MPP - Light Switch Script V1.5.3 - Documentation

Turns lights and glowing materials on and off on any object: by click, by Nearby Chat command, in sync with other lamps in the same group, or from another script (a scheduler, a button, your own trigger). Smooth fades, access by permission mode (owner only, owner + whitelist, everyone except a blacklist), works alone or as the receiving end of MPP - Day and Night Sky Cycle and MPP - Action Button.

This script is standalone - it does not require any other MPP script to function. It becomes useful together with a trigger: your own click, a chat command, an Action Button, or the Day Night scheduler.

New in V1.5: one anti-spam cooldown for every way of switching a lamp (the last command is never lost), a private "please wait" message for a click during the cooldown, access by avatar handle or UUID, a private message for denied visitors, the option to hide the switch from them, smoother long fades, and settings grouped by category in the Build panel.

New in V1.5.3: the transition mode is chosen by a number (Transition/Transition Mode (1-5), no name to type), the access control uses the scheme shared by every MPP script (Access/Permission Mode (1-3) with a Whitelist and a Blacklist), and the labels follow the MPP conventions (Hover Text, Enable Chat Commands, Enable Script Events). Two settings are not carried over from V1.5.1: the transition mode and the access. Read "Updating from V1.5.1" before you update lamps already placed in a scene.

Overview

Drag the script onto any object - a street lamp, a window, a neon sign, a whole building. On that object it can:

• Switch its Light components (the actual illumination: color and intensity).
• Switch its materials (an emissive glow, a tint), for objects without a real light or for combining both.
• Do either, both, or neither (Light/Affect Lights / Material/Affect Materials), on the same click.

The object has two states, ON and OFF, each with its own light color/intensity and material tint/emissive. Switching between them fades smoothly over Transition/Transition Seconds (0 = instant).

In the Build panel the settings are grouped by category: Activation/, Light/, Material/, Transition/, Access/, Chat/, Events/ and Debug/.

How It Works

Four independent ways to trigger a switch, all ending at the same ON/OFF state:

Group sync vs. External Events - not the same thing. These are two separate mechanisms that happen to both use the Group setting:

• Group sync (Events/Internal Group Events) is a private conversation between lamps running this script: when Activation/Click Syncs Group is On, clicking one lamp tells every other lamp with the same Group to toggle too. Other scripts cannot see or trigger this - it uses an internal event name (MPPLightSwitch:<group>:<action>).
• External Script Events (Events/Enable Script Events) is the public door: any script in the scene - Day Night, Action Button, or a script you write - can switch this lamp (or every lamp of a given group, or every lamp in the scene) by posting a plain, documented event name (mpp_lamp_<group>_<action>, see section "External Script Events" below).

A lamp can use one, both, or neither. They never conflict: a click can drive both the local group and be silent to the outside world, or vice versa.

Click

• Activation/Enable Click (default On) shows a hover text (Activation/Hover Text When ON / Hover Text When OFF, whichever matches the current state) and toggles on click. With Enable Click Off there is no click and no hover text at all; chat and Script Events still work.
• Activation/Click Syncs Group (default On): with Events/Internal Group Events also On, a click sends a toggle to the whole Group instead of only this object (see "Group Sync" below). Turn it Off to make this lamp react to its own click only, even if it has a Group set (useful when the lamp should still receive chat/external commands for its group, but not spread its own click).
• A click during the lamp's cooldown is ignored, whatever started the cooldown. For a wait of half a second or more, the avatar receives a private "please wait" message (see "Cooldown" below).
• An avatar who is not allowed receives a short private message (see "Access Control").

Cooldown (anti-spam)

Activation/Cooldown Seconds (default 0.25, 60 at most) is the minimum delay between two changes of a lamp, whatever the source: click, chat, group sync or another script.

• Clicks during the cooldown are ignored, as on a real switch, whatever started the cooldown (a click, a chat command, another lamp of the group or a script). A click that is accepted therefore always does what the hover text says.
• Chat commands, group sync and script events are never lost: if one arrives during the cooldown, the lamp waits for the end of the cooldown and then applies the last command it received. A burst of commands therefore changes the lamp at most once per cooldown, and the lamp always ends in the state that was asked last.
• Commands sent together count as one: the lamp waits a tenth of a second before switching, and only the last of the commands received meanwhile applies.
• A command for the state the lamp is already in (an on to a lamp that is on) changes nothing and does not start a cooldown.

Cooldown Notice. With Activation/Cooldown Notice On (default), an avatar whose click is ignored receives a private chat message, only visible to them, that tells how long to wait: by default "Please wait 2 seconds before using this switch again." At most one message every 3 seconds per avatar, and none when the wait is under half a second (the next click already works). Write your own text in Activation/Cooldown Notice Text: {time} becomes the remaining time with its unit ("2 seconds", "1 minute 5 seconds"), {seconds} the whole number of seconds. Leave the text empty, or turn the notice Off, for silent clicks. Chat commands and script events never get this message: they are kept and applied at the end of the cooldown.

