# MPP - Auto Megaphone Package V1.5.1 - Documentation Automatic **Megaphone** control for your experience: switch the Sansar Megaphone (the voice mode heard by everyone in the experience) on or off for your visitors when they arrive, when they enter or leave a zone, when they touch an object, or when someone presses a button. Two scripts delivered as one asset: the **Policy**, which decides who and when, and optional **Zones**, trigger volumes that ask the Policy for a change. This package is **standalone** - it does not require any other MPP script to function. It works with **MPP - Action Button** for buttons (Megaphone on/off for yourself, or for everyone). **New in V1.5:** the latest request always wins, visitor by visitor: a request that arrives during the cooldown is kept and applied when the cooldown ends, and requests of the same instant (a visitor stepping back and forth on a zone edge) count as one, so no more bursts of public messages. The state remembered for a visitor follows Sansar's answers, so a refused change never leaves a wrong state. "... is no longer in Megaphone mode" is only announced for a visitor the Policy had turned on. All On / All Off send one summary instead of a copy per visitor. The lists accept avatar handles as well as UUIDs. VR hands are ignored by zones. Warnings in the script console for inconsistent settings. Settings grouped by category. V1.5.1 renames labels and groups and names the modules "MPP - Auto Megaphone Policy" and "MPP - Auto Megaphone Zone". Your settings are kept when you update: see "Updating from V1.4.4". --- ## 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 - Auto Megaphone Policy** | One object of the scene (any object, even a hidden one) | The controller: applies the rules (who is affected, cooldown, messages) and makes every Megaphone change. **Always needed.** | | **MPP - Auto Megaphone Zone** | Trigger volumes, as many as you like | Asks the Policy to switch Megaphone on or off when an avatar enters or leaves the volume. Optional. | Zones never change Megaphone themselves: they send a request to the Policy, which checks it against its rules. One Policy per scene is enough for any number of zones. --- ## Quick Start **A - Megaphone for everyone as soon as they arrive.** Add the Policy module to any object. The defaults do it: `Auto Triggers/On Join Action` 1 (On), `Targets/Target Mode` 0 (everyone), a public message "Name is now in Megaphone mode." Nothing else to set. **B - Megaphone only on a stage.** On the Policy, set `Auto Triggers/On Join Action` to 2 (Off) so everyone starts silent. Make a trigger volume over the stage (a box with a RigidBody set to Trigger Volume), add the Zone module to it, keep `Zone/On Enter Action` 1 (On) and `Zone/On Exit Action` 2 (Off). Whoever steps on the stage is heard everywhere; whoever steps off is not. **C - A silent room.** Keep the Policy defaults (Megaphone on at arrival) and put a Zone on the room with `On Enter Action` 2 (Off) and `On Exit Action` 1 (On). The rest of this guide details every option. --- ## How It Works Every Megaphone change, whatever asks for it, goes through the same gate in the Policy, **visitor by visitor**: 1. **Enabled**: with `Activation/Enabled` Off, the Policy changes nothing at all. 2. **Target Mode**: is this visitor affected? (`Targets/Target Mode`, with the Whitelist or the Blacklist). 3. **Once per session**: for the join and the collision only, if `Auto Triggers/Once Per Avatar Per Session` is On and this visitor was already served. 4. **Already in that state**: a request for the state the visitor already has does nothing and starts no cooldown. 5. **Queue**: the request waits a tenth of a second, or until the visitor's cooldown ends, then the **latest** request received for that visitor is applied. Earlier ones are replaced, never lost. 6. **Change and messages**: the Megaphone is switched, then the private and public messages of `Messages/Message Mode` are sent. If Sansar refuses the change (too many changes at once, visitor gone), the state remembered for the visitor stays right, the next request works, and `Messages/Notify On Failure` can tell the visitor. In the Build panel the Policy settings are grouped by category: `Activation/`, `Targets/`, `Auto Triggers/`, `Messages/`, `Events/` and `Debug/`. The Zone has `Zone/` and `Debug/`. --- ## Behavior Mode `Activation/Behavior Mode (0-2)` chooses which sources the Policy listens to: | Mode | Auto Triggers (join, collision, leave) | Zones | |---|---|---| | **0** - PolicyOnly | Yes | Ignored | | **1** - ZoneOnly | Ignored | Yes | | **2** - Hybrid (default) | Yes | Yes | Script Events (buttons) work in every mode. `Activation/Enabled` Off stops everything, zones and buttons included. --- ## Targets - Who Is Affected `Targets/Target Mode (0-6)` says which visitors the Policy may switch. It is not an access control on the zones or buttons: a visitor who is not targeted is simply left alone by every source. | Mode | Who is affected | |---|---| | **0** - Everyone (default) | All visitors, the scene owner included | | **1** - Everyone except the owner | All visitors but the scene owner | | **2** - Owner only | The scene owner only | | **3** - Whitelist only | The avatars of `Targets/Whitelist` | | **4** - Owner and Whitelist | The scene owner and the avatars of `Targets/Whitelist` | | **5** - Everyone except the Blacklist | All visitors but the avatars of `Targets/Blacklist` | | **6** - Owner and everyone not blacklisted | The scene owner (even if listed) and all visitors but the avatars of `Targets/Blacklist` | **Lists.** `Targets/Whitelist` and `Targets/Blacklist` take avatar **handles** or avatar **UUIDs**, separated by commas or semicolons. Handles are not case sensitive and a leading `@` is ignored. Display names are not accepted (Sansar does not guarantee them unique). A list of V1.4.4 with UUIDs separated by spaces still works: every UUID of such an entry is read, the other words are ignored with a warning. Example: `@morgane, friend-handle; 3f2c1a9e-0000-4c1e-9a55-1234567890ab`. Tip: turn `Debug/Debug Logging` On on the Policy: every request shows the visitor's handle and UUID in the script console, ready to paste. Mode 3 or 4 with an empty Whitelist gets a warning at start (nobody, or only the owner, is affected). --- ## Auto Triggers The Policy can act on its own, without zones (Behavior Mode 0 or 2): | Setting | Default | What it does | |---|---|---| | Auto Triggers/On Join Action (0-2) | 1 (On) | When a visitor enters the scene: 0 nothing, 1 Megaphone on, 2 Megaphone off | | Auto Triggers/On Collision Action (0-2) | 0 (None) | When a visitor touches the **Policy object** itself: 0 nothing, 1 on, 2 off. The object needs a RigidBody (a trigger volume reacts on entry, a normal collider on contact). Most scenes use Zones instead | | Auto Triggers/On Leave Action (0-2) | 0 (None) | When a visitor leaves the scene. Kept for compatibility: the visitor is usually already gone when Sansar reports the departure, so it rarely does anything, and it sends no message | | Auto Triggers/Once Per Avatar Per Session | On | The join and the collision act at most **once per visitor and per visit**, and they share that one time: a visitor switched on at arrival is not switched again by the collision. Zones and buttons are never limited by this | With `Once Per Avatar Per Session` On, `On Join Action` and `On Collision Action` both active get a warning at start: the join uses up the only application. --- ## Zones Put the **Zone** module on a trigger volume: an object with a RigidBody set to **Trigger Volume** (a simple box is enough). Each zone has its own settings: | Setting | Default | What it does | |---|---|---| | Zone/Enabled | On | Off = the zone does nothing | | Zone/Zone Label | "" | A name for this zone, shown in the `{source}` token and the console: `Stage`, `Lobby`, `SilentRoom` | | Zone/On Enter Action (0-2) | 1 (On) | When an avatar enters the volume: 0 nothing, 1 Megaphone on, 2 Megaphone off | | Zone/On Exit Action (0-2) | 2 (Off) | When an avatar leaves the volume: 0 nothing, 1 on, 2 off | | Debug/Debug Logging | Off | Writes each avatar detected and each request sent to the script console | - A zone needs a **Policy** in the scene, with `Activation/Behavior Mode` 1 or 2 (mode 0 ignores zones). - Zones only see the avatar's body: VR hands and the desktop grab point are ignored. - Overlapping zones: the last request received for a visitor wins (see "Cooldown"). - A zone without a RigidBody, or with a RigidBody that is not a trigger volume, writes a warning at start. --- ## Cooldown and Anti-Spam `Activation/Cooldown Seconds` (default 0, up to 120) is the minimum time between two Megaphone changes of the **same visitor**. - A request that arrives during the visitor's cooldown is **kept** and applied when the cooldown ends. Several requests during the cooldown: only the **latest** is applied. A visitor who steps on a stage then off it within the cooldown ends up off, with one change at the end of the cooldown. - Even with `Cooldown Seconds` at 0, the requests of the same instant are grouped: the Policy waits a tenth of a second before applying the latest one. A visitor going back and forth on a zone edge does not produce a burst of messages. - A request for the state the visitor already has does nothing and starts no cooldown. - If a change fails, no cooldown starts, and the next request goes through. --- ## Messages `Messages/Message Mode (0-3)` chooses the feedback sent at each change: | Mode | Private message to the visitor | Public message to everyone in the experience | |---|---|---| | **0** - None | - | - | | **1** - Private only | Yes | - | | **2** - Public only (default) | - | Yes | | **3** - Private and public | Yes | Yes | - `Messages/Private Message (On)` / `(Off)`: the private texts, default "Megaphone mode has been enabled for you." / "Megaphone mode has been disabled for you." - `Messages/Public Format (On)` / `(Off)`: the public texts, default "{name} is now in Megaphone mode." / "{name} is no longer in Megaphone mode." They go to **everyone in the experience** (public chat), not only to nearby avatars. Tokens: `{name}` = the visitor's display name, `{state}` = `on` or `off`, `{source}` = what asked for the change: `PolicyJoin`, `PolicyCollision`, `Zone: