MPP - Commands Help On Chat Script V1.5.2 - Documentation

Shows a help text in Nearby Chat when a visitor types a command such as /CommandsHelp, or when another script asks for it (an MPP - Action Button on a help panel, for example). The help can be the built-in list of Sansar chat commands, your own text, or both. Optionally, the script also greets the avatars who enter the scene, with their name, their handle or a link to their web profile, plays a sound when someone arrives, and posts a Script Event at each arrival and each departure so that your other scripts can react.

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

New in V1.5: an Arrival/ group, all Off by default and independent of the greeting: a sound when an avatar enters the scene (from the object or everywhere, with a volume and a minimum interval), a Script Event at each arrival and one at each departure, carrying the avatar's UUID like an Action Button click. V1.5.1 also renames two groups of the Build panel (Activation/ and Help/). Your settings are kept when you update: see "Updating from V1.4.0".

New in V1.5.2: NPCs. Sansar NPCs enter a scene like avatars, so the greeter used to announce them at every scene start. The new switch Activation/Detect NPCs, Off by default, makes the script ignore them: no greeting, no arrival sound or event, no answer to their help request. Turn it On to treat NPCs as visitors (see "NPCs").

Quick Start

1. After purchase, the script is in your Inventory in Build mode. Add it to any object of your scene: a sign, a help panel, or a small object hidden out of sight.
2. Build and visit the scene, then type /CommandsHelp in Nearby Chat: the built-in help (the Sansar %% commands) is posted in the chat for everyone.
3. To add your own commands, paste them in Help/Help Block (several lines allowed). They are shown after the built-in help, under the separator line -- Custom Command --.
4. Optional: turn Join Greeting/Enable Greeting On to welcome visitors with "Hello! Type /CommandsHelp in Nearby Chat to see the scene commands."
5. Optional: pick a sound in Arrival/Arrival Sound to play a chime when someone arrives.

That is all most scenes need. The rest of this guide details every option.

How It Works

Two ways to ask for the help, one help text, two ways to deliver it:

Apart from the help, the script watches the avatars who enter and leave the scene: the join greeting (a chat message), the arrival sound and the arrival and departure events are three independent options, each with its own switch. Sansar NPCs are ignored by all three unless Activation/Detect NPCs is On (see "NPCs").

In the Build panel the settings are grouped by category: Activation/, Help/, Join Greeting/, Arrival/ and Debug/.

Triggers

Chat command

Activation/Chat Command (default /CommandsHelp). The visitor types it alone in Nearby Chat. Case does not matter (/commandshelp works too) and spaces before and after are ignored, but a sentence that contains the command among other words is ignored. Leave it empty to disable the chat trigger.

Script Event

With Activation/Enable Script Event On (default), the script also shows the help when another script posts the Script Event named in Activation/Script Event Name (default show_commands_help).

• From an MPP - Action Button: on the button, Send as Command On and Command 1 = show_commands_help. The button tells which avatar clicked, so the help can be whispered to that avatar (see "Who Receives the Help").
• From your own script: post the event name. To identify the avatar, send the same data as Action Button: an object with a public text property named ActivatorAvatarUuid holding the avatar's UUID (see "Event Payload Interface" in the Action Button documentation). Without it, the help can only be posted to everyone.

Several help texts in one scene

Place several copies of the script, each with its own chat command and event name: /AdminHelp, /TeamHelp, /EventHelp... Each copy has its own texts, cooldown and delivery mode.

What Is Shown

The help is made of up to three parts:

• Built-in help (Help/Show Default Help, default On): the list of Sansar's own chat commands, shown exactly like this:

Type these into Nearby Chat. (Most can target a username, e.g. %%kick User-1234)