Why it matters with Day Night: when the scene starts, and each time someone changes the season or the city, the Day Night scheduler replays the last 24 hours at once, so the lamps catch up with the time of day. It sends both commands together, for example sunrise | ..._off then sunset | ..._on at night. The lamp goes straight to the right state, without blinking, whatever Activation/Start On says.

0 turns the cooldown off: every command applies at once, with no delay and no anti-spam.

Chat Commands

Enabled by Chat/Enable Chat Commands (default On), with Chat/Chat Prefix (default /lamp). Channel: Nearby Chat (0).

/lamp <action>
/lamp <group> <action>
/lamp <group>
/lamp *  <action>

Chat/No-Group Targets All (default Off) decides what a groupless command (/lamp on, no group word) does: Off = it only reaches lamps whose own Group is empty; On = it reaches every lamp regardless of group. Either way, /lamp * always reaches everyone. The same setting applies to the groupless external events <prefix>_on / _off / _toggle (see "External Script Events").

Chat commands follow the same access rules as the click. An avatar who is not allowed gets no answer in chat (every lamp reads the chat, and each one would otherwise reply).

Group Sync

Give several lamps the same Activation/Group (for example street, case does not matter) and, with Activation/Click Syncs Group and Events/Internal Group Events both On (both default On), clicking any one of them toggles all of them together - a row of street lamps that light up as one.

Lamps with an empty Group form one click-sync group of their own: clicking one of them toggles all the other lamps that have no Group. To keep a lamp independent, turn Activation/Click Syncs Group Off, or give it a Group of its own. (A lamp with an empty Group still answers /lamp * in chat and the _all_ external events, see below.)

External Script Events

This is the integration point with Day Night Cycle, Action Button, and any script of your own. Enabled by Events/Enable Script Events (default On), with Events/Script Event Prefix (default mpp_lamp).

The script listens for these Script Event names (<prefix> = your Script Event Prefix):

With the defaults (mpp_lamp), a lamp in Group = Street answers mpp_lamp_street_on, mpp_lamp_all_on, and mpp_lamp_on only if Chat/No-Group Targets All is On (a lamp with an empty Group always answers it). Write the group part in lowercase: event names are matched exactly.

Any script can trigger these with PostScriptEvent("mpp_lamp_street_on", null). In practice you will mostly use:

• Action Button (Send as Command = On, Command 1 = mpp_lamp_all_toggle or mpp_lamp_<group>_on, etc.) - see that script's documentation.
• Day Night Cycle's Actions A/B scheduler - put lines like sunset | mpp_lamp_all_on and sunrise | mpp_lamp_all_off in Events/Actions A on the Control module. Full recipe in the Day Night documentation, section 9.
• Commands Help On Chat (V1.5 or later) - its arrival and departure events can switch a lamp when a visitor enters or leaves the scene: set its Arrival Event Name to mpp_lamp_all_on, for example.
• Your own script: SubscribeToScriptEvent on the receiving end, or simply PostScriptEvent the name above from anywhere.

Script events are not subject to the access rules (setting up a scheduler or a button is itself a Build-mode action), but they do follow the cooldown.

What Gets Switched - Lights

Light/Affect Lights (default On). Applies to every LightComponent on the object (or only the ones named in Light/Light Names, comma-separated - empty means all). A light that is not scriptable is skipped.

What Gets Switched - Materials

Material/Affect Materials (default On). Applies to every scriptable material found on the object's meshes (or only the ones named in Material/Material Slots, comma-separated - empty means all). Only the properties a given material actually supports are touched (a material without a tint or an emissive channel is simply left alone on that property - nothing to fix if it does not visibly react).

A common combination: a lamp post with a real light for illumination and an emissive material on its bulb mesh so the bulb itself glows - both switch together on the same click.

If one light or material of the object cannot be updated for a moment (a busy scene), the others still switch.

Transition (Fade)

Shared by lights and materials - one setting controls both:

Materials fade through Sansar's own built-in interpolation. Lights have no built-in fade in Sansar, so the script animates them itself at about 15 updates per second: a short fade stays light on the scene, a long fade (several seconds) stays smooth.

Access Control

Who can use the click and the chat commands is set by one number and two lists, in the Access/ group. This is the scheme shared by every MPP script (Action Button V1.7.1 and later, Random Object Spawner, Avatar Speed...):

• The scene owner is always allowed, in every mode, even if listed in the Blacklist.
• A list that the current mode does not use is ignored, with a warning in the script console: a Whitelist in mode 1 or 3, a Blacklist in mode 1 or 2.
• Access/Whitelist and Access/Blacklist: 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): an entry containing a space is ignored, with a warning in the script console. Example: @morgane, friend-handle; 3f2c1a9e-0000-4c1e-9a55-1234567890ab.
• Tip: turn Debug/Debug Logging On and click the lamp with the avatar to add: the script console shows its handle and UUID, ready to paste.
• Access/Denied Text (default "You are not allowed to use this switch."): private message sent to an avatar who clicks without being allowed, at most once every 5 seconds per avatar. Empty = no message. Chat commands from a denied avatar are ignored without a message.
• Access/Hide From Denied (default Off): denied avatars do not see the object as clickable (no highlight, no hover text). Applied to the avatars present when the script starts and to each arriving avatar about 2 seconds after arrival. Needs Activation/Enable Click On. The access check on click always stays active.
• External Script Events are never subject to these rules.

