MPP - Rotator Script V1.0.3 - Documentation

Turns the object it is on: a ceiling fan, a windmill, a planet, a sign, a door, a radar dish, a floating crystal. Around one axis or several at once, around the object's own axes or the world axes, without end or by a set number of degrees per axis, one way, there and back, or back and forth with a pause at each end. It starts when the scene loads, on a click, when an avatar touches the object, or on a Script Event from another script, and it tells other scripts when it starts, stops and reaches each end of its path.

This script is standalone - it does not require any other MPP script to function. It works with MPP - Action Button (a button that starts, stops, reverses or brings the object back) and with any MPP script that listens to Script Events, such as MPP - Light Switch.

First release on the Store (V1.0.3). The motion is computed by the Sansar server and interpolated for every visitor, so it stays smooth whatever their connection, and an object that is stopped resumes exactly where it was. The object can be carried or moved by another script (an MPP - MyMood item that follows its avatar, for example): the rotation resumes from wherever the object now stands.

Quick Start

1. In Build mode, select the object and tick Movable from Script in its properties. If the object has physics, set it to Keyframed (a Static or Dynamic body cannot be turned by a script: the script says so in the script console and does nothing).
2. After purchase, the script is in your Inventory. Add it to the object, build and visit: the object turns around its vertical axis (Z), one full turn every 8 seconds.
3. Change Rotation/Seconds Per Turn for the speed, tick Rotation/Reverse Z for the other way, or turn on Rotation/Axis X or Axis Y instead of, or in addition to, Z.

That is all a fan or a planet needs. The rest of this guide details every option.

How It Works

Two kinds of motion, chosen by the Rotation/Degrees X, Degrees Y and Degrees Z settings:

Four ways to start and stop it:

Clicks, collisions and the events that carry an avatar go through the access control (Access/Permission Mode (1-3)) and, for clicks and collisions, the per-avatar cooldown.

In the Build panel the settings are grouped by category: Activation/, Rotation/, Access/, Events/, Sound/ and Debug/.

Axes and Direction

• Rotation/Axis X, Axis Y, Axis Z: the axes the object turns around. Z is the vertical axis of Sansar (default On). Several axes can be On at once: the object then tumbles, the rotations composing X, then Y, then Z.
• Rotation/Reverse X, Reverse Y, Reverse Z: run that axis the other way. Ignored when the axis is Off.
• Rotation/Local Axes (On): the axes are those of the object itself, as it is placed and tilted in the scene. A tilted fan keeps turning around its own hub. Off: the axes are the X, Y and Z of the world, whatever the tilt of the object.

If no axis is On, the script warns in the script console and does nothing.

Speed

Rotation/Seconds Per Turn (default 8, minimum 0.5) is the time of one full turn when the object turns without end, and the time to go from the start pose to the end pose when degrees are set. The same value serves both cases, so a 720 degree path with 8 seconds takes 8 seconds, not 16.

A very fast setting (a large number of degrees in a short time) is slowed down by the script so the motion stays smooth, with a warning in the script console that gives the value used. Lower the degrees or raise the seconds to keep your own value.

A Path With Degrees

Give degrees to one or several enabled axes: Rotation/Degrees X, Degrees Y, Degrees Z. Each enabled axis turns by its own degrees, and every axis reaches its end at the same moment. An enabled axis left at 0 while another has degrees does not turn. Degrees can be above 360 (720 = two turns).

Rotation/Path Mode (1-3) sets what happens at the end pose:

• Rotation/Pause Seconds (default 0): how long the object waits at an end of the path before it comes back, in modes 2 and 3.
• Rotation/Motion Mode (1-4) (default 2): the shape of each leg. 1 = constant speed, 2 = smooth start and stop, 3 = ease in (slow start, fast end), 4 = ease out (fast start, slow end). A rotation without end is always at constant speed.

A stopped object keeps its place on the path: click again and it continues from there, toward the end it was heading to. At an end pose, a start goes toward the other end.

Starting and Stopping

Scene load

Activation/Start On Load (On): the object turns as soon as the scene is ready. Off: it waits for a click, a touch or a Script Event.

Click

Activation/Enable Click (Off): the object highlights on hover and shows Activation/Hover Text When Stopped ("Start") or Hover Text When Turning ("Stop"). Empty texts = highlight only. A click toggles: it stops a turning object (also during a pause at an end), and starts a stopped one.

• Activation/Cooldown Seconds (default 0, 0 to 600): a visitor who clicks again within this time is ignored. A silent 0.1 second anti double-click safety always remains.
• Activation/Cooldown Notice (On): the ignored visitor receives a private message, by default "Please wait {time} before using this object again." ({time} = the remaining time with its unit, {seconds} = the whole seconds). At most one message every 3 seconds per visitor. Empty text, or the notice Off, = silent.

Collision

Activation/Use Collision (Off): an avatar touching the object toggles it like a click, at most once per second per avatar, so an avatar leaning on a turning object does not make it flicker. The object needs a rigid body (Keyframed). For a trigger volume, entering the volume counts. The Cooldown Seconds and the access control apply too.

