# MPP - Scene Info Viewer Script V1.3.0 - Documentation

Shows your visitors what is going on in your scene: its name, how many people are in, the instance role, the gravity, how long the scene has been running and how long they have been there. They ask by clicking an object, by typing a chat command, or through an MPP - Action Button. The same click can open Sansar's **details window** of the scene (description, links, travel). A second, more technical **debug report** (IDs, script memory, coroutines, visitor names) is reserved to you and to the avatars you allow.

This script is **standalone** - it does not require any other MPP script to function. It works with **MPP - Action Button** if you want a button that asks for the report.

**First release on the Store (V1.3.0).** Every setting is visible in the Build panel; the debug report has an access control by permission mode (owner only, owner + whitelist, everyone except a blacklist); a visitor who asks too soon gets a private "please wait" message; the reports are sent safely even when someone leaves the scene in the middle.

---

## Quick Start

1. After purchase, the script is in your **Inventory** in Build mode. Add it to an object: an info sign, a desk, a totem at the landing point.
2. Build and visit. Click the object: you receive the simple report in private, and the details window of the scene opens.
3. Type `/sceneinfo` in the Nearby Chat: same report, without the window. Type `/sceneinfodebug`: the debug report, for you only.

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

---

## How It Works

| Source | Settings | What the visitor gets |
|---|---|---|
| **Click** | `Activation/Enable Click`, `Click Report Mode (0-2)`, `Open Details On Click` | The simple report (mode 1, default), the debug report (mode 2) or nothing (mode 0), and/or the details window |
| **Chat command** | `Chat/Simple Command`, `Debug Command` | `/sceneinfo` or `/sceneinfodebug`, with the details window if the matching switch is On |
| **Script Event** | `Events/Simple Event Name`, `Debug Event Name` | Sent by an MPP - Action Button: the report goes to the avatar who pressed the button |

Every request goes through the same checks: the access control (debug report only), the per-avatar cooldown and, for a report posted to everyone, the public cooldown. Then the report is **whispered** to the avatar (default) or **posted to everyone** in the Nearby Chat.

In the Build panel the settings are grouped by category: `Activation/`, `Report/`, `Access/`, `Chat/`, `Events/` and `Debug/`.

---

## The Two Reports

### Simple report

```
[Scene Info]
Scene: <experience name>
Visitors: 3 / 20
Instance role: <role>
Gravity: 9.81 m/s^2 (default 9.81)
Script active: 2h 14m 5s
Your tracked visit: 12m 40s
```

- `Report/Show Script Active Time` (On): the time since the script started, which is the last restart of the scene, not the real age of the instance.
- `Report/Show Tracked Visit Time` (On): how long the avatar who asked has been in the scene. Only in a whispered report: it makes no sense for everyone. An avatar present before the script started is counted from the script start.

### Debug report

The simple report, then: location handle, instance ID, world ID, event ID, owner handle and avatar UUID, access group, compat / proto / config versions, build ID, API version, script memory (used and peak) and memory policy, pending events, coroutines, and, with `Report/Show Visitor Names In Debug` On, the names of the avatars present (`Max Visitor Names In Debug`, 0 = all). `Report/Show Full IDs` Off shortens the long IDs to their first 8 and last 4 characters.

A long report is sent in several chat messages of `Report/Max Characters Per Message` characters at most (default 580).

---

## Activation

### Click

- `Activation/Enable Click` (On): the object highlights on hover and shows `Activation/Hover Text` (empty = an automatic text: "Scene Info / Open Details", "Scene Debug", "Open Scene Details"...). The hover text is cut at 128 characters.
- `Activation/Click Report Mode (0-2)`: 0 = no report (the click can still open the details window), 1 = simple report (default), 2 = debug report, with the access control below.
- `Activation/Open Details On Click` (On): the click also opens Sansar's details window of the scene for the visitor.

With mode 0 and the window Off, a click would do nothing: no interaction is created, and a warning says so in the script console.

### Chat commands

`Chat/Enable Chat Commands` (On) listens to `Chat/Simple Command` (`/sceneinfo`) and `Chat/Debug Command` (`/sceneinfodebug`) in the Nearby Chat: exact match, case ignored, empty = Off. `Open Details On Simple Command` and `Open Details On Debug Command` (Off) open the details window too.

### Script Events

`Events/Enable Script Events` (Off) listens to `Events/Simple Event Name` (`mpp_sceneinfo`) and `Events/Debug Event Name` (`mpp_sceneinfodebug`). Set an **MPP - Action Button** to send one of these names as a script event: the report goes to the avatar who pressed the button, with the details window if `Open Details On Simple Event` or `Open Details On Debug Event` is On. An event that does not carry the avatar (sent by a script that is not an MPP button) is ignored.

### The details window

The Sansar window of the current scene, with its description, its links and the travel button, opened on the visitor's screen. It is a handy way to show the scene's rules or links from an object.

---