Editor Properties Reference (36 total)

Activation

Light

Material

Transition

Access

Chat

Events

Debug

Version Notes

All versions share the same on / off / toggle vocabulary.

Updating from V1.5.1

Before you update, take a screenshot of the Build panel of one lamp of each kind (each Group, each transition mode, each access setting). Two settings are replaced by new ones and their values are not carried over; the screenshot lets you enter them again in a minute.

• Event names, chat commands and group sync are unchanged: Day Night, Action Button and your own scripts keep working as they are.
• Everything else carries over: the settings keep their internal names and their values; only some labels change (Prompt When ON / OFF are now Activation/Hover Text When ON / OFF, Chat Commands is Chat/Enable Chat Commands, External Events is Events/Enable Script Events, External Event Prefix is Events/Script Event Prefix), and the groups are in a new order.
• Transition Mode is now a number: after the update every lamp shows Transition/Transition Mode (1-5) = 2 (Smoothstep, the old default). If your lamps used another mode, enter its number: Linear 1, Smoothstep 2, EaseIn 3, EaseOut 4, Step 5.
• Access: after the update every lamp is in Access/Permission Mode 3 with empty lists, which means everyone can click and use chat, whatever its V1.5.1 access was. Set the access again on the lamps that had one:

• As with any update, update one lamp first and check its panel before doing the others.

Updating from V1.4.2

• Event names, chat commands and group sync are unchanged: Day Night, Action Button and your own scripts keep working as they are.
• Most values carry over: the settings keep their internal names, only their labels move into categories (Click Controls Group is now Activation/Click Syncs Group, Prompt When ON / OFF are Hover Text When ON / OFF: same settings, same values). Take a screenshot of the panel first, as above.
• Transition Mode is now a number and starts at 2 (Smoothstep): enter the number of your old mode (Linear 1, Smoothstep 2, EaseIn 3, EaseOut 4, Step 5).
• Access: Use Whitelist and Avatar Name List are gone, replaced by Access/Permission Mode (1-3), Whitelist and Blacklist, which start at "everyone". Set the mode again, and fill the lists with avatar handles or UUIDs, not display names (an old list of display names would match nobody). The scene owner is now always allowed.
• Cooldown: it now also applies to chat, group sync and script events (see Cooldown). A lamp switches a tenth of a second after a command, and a command that arrives during the cooldown is applied at its end instead of immediately. With Cooldown Seconds at 0, every command applies at once, as in V1.4.2.

Recipes

A - A single lamp, click only. Defaults are enough: drop the script on the object, leave Group empty. Click to toggle. With several such lamps in the scene, turn Click Syncs Group Off, or give each lamp its own Group, otherwise one click toggles them all.

B - A row of street lamps, one click lights them all. Same Activation/Group (for example Street) on every lamp, keep Click Syncs Group and Internal Group Events On (defaults).

C - Lamps switched by Day Night Cycle at sunset/sunrise. Events/Enable Script Events On, Script Event Prefix = mpp_lamp (default). In the Day Night Control's Events/Actions A: sunset | mpp_lamp_all_on and sunrise | mpp_lamp_all_off (or mpp_lamp_street_on / _off to target one group only). See the Day Night documentation, section 9.

D - Lamps switched by an Action Button. On the button: Send as Command On, Command 1 = mpp_lamp_all_toggle (or a group/on/off variant).

E - A silent backstage lamp. Activation/Enable Click Off, Chat/Enable Chat Commands Off - the lamp only reacts to External Script Events, invisible to visitors.

F - Lamps only you can switch. Access/Permission Mode 1 on each lamp, or 2 with your friends' handles in Access/Whitelist. Turn Hide From Denied On so visitors do not even see the lamps as clickable. Day Night and your buttons keep working (script events are not restricted).

G - A lamp that lights up when someone arrives. With Commands Help On Chat V1.5 or later in the scene: Arrival/Send Arrival Event On with Arrival Event Name = mpp_lamp_all_on, and if you like Send Departure Event On with Departure Event Name = mpp_lamp_all_off.

Troubleshooting

Limits

• Denied avatars get no message for chat commands, only for clicks.
• Hide From Denied needs the click to be enabled; it is applied a couple of seconds after an avatar arrives.
• The cooldown is per lamp: every lamp of a group applies it on its own, which keeps them in step.
• The internal group-sync event names (MPPLightSwitch:<group>:<action>) are a private detail of this script and not meant to be posted by other scripts - use the External Script Events instead (see that section) to integrate from outside.

Related MPP Items

MPP - My Pretty Pixels. Light Switch Script V1.5.3 (script MPP - Light Switch). Store: https://www.sansar.com/store/listings/7379d48c-2b6f-45f6-b6f1-205ce95aec1c/light-switch-script