MPP - Avatar Speed Package V1.3.2 - Documentation

Controls how fast avatars move in your experience: by Nearby Chat commands (/speedup, /speeddown, /speedreset, /speedset 1.5), by speed zones they walk into, or by Script Events from an MPP - Action Button. For each visitor alone, or for everyone at once with an access control. Optional timed boosts that wear off, sounds, private messages and a help command. Two scripts delivered as one asset: the Controller, one per scene, and optional Zones.

This package is standalone - it does not require any other MPP script to function.

New in V1.3: the speed stays inside the range Sansar really applies (0.1 to 4), so the script never announces a speed the avatar does not get, and a visitor at the limit reads "already at maximum"; /speedset 0,5 and /speedset 0.5 both work; a private "please wait" message for a command that comes too soon; zones no longer slowed by the cooldown (a Reset zone right after a SpeedUp zone works); in global mode an ordinary sentence gets no answer, a refused command a private message, and the person who triggers one summary; one clean return after a timed boost; avatar handles in the lists; Volume 0 silent; settings grouped by category. V1.3.2 uses the access scheme shared by every MPP script (Access/Permission Mode (1-3)) and a numeric Zone Action (1-4). Two settings of V1.2 are not carried over: read "Updating from V1.2" before you update a Controller or Zones already placed in a scene.

What You Get

The asset holds two script modules. When you add the script to an object, Sansar asks which module to use:

Quick Start

1. Add the Controller module to any object. The defaults already work: visitors type /speedup, /speeddown, /speedreset or /speedset 1.5 in Nearby Chat and change their own speed; /speedhelp lists the commands; each arriving visitor gets a private welcome line.
2. Optional: make a trigger volume (a box with a RigidBody set to Trigger Volume), add the Zone module to it, choose Zone/Zone Action (1-4): 1 SpeedUp, 2 SpeedDown, 3 Reset, 4 Set (to Zone/Set Value).
3. Optional: Activation/Boost Duration Seconds 20 turns every change into a boost that wears off after 20 seconds.

The rest of this guide details every option.

How It Works

Every request, whatever its source, goes through the Controller:

1. Global mode only: is this avatar allowed to change everyone's speed? (Access/Permission Mode). If not, a private Denied Text and nothing else.
2. Cooldown: chat commands and Script Events wait Activation/Cooldown Seconds after the avatar's last change (private "please wait"). Zones only wait a tenth of a second.
3. Apply: the new SpeedFactor is computed and kept inside Min SpeedFactor to Max SpeedFactor, themselves inside the 0.1 to 4 that Sansar accepts. An avatar already at the limit reads "SpeedFactor is already at maximum (4.00)." (command or button; zones stay silent). A change that changes nothing starts no cooldown, plays no sound.
4. Feedback: private message with the new value (or one summary in global mode), sound, and the timed boost countdown if Boost Duration Seconds is set.

In the Build panel the Controller settings are grouped by category: Activation/, Speed/, Access/, Chat/, Events/, Sound/, Messages/ and Debug/. The Zone has Zone/ and Debug/.

Chat Commands

Chat/Enable Chat Commands (default On) reads Nearby Chat (Chat/Chat Channel -1; another number listens on that channel). Commands are typed alone, case ignored:

Empty a command to disable it; /speedhelp then no longer lists it.

Speed Range and Steps

With the defaults, /speedup gives 2, then 4, then "already at maximum (4.00)".

Local or Global

Speed/Apply To All Users (default Off):

• Off - local: a command, a button or a zone changes the speed of the avatar who used it, and nobody else. Every visitor can use the commands.
• On - global: every change applies to every avatar present, and only allowed avatars can trigger one. The trigger avatar receives one summary ("Global SpeedUp applied to 5 avatar(s)."), one sound plays for the whole scene, and an ordinary sentence from a visitor gets no answer.

Who may trigger global changes: Access/Permission Mode (1-3), the scheme shared by every MPP script:

• The scene owner is always allowed. A list the mode does not use gets a warning at start.
• Access/Whitelist and Access/Blacklist: avatar handles or UUIDs, separated by commas or semicolons (@ and case ignored). Old lists of UUIDs separated by spaces still work; the other words of such an entry are ignored with a warning.
• Access/Denied Text (default "You are not allowed to use global speed changes."): private message to a visitor who is not allowed, at most once every 5 seconds. Empty = silent.
• Local mode ignores these settings entirely.

Zones

Put the Zone module on a trigger volume (a box with a RigidBody set to Trigger Volume), or on an object visitors touch (a normal collider: contact mode). When an avatar's body enters (VR hands are ignored), the zone asks the Controller for its action:

• Zones are not slowed by Cooldown Seconds: only a tenth of a second separates two zone changes for the same avatar, so a Reset gate right after a boost gate works. A zone never sends a "please wait" or "already at the limit" message.
• In global mode, a zone acts only when an allowed avatar enters it, and then changes everyone; other avatars get nothing, without a message.
• Leaving a zone does nothing: use a second zone (Reset, or SpeedDown) at the exit.
• A zone without a RigidBody, with an empty event message or an action outside 1 to 4 writes a warning at start and sends nothing.

