MPP - Action Button V1.7.1 - Documentation

Overview

Click or collision button that sends chat text or posts a Script Event command. Unified command model: the button has 1 to 4 commands. One command = single action (flash), multiple commands = cycling sequence. Includes optional interaction sound, visual tint and emissive feedback, remote control via Script Events, a private cooldown notice and access control.

This script is standalone - it does not require any other MPP script to function. When combined with other MPP scripts (Light Switch, Commands Help On Chat, TransformByClickOrChat, etc.), it acts as a universal trigger.

In the Build panel the settings are grouped by category: Activation/, Access/, Command/, Remote/, Sound/, Visual/ and Debug/.

New in V1.7.1: the settings are grouped by category in the Build panel, and the access control uses the same scheme as the other MPP scripts: Access/Permission Mode (1-3) with a Whitelist and a Blacklist. The three access settings of V1.7.0 are not carried over: read "Updating from V1.7.0" before you update buttons already placed in a scene.

Changelog

V1.7.1 (from V1.7.0) - Settings by category and unified access

36 properties, as in V1.7.0. Every setting keeps its value when the script is swapped, except the three access settings, replaced by new ones (see "Updating from V1.7.0").

V1.7.0 (from V1.6) - Cooldown Notice and Access Control

29 -> 36 properties. All V1.6 property names are unchanged, so existing values carry over when the script is swapped.

How It Works

The button has 1 to 4 commands. Each click sends the next command and advances.

Command Count = 1 (Single Action)

• Every click sends Command 1 (always the same command).
• Visual: flashes Command 1 Tint, holds briefly, fades back to the initial material tint.
• Use case: a button that always does the same thing (toggle lights, show help, etc.)

Command Count = 2-4 (Cycling Sequence)

• Each click advances: Command 1 -> Command 2 -> ... -> Command Count -> Command 1.
• Visual: applies the corresponding Command N Tint and stays.
• Use case: a button that cycles between states (speed on/off, light modes, etc.)

Activation order

1. The avatar is validated (still in the scene).
2. Access check - denied avatars receive Denied Text (throttled) and nothing else happens.
3. Cooldown check - blocked avatars receive the cooldown notice (throttled) and nothing else happens.
4. Sound, visual feedback, then the command (chat text or Script Event).

Activation Modes

Click Mode (default)

• Activation/Use Collision = Off
• The button shows a hover text (Activation/Hover Text) and activates on click.

Collision Mode

• Activation/Use Collision = On
• Activates when an avatar enters the trigger volume or makes character contact.
• Requires a RigidBodyComponent on the object.
• VR hand contacts are ignored (unchanged from V1.6).

Cooldown

• Activation/Cooldown Seconds = 0 disables the configured cooldown. A silent 0.1 s per-avatar safety remains (double-click protection).
• Maximum accepted value: 86400 s (24 h).

Cooldown Notice

When an avatar tries to use the button during the cooldown, they receive a private chat message (only them, in their Nearby Chat).

• Default text: Please wait {time} before using this button again.
• The remaining time is rounded up (never "0 seconds").
• Anti-spam: at most one notice every 3 seconds per avatar.
• No notice when Cooldown Seconds is 0.1 or less (the safety floor stays silent).
• In global mode, avatars who never clicked also get the notice if the button is busy.
• Tip: with very short cooldowns (under 1 second), you may prefer Activation/Cooldown Notice = Off.

Access Control

Who can use the button is set by one number and two lists, in the Access/ group. This is the scheme shared by every MPP script:

• The scene owner is always allowed, in every mode, even if listed in the Blacklist.
• The owner is recognized by the avatar that owns the scene (with its handle as a fallback). Another persona of the owner counts as a different avatar.
• 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.
• The access check applies to click and collision activation. Remote Control events (from other scripts) are not affected.

List format (Whitelist and Blacklist)

• Avatar handles or avatar UUIDs, separated by commas, semicolons or new lines.
• Handles are not case sensitive; a leading @ is ignored.
• Display names are not supported (not unique). Entries containing a space are ignored with a warning.
• Example: @morgane, friend-handle; 3f2c1a9e-0000-4c1e-9a55-1234567890ab
• Tip: turn Debug/Debug Logging On and click the button with the avatar to add: the script console shows its handle and UUID, ready to paste.

Denied Text

• Private message sent to a denied avatar. Default: You are not allowed to use this button.
• At most one message every 5 seconds per avatar (useful in collision mode). Empty = silent.

Hide From Denied

• Click mode only (ignored with a warning when Use Collision is On).
• Denied avatars do not see the button as clickable: no highlight, no hover text.
• Applied to avatars present when the script starts, and to each joining avatar about 2 seconds after arrival.
• This is a comfort feature: the access check on click always stays active.

