# 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:

| Module | Put it on | Role |
|---|---|---|
| **MPP - Avatar Speed Controller** | One object of the scene (any object, even hidden) | Reads the chat, listens to the zones and the buttons, applies every speed change, sends the messages and sounds. **Always needed.** |
| **MPP - Avatar Speed Zone** | Trigger volumes (or objects visitors touch), as many as you like | Asks the Controller for a change when an avatar enters. Optional. |

---

## 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:

| Command (default) | Effect |
|---|---|
| `/speedhelp` (`Chat/Help Command`) | Sends the list of active commands, the allowed range and the scope (LOCAL or GLOBAL), in private |
| `/speedup` (`Chat/SpeedUp Command`) | Multiplies the SpeedFactor by `Speed/Step Coefficient`, up to `Max SpeedFactor` |
| `/speeddown` (`Chat/SpeedDown Command`) | Divides it by `Step Coefficient`, down to `Min SpeedFactor` |
| `/speedreset` (`Chat/Reset Command`) | Back to the SpeedFactor the avatar had before its first change (usually 1) |
| `/speedset 1.25` (`Chat/Set Command`) | Sets the SpeedFactor directly, comma or dot accepted, kept inside the range |

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

---

## Speed Range and Steps

| Setting | Default | What it does |
|---|---|---|
| Speed/Min SpeedFactor | 0.2 | Lowest SpeedFactor the script applies |
| Speed/Max SpeedFactor | 8 | Highest SpeedFactor the script applies. **Sansar only accepts 0.1 to 4**: the default 8 is lowered to 4 (a Debug line says so), any other value above 4 gets a warning |
| Speed/Step Coefficient | 2 | Factor of `/speedup` and `/speeddown`. Use a value above 1; a value between 0 and 1 is used as its inverse |

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:

| Access/Permission Mode | Allowed |
|---|---|
| **1** - Owner only | The scene owner |
| **2** - Owner + Whitelist (default) | The scene owner and the avatars of `Access/Whitelist` (empty list = owner only) |
| **3** - Everyone except Blacklist | Everyone, minus the avatars of `Access/Blacklist` (empty list = everyone) |

- 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:

| Setting | Default | What it does |
|---|---|---|
| Zone/Enable Zone | On | Off = the zone ignores collisions |
| Zone/Controller Event Message | "MPPAvatarSpeedzone" | Must match `Events/Zone Event Message` on the Controller. Empty = the zone sends nothing |
| Zone/Zone Action (1-4) | 1 | **1** SpeedUp, **2** SpeedDown, **3** Reset, **4** Set (to Set Value) |
| Zone/Set Value | 1 | SpeedFactor applied by action 4, kept inside the Controller's range |
| Debug/Debug Logging | Off | Writes each avatar detected and each event posted |