Script Events (buttons and your own scripts)

With Events/Enable Script Events On (default), the Controller listens to five Script Events, meant for MPP - Action Button (Send as Command On) or any script that sends the same data (an object with a text property ActivatorAvatarUuid):

Events follow the same rules as chat commands: the cooldown with its notice, the permission in global mode, the limit message. A two-state Action Button (Command 1 = mpp_speed_up, Command 2 = mpp_speed_reset) makes a boost switch.

Events/Zone Event Message (default "MPPAvatarSpeedzone") is the private channel between the Controller and its zones: change it only if you change it on every zone. Empty = zones ignored.

Cooldown and Notice

Activation/Cooldown Seconds (default 1) is the wait per avatar after a change before its next chat command or Script Event is accepted. A silent tenth of a second remains at 0.

With Activation/Cooldown Notice On (default), a command that comes too soon gets a private message, at most once every 3 seconds: by default "Please wait 1 second before using another speed command." Write your own text in Activation/Cooldown Notice Text: {time} becomes the remaining time with its unit, {seconds} the whole number of seconds. Empty text, or the notice Off, = silent.

Timed Boost

Activation/Boost Duration Seconds (default 0 = Off): when set, every SpeedUp, SpeedDown or Set is undone after that many seconds, back to the speed the avatar had before its first change. A new change restarts the countdown (one return only, at the end), and a Reset cancels the pending return. In global mode one countdown serves everyone.

Messages and Sounds

Editor Properties Reference (37 + 5)

Controller - Activation

Controller - Speed

Controller - Access (global mode only)

Controller - Chat

Controller - Events

Controller - Sound

Controller - Messages

Controller - Debug

Zone

Version Notes

Updating from V1.2

Before you update, take a screenshot of the Build panel of the Controller and of one Zone of each action. Two settings are replaced by new ones and their values are not carried over.

• Your other values carry over: commands, range, step, cooldown, boost, both lists, event names, messages, sounds and volume keep their internal names and their values, in new groups. Check after the update that the Controller object still runs the Controller module and each zone the Zone module.
• Global Permission Mode (text) is replaced by Access/Permission Mode (1-3), which starts at 2 = Owner + Whitelist: OwnerOnly becomes 1, OwnerAndWhitelist 2 (nothing to do), OwnerAndBlacklist 3. Global Admin Whitelist is now Access/Whitelist, Global Excluded Blacklist is Access/Blacklist; their values are kept, and they now accept handles.
• Zone Action (text) is replaced by Zone/Zone Action (1-4), which starts at 1 = SpeedUp on every zone: set 2 for a SpeedDown zone, 3 for a Reset zone, 4 for a Set zone.
• Three new settings at their defaults: Activation/Cooldown Notice (On), Activation/Cooldown Notice Text, Access/Denied Text (the same text V1.2 sent).
• What behaves differently: values above 4 are no longer announced (Sansar stops at 4); a command during the cooldown gets a private "please wait" (turn Cooldown Notice Off for the V1.2 silence); zones ignore the cooldown; in global mode an ordinary sentence gets no answer and the trigger avatar reads one summary; Sound Volume 0 is silent; a lone word in an old list is now read as a handle.

Recipes

A - Free speed for everyone. Controller defaults. Visitors use /speedup and /speeddown; /speedhelp tells them the range.

B - Parkour with boost pads. Zones with Zone Action 1 (SpeedUp) on the pads, a zone with Zone Action 3 (Reset) at the finish line. Activation/Boost Duration Seconds 10 for boosts that wear off.

C - Slow zone. A zone with Zone Action 4 and Set Value 0.5 over the mud, a Reset zone at its exit.

D - Boost button. An MPP - Action Button with Send as Command On, Command Count 2, Command 1 = mpp_speed_up, Command 2 = mpp_speed_reset.

E - Race master. Speed/Apply To All Users On, Access/Permission Mode 2 with the referees' handles in Whitelist: /speedset 3 sets everyone to 3, /speedreset brings everyone back.

F - Silent gameplay. Messages/Show Speed Messages Off, Show Welcome Message Off, Cooldown Notice Off: the speed changes without a word.

Troubleshooting

Limits

• Sansar applies SpeedFactors from 0.1 to 4 only; Max SpeedFactor above 4 is lowered to 4.
• If another script changes an avatar's speed, the Controller only notices it at the next command, and a command that would restore the last value the Controller wrote does nothing.
• In global mode, an allowed avatar running back and forth between two zones can change everyone's speed up to ten times a second.
• Leaving a zone does nothing by itself.

Related MPP Items

MPP - My Pretty Pixels. Avatar Speed Package V1.3.2 (modules MPP - Avatar Speed Controller and MPP - Avatar Speed Zone). Store: https://www.sansar.com/store/listings/18c6ce0a-4900-4f74-88fd-76d56d7fc649/avatar-speed-package-script