%%who -- list all users in scene
%%roles -- show your current role
%%kick <name> -- remove a user from the scene
%%mute <name> -- temporarily disable a user's mic
%%mega-on/off <name> -- give or remove megaphone access
%%broadcast-on/off <name> -- show or hide avatar across instances
%%backpack-on/off -- toggle backpack visibility
%%backpack-clear -- remove all spawned backpack items
%%muteall [seconds] -- mute everyone (optional delay)
%%unmuteall [seconds] -- unmute everyone (optional delay)

• Your Help Block (Help/Help Block): your own text, as many lines as you like. Empty lines are skipped when the help is sent line by line; with Help/Send As Single Message On, they are kept inside the message.
• Separator (Help/Section Separator, default -- Custom Command --): a line placed between the two, only when both are shown. Empty = no separator.

Order. By default: built-in help, separator, your Help Block. With Help/Help Block First On: your Help Block, separator, built-in help.

To show only your own text, turn Help/Show Default Help Off. With Show Default Help Off and an empty Help Block, the command does nothing.

Line by line or in blocks

• Help/Send As Single Message Off (default): each line is a separate chat message, sent quickly one after the other.
• On: each part (built-in help, separator, your Help Block) is sent as one message. A part longer than Help/Max Characters Per Message (default 580, from 100 to 2000) is split into several messages, preferably between lines, so a line is only cut when it is itself longer than the limit.

Who Receives the Help

Help/Whisper To Sender Only:

• Off (default) - broadcast: the help is posted in Nearby Chat for everyone in the scene.
• On - whisper: only the avatar who asked receives it, in private. The other visitors see nothing. A Script Event that does not say which avatar asked (see "Script Event") shows nothing in this mode.

Cooldown

Activation/Cooldown Seconds (default 5, 0 = no cooldown, 86400 = 24 hours at most) is the minimum delay between two help displays:

• Broadcast: one delay for the whole scene. After the help was posted, the next request from anyone is refused until the delay is over, so a crowd typing the command does not flood the chat.
• Whisper: one delay per avatar. Each visitor can get the help in private without waiting for the others. The only shared limit is a safety pause of a tenth of a second after each help sent: a request from another avatar in that instant is ignored without a message (asking again works).

A request that would show nothing (no built-in help and an empty Help Block, or a whisper without a known avatar) is simply ignored and does not start the delay.

Cooldown Notice

With Activation/Cooldown Notice On (default), an avatar whose request is refused receives a private message, only visible to them: by default "The help was just posted in the chat. You can ask again in 4 seconds." At most one message every 3 seconds per avatar, and none when the wait is under half a second.

Write your own text in Activation/Cooldown Notice Text: {time} becomes the remaining time with its unit ("4 seconds", "1 minute 5 seconds"), {seconds} the whole number of seconds. Leave the text empty, or turn the notice Off, to refuse in silence.

Join Greeting

With Join Greeting/Enable Greeting On, a greeting is posted in Nearby Chat, for everyone, when an avatar enters the scene.

Tokens in the message:

• {trigger} is replaced by your chat command (/CommandsHelp).
• {name}, {handle} and {profileurl} are replaced by the arriving avatar's name, handle and profile link, only when the matching Include switch is On (otherwise they become empty).

When the message contains neither {name} nor {handle}, the Include switches still work:

• The name and/or the handle are placed before the message: Anna (@anna) - Hello! Type /CommandsHelp in Nearby Chat to see the scene commands.
• The profile link is added at the end, after the label: ... commands. Profile: https://www.sansar.com/profiles/anna

If the message contains {name} or {handle}, nothing is placed before it: write both tokens to show both, for example Welcome {name} ({handle})!.

Double spaces, and a space left before a comma, a period or a colon, are cleaned up. If your message uses a token, keep the matching Include switch On: otherwise the text around the token stays (for example empty brackets () or a space before !). A display name that ends with "- Sansar" (Sansar staff accounts) is shown as "Name Sansar", so the chat does not turn it into a link.

Arrival Sound and Events

The Arrival/ group reacts to the avatars who enter and leave the scene, independently of the join greeting (which can be On or Off). Everything in it is Off by default: with the defaults, the script behaves exactly as V1.4.0.