## Delivery and Cooldowns

- `Report/Simple Report To Everyone` and `Report/Debug Report To Everyone` (Off): On, the report is posted in the Nearby Chat for everyone instead of being whispered. The visit-time line is then left out.
- `Activation/Cooldown Seconds` (default 3, 0 to 120): a visitor who asks again within this time is refused, whatever the source (click, command, event).
- `Activation/Public Cooldown Seconds` (default 5, 0 to 120): minimum time between two reports posted to everyone, whoever asks, so the chat is never flooded.
- `Activation/Cooldown Notice` (On): a refused visitor receives a private message, only visible to them: by default "Please wait 3 seconds before asking for the scene info again.". At most one message every 3 seconds per visitor, 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 ("2 seconds", "1 minute 5 seconds"), `{seconds}` the whole number of seconds. Empty text, or the notice Off, = silent refusal.

---

## Access to the Debug Report

The simple report is open to everyone. The debug report follows `Access/Permission Mode (1-3)`:

| Mode | Who gets the debug report |
|---|---|
| **1** (default) | The scene owner only |
| **2** | The scene owner and the avatars of `Access/Whitelist` |
| **3** | Everyone, except the avatars of `Access/Blacklist` (empty list = everyone) |

The scene owner is always allowed, in every mode. The lists take avatar **handles** (the name in the profile link, `https://www.sansar.com/profiles/<handle>`) or avatar **UUIDs**, separated by commas or semicolons; `@` and letter case are ignored. A display name with a space is ignored with a warning.

A refused avatar receives `Access/Denied Text` in private (default "You are not allowed to use the scene debug report."), at most once every 5 seconds; empty = silent. A refused **click** still opens the details window when `Open Details On Click` is On.

---

## Editor Properties Reference (31 total)

### Activation
| Property | Type | Default | Description |
|---|---|---|---|
| Activation/Enable Click | bool | On | Click on the object sends the report and/or opens the details window |
| Activation/Hover Text | string | (empty) | Hover text; empty = automatic |
| Activation/Click Report Mode (0-2) | integer, 0-2 | 1 | 0 = none, 1 = simple report, 2 = debug report |
| Activation/Open Details On Click | bool | On | The click also opens the scene details window |
| Activation/Cooldown Seconds | number, 0-120 | 3 | Wait per visitor between two requests |
| Activation/Cooldown Notice | bool | On | Private "please wait" message for a request that comes too soon |
| Activation/Cooldown Notice Text | string | "Please wait {time} before asking for the scene info again." | Text of that message; `{time}` and `{seconds}` are replaced, empty = no message |
| Activation/Public Cooldown Seconds | number, 0-120 | 5 | Minimum time between two reports posted to everyone |

### Report
| Property | Type | Default | Description |
|---|---|---|---|
| Report/Simple Report To Everyone | bool | Off | Post the simple report in the chat for everyone |
| Report/Debug Report To Everyone | bool | Off | Post the debug report in the chat for everyone |
| Report/Show Script Active Time | bool | On | Time since the script started |
| Report/Show Tracked Visit Time | bool | On | Visit time of the avatar who asked (whispered reports only) |
| Report/Show Visitor Names In Debug | bool | Off | Names of the avatars present, in the debug report |
| Report/Max Visitor Names In Debug | integer, 0-100 | 10 | Names shown at most; 0 = all |
| Report/Show Full IDs | bool | Off | Off = long IDs shortened |
| Report/Max Characters Per Message | integer, 120-2000 | 580 | A longer report is split into several messages |

### Access
| Property | Type | Default | Description |
|---|---|---|---|
| Access/Permission Mode (1-3) | integer, 1-3 | 1 | Who gets the debug report; the owner always |
| Access/Whitelist | string | (empty) | Handles or UUIDs allowed in mode 2 |
| Access/Blacklist | string | (empty) | Handles or UUIDs refused in mode 3 |
| Access/Denied Text | string | "You are not allowed to use the scene debug report." | Private refusal, at most every 5 s; empty = silent |

### Chat
| Property | Type | Default | Description |
|---|---|---|---|
| Chat/Enable Chat Commands | bool | On | Listen to the two commands |
| Chat/Simple Command | string | "/sceneinfo" | Command of the simple report; empty = Off |
| Chat/Debug Command | string | "/sceneinfodebug" | Command of the debug report; empty = Off |
| Chat/Open Details On Simple Command | bool | Off | The simple command also opens the details window |
| Chat/Open Details On Debug Command | bool | Off | The debug command also opens the details window |

### Events
| Property | Type | Default | Description |
|---|---|---|---|
| Events/Enable Script Events | bool | Off | Listen to the two Script Events |
| Events/Simple Event Name | string | "mpp_sceneinfo" | Event of the simple report; empty = Off |
| Events/Debug Event Name | string | "mpp_sceneinfodebug" | Event of the debug report; empty = Off |
| Events/Open Details On Simple Event | bool | Off | The simple event also opens the details window |
| Events/Open Details On Debug Event | bool | Off | The debug event also opens the details window |

### Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Debug/Debug Logging | bool | Off | Writes the start summary and every request, accepted or refused, with the avatar handle and UUID, to the script console |

---

## Version Notes

| Version | What changed |
|---|---|
| V1.0 - V1.2.4 | Internal versions, never sold: simple and debug reports, click, chat commands, Script Events, details window, cooldowns, visit tracking |
| **V1.3.0** (this version) | First release on the Store. Every setting visible in the Build panel (a numeric click mode, "To Everyone" switches), access to the debug report by permission mode with whitelist and blacklist, customizable refusal text, "please wait" notice for the cooldowns, safe delivery when an avatar leaves during a report, warnings for a wrong setup, settings grouped by category, Debug Logging |

### Updating from V1.2.4

Only for an object that already carried the internal V1.2.4. The 21 settings that keep their name keep their value; take a screenshot of the Build panel first. Six settings are replaced and must be entered again: Click Mode (None, Simple, Debug) becomes `Activation/Click Report Mode (0-2)` (0, 1, 2); Simple Output and Debug Output (Private, Public) become `Report/Simple Report To Everyone` and `Debug Report To Everyone`; Debug Access (OwnerOnly, OwnerOrWhitelist) becomes `Access/Permission Mode (1-3)` (1, 2); Debug Admin Handles and Debug Admin Avatar UUIDs become the single `Access/Whitelist`. New at their defaults: `Cooldown Notice` and its text, `Access/Denied Text`, `Debug/Debug Logging`.

---

## Recipes

**A - The info sign.** Defaults: a click whispers the simple report and opens the details window. Put it at the landing point.

**B - A public counter.** `Report/Simple Report To Everyone` On, `Activation/Open Details On Click` Off, `Hover Text` "Who is here?": a click posts the visitor count for everyone, at most every 5 seconds.

**C - The admin desk.** `Activation/Click Report Mode (0-2)` 2, `Access/Permission Mode (1-3)` 2, your helpers' handles in `Access/Whitelist`: a click gives them the debug report, and the other visitors get the details window with a polite refusal.

**D - A "Scene info" button on a control desk.** An MPP - Action Button set to send the script event `mpp_sceneinfo`, `Events/Enable Script Events` On: the report goes to whoever presses the button.

**E - Commands only.** `Activation/Enable Click` Off: no click, only `/sceneinfo` and `/sceneinfodebug` in the chat.

---

## Troubleshooting

| Symptom | Check |
|---|---|
| The object has no hover text | `Activation/Enable Click` Off, or `Click Report Mode` 0 with `Open Details On Click` Off (warning "no click interaction is created" in the script console) |
| I click and nothing happens | Your own cooldown: with `Cooldown Notice` On you get the "please wait" message; with it Off the refusal is silent |
| `/sceneinfodebug` answers "You are not allowed..." | The debug report follows `Access/Permission Mode (1-3)`: add the handle to the `Whitelist` in mode 2, or use mode 3. The scene owner is always allowed |
| A whitelisted friend is still refused | The list takes the **handle** (from the profile link) or the avatar UUID, not the display name; an entry with a space is ignored with a warning |
| The report is cut, or too many messages | Raise `Report/Max Characters Per Message` (up to 2000) |
| The visit time is missing | It is only in a whispered report, and only with `Show Tracked Visit Time` On |
| "Script active" is shorter than I expect | It counts from the last restart of the scene, not from its creation |
| The Action Button does nothing | `Events/Enable Script Events` On, and the button's command equal to the event name. The button must be an MPP - Action Button (it carries the avatar in its event) |
| I want to know what the script does | Turn `Debug/Debug Logging` On: the script console shows the start summary and every request, accepted or refused |

---

## Limits

- The visit time and the script active time are measured by the script: they start at the last restart of the scene.
- A Script Event sent by a script that does not carry the avatar (not an MPP - Action Button) cannot be answered: there is nobody to whisper to.
- The gravity is the scene's, read at the moment of the report.

---

## Related MPP Items

| Item | What it adds |
|---|---|
| **Action Button Script** | Buttons that ask for the report through a script event, on a control desk. Store: https://www.sansar.com/store/listings/3e1a3546-6c79-4527-bc1e-78d02648d19e/action-button-script |
| **Commands Help On Chat Script** | Lists your scene commands (`/sceneinfo` among them) when a visitor asks for help, and greets arrivals. Store: https://www.sansar.com/store/listings/fea2df6b-21ce-48eb-94fc-4b7a7aad2777/commands-help-on-chat-script |

---

*MPP - My Pretty Pixels. Scene Info Viewer Script V1.3.0 (script `MPP - Scene Info Viewer`). Store: https://www.sansar.com/store/listings/34549ccc-ce32-4bc6-a2f1-5e05d70a97b0/scene-info-viewer-script*