Script Events

See "Script Events" below: _start, _stop, _toggle, _reverse and _return.

If Start On Load, Enable Click, Use Collision and Enable Script Events are all Off, nothing can ever start the object: the script warns in the script console.

Access

Who may start or stop the object by click, touch or event follows Access/Permission Mode (1-3):

The scene owner is always allowed, in every mode. The lists take avatar handles (the name in the profile link, https://www.sansar.com/profiles/<handle>) or avatar UUIDs, separated by commas or semicolons; @ and letter case are ignored. A display name with a space is ignored with a warning.

• Access/Denied Text: private message to an avatar who clicks or touches without being allowed (default "You are not allowed to use this object."), at most once every 5 seconds; empty = silent.
• Access/Hide From Denied (Off): in click mode, the avatars who are not allowed do not see the object as clickable at all (no highlight, no hover text). The check on click stays active.

Start On Load is not subject to the access control: it is the scene itself that starts the object.

Script Events

Everything goes through one name, Events/Script Event Prefix (default mpp_rotator). Two rotators with different prefixes are controlled separately; two with the same prefix move together.

Events the object listens to

With Events/Enable Script Events (On):

Set an MPP - Action Button to "Send as Command" with one of these names: a control desk with Start, Stop and Reverse buttons takes three buttons.

Events/Use Click Permission (On): an event that carries the avatar who pressed the button (every MPP button does) is checked against Permission Mode like a click, the owner always allowed; an event without an avatar (a timer, a scheduler) is accepted in mode 3 only. Off: every event is accepted, with or without an avatar.

Events the object sends

With Events/Send Script Events (Off):

The events carry the avatar who started the object (empty when the scene started it), so an MPP - Light Switch set to the same prefix lights a lamp while the object turns, and any MPP script that listens to Script Events can follow.

Sounds

Three optional sounds, all played at the object with Sound/Sound Volume (0 to 200 percent, 100 = the original volume, 0 = no sound):

• Sound/Start Sound: once, when the object starts turning.
• Sound/Turning Sound: in a loop while the object turns (a motor hum, wind in the blades), stopped with a short fade when it stops or pauses at an end of the path.
• Sound/Stop Sound: once, when the object stops, by a click, an event or the end of the path.

The sounds play on the object's audio emitter when it has one, else at the object's position.

Editor Properties Reference (36 total)

Activation

Rotation

Access

Events

Sound

Debug

Version Notes

Recipes

A - The ceiling fan. Defaults, Seconds Per Turn 2, a hum in Sound/Turning Sound. Tick Reverse Z if the blades turn the wrong way for their shape.

B - The slow planet. Tilt the object in the scene, Local Axes On, Seconds Per Turn 120: it turns around its own tilted pole.

C - The door. Degrees Z 90, Seconds Per Turn 2, Path Mode (1-3) 1, Motion Mode (1-4) 2, Start On Load Off, Enable Click On, Hover Text When Stopped "Open / Close", a creak in Start Sound and a thud in Stop Sound. The hinge side of the door must be the object's pivot. Each click opens or closes.

D - The pendulum or radar sweep. Degrees X 60 (or Degrees Z for a radar), Seconds Per Turn 2, Path Mode 3, Pause Seconds 0.5, Motion Mode 2: it swings without end.

E - The control desk. Three MPP - Action Buttons set to "Send as Command" with mpp_rotator_start, mpp_rotator_stop and mpp_rotator_reverse; Start On Load Off on the rotator. Add mpp_rotator_return for a "home" button.

F - The tumbling crystal. Axis X, Axis Y and Axis Z On, every Degrees at 0, Seconds Per Turn 20, Reverse Y On for a less regular pattern.

G - The windmill you can stop. Defaults plus Use Collision On on a Keyframed body: touch the wheel to stop it, touch it again to start it, once per second at most.

H - Two doors that open together. The same Script Event Prefix (door_hall) on both rotators, one Action Button sending door_hall_toggle.

Troubleshooting

Limits

• The object must be Movable from Script. With a rigid body, only a Keyframed one follows the rotation; a Static or Dynamic body is refused.
• The script turns the object in place: it does not move it along, and does not scale it.
• Seconds Per Turn cannot go under 0.5; very fast paths are slowed down with a warning so the motion stays smooth.
• The start pose is the object's pose in the scene. A stopped object resumes from where it stopped; a scene restart puts it back at its start pose.
• When another script moves or turns the object, the rotation resumes within a second from the object's new pose, which becomes its new start pose: a path with degrees then measures its ends from there.
• A Script Event without an avatar (sent by a script that is not an MPP button) is accepted only when Use Click Permission is Off or Permission Mode is 3.

Related MPP Items

MPP - My Pretty Pixels. Rotator Script V1.0.3 (script MPP - Rotator). Store: https://www.sansar.com/store/listings/89d478b4-0897-4f94-a690-4bf992e138da/rotator-script