Arrival sound

A sound played for everyone in the scene when an avatar arrives - a chime, a door, a bird.

• The delay starts when a sound is actually played.
• The avatar who arrives may not hear their own arrival sound: their client is still loading at that moment. The visitors already in the scene hear it.
• Place the object near the spawn point, or turn Sound Everywhere On, so the sound is heard where it matters.

Arrival and departure events

Two Script Events that other scripts can listen to, to react to the comings and goings: a lamp that lights up, a counter, a door, a script of your own.

• One event per avatar, at every arrival and every departure: no delay between two events.
• Each event carries the avatar's UUID, with the same data as an MPP - Action Button click (ActivatorAvatarUuid, see "Event Payload Interface" in the Action Button documentation). A script that already listens to an Action Button can listen to arrivals and departures the same way, and knows which avatar it was.
• For the departure, the avatar is already gone when the event is sent: the script remembers the UUID of each avatar from its arrival (and of the avatars already present when the scene starts). If the avatar could not be read, the event is still posted, with an empty UUID.
• A switch On with an empty event name sends nothing, with a warning in the script console at start.
• Examples. Set Arrival Event Name to mpp_lamp_all_on and Departure Event Name to mpp_lamp_all_off to switch every MPP - Light Switch lamp of the scene on when someone arrives and off when they leave. Set Arrival Event Name to the Activation/Script Event Name of a second Commands Help object in whisper mode to send the help in private to each arriving avatar. Or listen to mpp_avatar_arrived in your own script with SubscribeToScriptEvent.
• A script that answers the arrival event by writing to the arriving avatar (a private message, a window) may act before that avatar's client has finished loading, and the message can be missed. For the arriving avatar, the join greeting is the safe choice: it is posted to everyone and stays in the chat.

NPCs

Sansar NPCs (non-player characters) are in the scene when it starts, and scripts see them exactly like avatars. Without this setting the greeter would welcome them at every scene start, the arrival sound would play, the arrival event would fire, and the greeting cooldown would be spent on them before the first real visitor.

Activation/Detect NPCs (default Off):

• Off: NPCs are ignored by the whole script: no greeting, no arrival sound, no arrival or departure event, and a help request coming from an NPC gets no answer. Real visitors are handled as usual.
• On: NPCs count as visitors, as in V1.5.1: greeted, announced, and able to trigger the help.

The script recognizes an NPC by its handle: npc- followed by 32 characters (digits and letters a to f), for example npc-47fd9b2b74454649aedef8d8fe5550ac. Sansar gives scripts no other sign. A visitor whose handle merely starts with npc- (like npc-fan) is not an NPC. With Debug/Debug Logging On, each ignored NPC is written to the script console.

Editor Properties Reference (30 total)

Activation

Help

Join Greeting

Arrival

Debug

Version Notes

Updating from V1.5.1

• Your values carry over: nothing changes in the existing settings.
• One new setting, Activation/Detect NPCs, Off: NPCs present in your scene are no longer greeted or announced, and no longer spend the greeting cooldown. Turn it On to keep the V1.5.1 behaviour.

Updating from V1.4.0

• Your values carry over: the 21 settings of V1.4.0 keep their internal names and their values. Only two group names and one label change in the Build panel: Trigger/ is now Activation/, Message/ is now Help/, and Script Event Trigger is now Enable Script Event.
• Nine new settings, all Off or empty: Activation/Detect NPCs and the eight Arrival/ settings. Until you use them, the script behaves as V1.4.0 (no sound, no event), with one difference: NPCs are no longer greeted or announced (see "NPCs").
• As with any update, take a screenshot of the Build panel first, update one object and check that its settings are still there before doing the others.

Updating from V1.3.8