Commands

Send as Command

• Off (default): the command value is sent as chat text.
• On: the command value is posted as a Script Event that other scripts can listen to.

The event payload contains the activating avatar's UUID (IActionButtonEventData).

Private Text

Only used when Command/Send as Command = Off. If On, text is sent only to the activating avatar.

Command Values

• Command 1 through Command 4: the text or Script Event name to send.
• Example with Send as Command = On: Command 1 = mpp_lamp_toggle will toggle all Light Switch instances.
• Example with Send as Command = Off: Command 1 = Hello! will send "Hello!" to chat.

Initial Command

Controls the button's starting state when the scene loads.

Use case: Your button controls AvatarSpeed which starts in "normal" mode (= Command 2). Set Initial Command = 2 so the button shows Command 2 tint at startup and the first click sends Command 1 (speed boost).

Remote Control

When Remote/Remote Control = On, the button listens for incoming Script Events from other scripts to control its state externally.

Events Listened To

• <prefix> = Remote/Remote Prefix (default: mpp_actionbutton)
• If Remote/Remote Token is set: <prefix>_<token>_reset, <prefix>_<token>_set_1, etc.

Remote Token - Targeting specific buttons

Without a token, all Action Buttons sharing the same prefix react. The token differentiates instances.

Practical Examples

Master Reset button: Resets all buttons to command 1.

• Create an Action Button with Send as Command = On, Command 1 = mpp_actionbutton_reset
• Click it -> all buttons listening with that prefix reset.
• Tip: set Access/Permission Mode = 1 on this master button so visitors cannot reset the scene.

Reset one button only:

• Command 1 = mpp_actionbutton_lobby_reset

External script sync: A timer script calls PostScriptEvent("mpp_actionbutton_speed_set_2", ...) to force the Speed button to display command 2 when a boost expires automatically.

Remote flash for Count=1: A script calls PostScriptEvent("mpp_actionbutton_lobby_set_1", ...) -> the button flashes Command 1 Tint and returns to normal, as if someone clicked it.

Sound

• Sound/Click Sound = optional SoundResource played at the button's position on activation.
• Sound/Sound Volume = loudness from 0 to 200 percent (100 = original volume, 0 = no sound).
• No sound is played for denied avatars or during the cooldown.

Visual Feedback

Tint

• Visual/Visual Feedback = On enables material tint changes.
• Visual/Tint Material Name = filter to a specific material (empty = all tintable scriptable materials).

Emissive

• Visual/Affect Emissive = On enables EmissiveIntensity changes alongside tint.
• Returns to the material's cached initial emissive value (for Count=1 fade and initial tints).

Editor Properties Reference (36 total)

Activation (6)

Access (5)

Command (8)

Remote (3)

Sound (2)

Visual (11)

Debug (1)

Updating from V1.7.0

Before you update, take a screenshot of the Build panel of each button whose access you had changed (Owner Only, Access List, List Is Blacklist): these three settings are replaced by new ones and their values are not carried over.

• Everything else carries over: the 33 other settings keep their internal names and their values. Only their labels move into categories (Collision Mode is now Activation/Use Collision, Visual is Visual/Visual Feedback, Emissive is Visual/Affect Emissive, Debug is Debug/Debug Logging).
• Access: after the update every button is in Access/Permission Mode 3 with empty lists, which means everyone can use it, whatever its V1.7.0 access was. Set the access again on the buttons that had one, using your screenshot:

• Update the owner-only buttons (master reset, admin panels) first, so they are not open to visitors in the meantime.
• Commands, Script Events, IActionButtonEventData and the Remote Control events are unchanged: the scripts that listen to your buttons keep working as they are.

Updating from V1.6

• Every V1.6 property keeps its name and its value; the labels moved into categories in V1.7.1.
• Default behavior is identical (everyone can click), with one visible difference: Cooldown Notice is On by default. Turn it Off to get the exact V1.6 behavior.
• Sound/Sound Volume = 0 now mutes the click sound.
• The access control is new since V1.7: Access/Permission Mode 3 with empty lists = everyone, as in V1.6.

Compatibility

IActionButtonEventData and PostScriptEvent are unchanged from V1.4.x. All consumer scripts (Light Switch, Commands Help On Chat, TransformByClickOrChat, StoreListingRouter, RandomObjectSpawner) remain fully compatible.

Event Payload Interface

public interface IActionButtonEventData
{
    string ActivatorAvatarUuid { get; }
}

Related MPP Items

MPP - My Pretty Pixels. Action Button V1.7.1 (script MPP - Action Button). Store: https://www.sansar.com/store/listings/3e1a3546-6c79-4527-bc1e-78d02648d19e/action-button-script