- 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`):

| Event (default name) | Effect |
|---|---|
| `mpp_speed_help` | Sends the help text in private to the activating avatar |
| `mpp_speed_up` | SpeedUp for that avatar (or everyone, in global mode) |
| `mpp_speed_down` | SpeedDown |
| `mpp_speed_reset` | Reset |
| `mpp_speed_set` | Set to `Events/Event Set Value` (default 1), kept inside the range |

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

| Setting | Default | What it does |
|---|---|---|
| Messages/Show Welcome Message | On | Each arriving avatar receives `Messages/Welcome Message` in private; `{HELP}` becomes the help command. Empty message = nothing |
| Messages/Show Speed Messages | On | The avatar reads its new SpeedFactor in private ("SpeedFactor set to 2.00"), or the "already at maximum / minimum" line; in global mode, the trigger avatar reads the summary |
| Sound/Enable Sounds | Off | Plays the sounds below when a change applies: at the avatar (heard nearby) in local mode, once for the whole scene in global mode |
| Sound/SpeedUp, SpeedDown, Reset, Set Sound | (none) | One optional sound per action; the Reset sound also plays at the end of a boost |
| Sound/Sound Volume | 100 | 0 to 200 percent for all the sounds (0 = no sound) |

---

## Editor Properties Reference (37 + 5)

### Controller - Activation
| Property | Type | Default | Description |
|---|---|---|---|
| Activation/Cooldown Seconds | number | 1 | Wait per avatar after a change (chat and events; zones ignore it). 0 = none, 0.1 s safety kept |
| Activation/Cooldown Notice | bool | On | Private "please wait" for a refused command |
| Activation/Cooldown Notice Text | string | "Please wait {time} before using another speed command." | Its text; `{time}` `{seconds}` replaced; empty = silent |
| Activation/Boost Duration Seconds | number | 0 | Changes wear off after this delay; 0 = Off |

### Controller - Speed
| Property | Type | Default | Description |
|---|---|---|---|
| Speed/Min SpeedFactor | number | 0.2 | Lowest applied value (0.1 at least) |
| Speed/Max SpeedFactor | number | 8 | Highest applied value (4 at most: Sansar's limit) |
| Speed/Step Coefficient | number | 2 | Factor of SpeedUp / SpeedDown |
| Speed/Apply To All Users | bool | Off | On = every change applies to everyone, allowed avatars only trigger |

### Controller - Access (global mode only)
| Property | Type | Default | Description |
|---|---|---|---|
| Access/Permission Mode (1-3) | int (1-3) | 2 | 1 = Owner only, 2 = Owner + Whitelist, 3 = Everyone except Blacklist |
| Access/Whitelist | string | "" | Handles or UUIDs for mode 2 |
| Access/Blacklist | string | "" | Handles or UUIDs for mode 3 |
| Access/Denied Text | string | "You are not allowed to use global speed changes." | Private refusal, at most every 5 s; empty = silent |

### Controller - Chat
| Property | Type | Default | Description |
|---|---|---|---|
| Chat/Enable Chat Commands | bool | On | Reads the commands below |
| Chat/Chat Channel | int | -1 | -1 = Nearby Chat |
| Chat/Help Command | string | "/speedhelp" | Help in private; empty = off |
| Chat/SpeedUp Command | string | "/speedup" | Empty = off |
| Chat/SpeedDown Command | string | "/speeddown" | Empty = off |
| Chat/Reset Command | string | "/speedreset" | Empty = off |
| Chat/Set Command | string | "/speedset" | Followed by a value; empty = off |

### Controller - Events
| Property | Type | Default | Description |
|---|---|---|---|
| Events/Zone Event Message | string | "MPPAvatarSpeedzone" | Shared with the zones; empty = zones ignored |
| Events/Enable Script Events | bool | On | Listens to the five events below |
| Events/Help Event Name | string | "mpp_speed_help" | Empty = off |
| Events/SpeedUp Event Name | string | "mpp_speed_up" | Empty = off |
| Events/SpeedDown Event Name | string | "mpp_speed_down" | Empty = off |
| Events/Reset Event Name | string | "mpp_speed_reset" | Empty = off |
| Events/Set Event Name | string | "mpp_speed_set" | Empty = off |
| Events/Event Set Value | number | 1 | Value applied by the Set event |

### Controller - Sound
| Property | Type | Default | Description |
|---|---|---|---|
| Sound/Enable Sounds | bool | Off | Plays the sounds below |
| Sound/SpeedUp Sound, SpeedDown Sound, Reset Sound, Set Sound | SoundResource | (none) | One per action |
| Sound/Sound Volume | number, 0-200 | 100 | Loudness in percent (0 = no sound) |

### Controller - Messages
| Property | Type | Default | Description |
|---|---|---|---|
| Messages/Show Welcome Message | bool | On | Private welcome for each arriving avatar |
| Messages/Welcome Message | string | "Welcome! Type {HELP} to see speed commands." | `{HELP}` = the help command |
| Messages/Show Speed Messages | bool | On | Private value / limit messages, global summary |

### Controller - Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Debug/Debug Logging | bool | Off | Writes changes, refusals (access, cooldown, limits) and the SpeedFactor read from Sansar to the script console |

### Zone
| Property | Type | Default | Description |
|---|---|---|---|
| Zone/Enable Zone | bool | On | Off = ignores collisions |
| Zone/Controller Event Message | string | "MPPAvatarSpeedzone" | Must match the Controller |
| Zone/Zone Action (1-4) | int (1-4) | 1 | 1 SpeedUp, 2 SpeedDown, 3 Reset, 4 Set |
| Zone/Set Value | number | 1 | Value for action 4 |
| Debug/Debug Logging | bool | Off | Writes detections and events posted |

---

## Version Notes

| Version | What changed |
|---|---|
| V1.0 - V1.1 | Chat commands, speed zones, sounds, timed boost, global mode with UUID lists |
| V1.2 | Script Events for MPP - Action Button (help, up, down, reset, set), cooldown only when a change applies. Sold until V1.3.2 |
| V1.3.0 | Speed kept inside Sansar's 0.1 to 4 with "already at maximum / minimum" messages; comma or dot in `/speedset`; Cooldown Notice; zones no longer slowed by the cooldown; global mode: no answer to ordinary chat, refusal at most every 5 s, one summary and one sound; one return after a timed boost; handles in the lists; Volume 0 silent; help lists only the active commands; settings grouped; warnings at start |
| V1.3.1 | Permission Mode as a number (never sold) |
| **V1.3.2** (this version) | `Access/` group with `Permission Mode (1-3)`, `Whitelist`, `Blacklist` and a `Denied Text` setting; `Zone/Zone Action (1-4)` as a number; groups `Activation/`, `Speed/`, `Sound/`; `Enable Script Events`; modules named "MPP - Avatar Speed Controller" and "MPP - Avatar Speed Zone" |

### 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

| Symptom | Check |
|---|---|
| Commands do nothing | Typed alone in Nearby Chat? `Chat/Enable Chat Commands` On, `Chat Channel` -1? During the cooldown you get "please wait"; at the limit, "already at maximum" |
| `/speedup` stops at 4 | Sansar's limit: no script can go higher |
| Zones do nothing | A Controller in the scene? The zone has a RigidBody (trigger volume or contact)? `Controller Event Message` = `Events/Zone Event Message`? `Zone Action` 1 to 4? Turn the zone's `Debug Logging` On: "Posted event ..." must appear |
| All my zones became SpeedUp after the update | `Zone/Zone Action (1-4)` starts at 1: set 2, 3 or 4 again (see "Updating from V1.2") |
| Global mode: my visitor cannot trigger anything | `Access/Permission Mode` (2 by default = owner + Whitelist): add the handle, or set 3. The visitor reads the `Denied Text` at most every 5 s |
| Global mode: a zone does nothing for visitors | Only an allowed avatar entering the zone triggers a change, for everyone |
| The boost never ends | `Activation/Boost Duration Seconds` 0 = Off. A Reset also cancels the pending return |
| No sound | `Sound/Enable Sounds` On, a sound assigned for that action, `Sound Volume` above 0? |
| Settings look different after updating | Labels in groups; two values to set again (see "Updating from V1.2") |

---

## 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

| Item | What it adds |
|---|---|
| **Action Button Script** (V1.7.1) | Speed buttons with `mpp_speed_up`, `mpp_speed_down`, `mpp_speed_reset`, `mpp_speed_set` and `mpp_speed_help`. Store: https://www.sansar.com/store/listings/3e1a3546-6c79-4527-bc1e-78d02648d19e/action-button-script |
| **Commands Help On Chat Script** (V1.5.2) | List your speed commands in its help text for visitors. Store: https://www.sansar.com/store/listings/fea2df6b-21ce-48eb-94fc-4b7a7aad2777/commands-help-on-chat-script |

---

*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*