• Your values carry over: the settings keep their internal names, only their labels change (for example UserBlockFirst is now Help/Help Block First). Take a screenshot of the Build panel first, update one object and check that its settings are still there.
• Whisper mode: the cooldown is now per avatar. In V1.3.8, one visitor's request blocked everybody else for the whole delay, without a word.
• Cooldown Notice is On by default: a refused request now gets a private "please wait" message. Turn Activation/Cooldown Notice Off to keep the V1.3.8 silence.
• Cooldown Seconds now stops at 86400 (24 hours): a larger value counts as 24 hours.
• Twelve new settings since V1.3.8: Activation/Cooldown Notice, Activation/Cooldown Notice Text, Activation/Detect NPCs, Debug/Debug Logging and the eight Arrival/ settings, all at their defaults. The others are the same as in V1.3.8. NPCs are no longer greeted (see "NPCs").

Recipes

A - A help command for everyone. Defaults are enough: add the script to any object, paste your own commands in Help/Help Block.

B - A private help for each visitor. Help/Whisper To Sender Only On. Each visitor who types the command gets the help in private; the chat stays clean for the others.

C - A "Help" button. Put an MPP - Action Button on a panel: Send as Command On, Command 1 = show_commands_help. With Whisper To Sender Only On, the help goes to the avatar who clicked.

D - Your own commands only. Help/Show Default Help Off, your text in Help/Help Block. Useful for a game, a roleplay or a shop with its own chat commands.

E - Welcome visitors by name. Join Greeting/Enable Greeting On, Include Name On, and for example Join Greeting/Message = Welcome {name}! Type {trigger} for the scene commands. Set Cooldown Minutes to 0 to greet every arrival, or keep 10 in a busy hub.

F - Separate help texts for visitors and staff. Visitor copy: /CommandsHelp, Help/Show Default Help Off, and your visitor commands in Help/Help Block. Staff copy: Activation/Chat Command = /AdminHelp, Show Default Help On (the Sansar %% commands), your staff notes in its Help Block, Whisper To Sender Only On. Give it another Activation/Script Event Name, or turn its Activation/Enable Script Event Off, so that a help button does not show both. The command is not restricted: a visitor who types /AdminHelp receives that help in private too.

G - A chime when someone arrives. Pick a sound in Arrival/Arrival Sound, put the object near the spawn point (or turn Sound Everywhere On). Keep Sound Min Interval Seconds at 2 so a group arriving together rings once.

H - Lamps that light up for your visitors. Arrival/Send Arrival Event On with Arrival Event Name = mpp_lamp_all_on, Send Departure Event On with Departure Event Name = mpp_lamp_all_off, and MPP - Light Switch on the lamps (Events/Enable Script Events On, prefix mpp_lamp). The lamps switch on when someone enters and off when they leave.

I - Your own script reacts to arrivals. Keep the default names (mpp_avatar_arrived, mpp_avatar_left) and subscribe to them in your script: the event data holds the avatar UUID in ActivatorAvatarUuid, like an Action Button click.

Troubleshooting

Limits

• The help is posted in Nearby Chat: visitors see it in their chat window.
• The greeting is always posted for everyone; it cannot be private.
• The greeting cooldown, the arrival sound interval and, in broadcast mode, the help cooldown are shared by the whole scene.
• The arrival sound and the events fire the moment the avatar enters, while their own client may still be loading: a sound or a private message aimed at the arriving avatar can be missed by them. Everyone else gets them.
• NPCs are recognized by their handle (npc- followed by 32 characters), the only sign Sansar gives scripts. If Sansar changed that format, NPCs would count as visitors again until the script is updated.
• Some of the Sansar %% commands of the built-in help only work for the scene's owner and the roles they grant; the list is shown to everyone.

Related MPP Items

MPP - My Pretty Pixels. Commands Help On Chat Script V1.5.2 (script MPP - Commands Help On Chat). Store: https://www.sansar.com/store/listings/fea2df6b-21ce-48eb-94fc-4b7a7aad2777/commands-help-on-chat-script