# MPP - Store Listing Opener Script V1.3.1 - Documentation

Turns any object of your scene into a direct link to a Sansar Store listing: a click opens the Store panel of that listing for the visitor. Paste the listing link, or its UUID alone, and you are done. The same opener can also be driven by an **MPP - Action Button** (a "Buy" button on a control desk), and can play a sound when the listing opens.

This script is **standalone** - it does not require any other MPP script to function. It works with **MPP - Action Button** for a button that opens the listing.

**New in V1.3:** a per-visitor cooldown (0.75 s by default) with a private "please wait" message for a click that comes too soon; the listing opens first, then the sound plays; the listing link is checked once at start, with a clear warning when it is not usable (the object is then not clickable at all, instead of a dead button); `Sound Volume` 0 is silent; the hover text is kept to one line. Settings grouped by category and a `Debug Logging` switch. V1.3.1 only changes the version number. Your settings are kept when you update: see "Updating from V1.2".

---

## Quick Start

1. After purchase, the script is in your **Inventory** in Build mode. Add it to the object that shows the product: the product itself, a poster, a sign.
2. On the Sansar Store, open the listing you want and copy its link (`https://www.sansar.com/store/listings/<uuid>/<name>`). Paste it in `Listing/Listing URL Or UUID`.
3. Build and visit: hover the object ("Show Details"), click it, the Store panel of the listing opens.

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

---

## How It Works

| Source | Settings | What happens |
|---|---|---|
| **Click** | `Activation/Enable Click`, `Hover Text` | The listing opens for the visitor who clicks |
| **Script Event** | `Activation/Enable Script Event`, `Script Event Name` | Sent by an MPP - Action Button: the listing opens for the avatar who pressed the button |

Both go through the same per-visitor cooldown, then the listing opens, then `Sound/Click Sound` plays at the object (everyone nearby hears it). In the Build panel the settings are grouped by category: `Activation/`, `Listing/`, `Sound/` and `Debug/`.

---

## The Listing

`Listing/Listing URL Or UUID` accepts:

- the **full link** of the listing, as copied from the Store or from a share button;
- the **UUID alone** (the 36 characters of the link).

The UUID is read once, when the scene starts. A link without a UUID is only kept when it starts with `http://` or `https://`: it then opens as a **location detail view** (an Atlas link, for example), with a warning at start. Anything else (an empty value, a truncated UUID alone, free text) is a setup error: a warning tells you what to fix, and the object gets **no click interaction** and ignores the Script Event until the value is corrected.

---

## Activation

### Click

- `Activation/Enable Click` (On): the object highlights on hover and shows `Activation/Hover Text` (default "Show Details"; one line of 128 characters at most; empty = "Show Details"). Off: no hover text, no click; the Script Event still works.
- `Activation/Cooldown Seconds` (default 0.75, 0 to 60): a visitor who clicks again within this time is ignored. A silent tenth of a second always remains, even at 0, so a double click never opens the listing twice. Other visitors are never blocked.
- `Activation/Cooldown Notice` (On): a click during the cooldown gets a private message, only visible to that visitor: by default "Please wait {time} before opening this listing again.", where `{time}` becomes the remaining time with its unit and `{seconds}` the whole number of seconds (`Activation/Cooldown Notice Text`). At most one message every 3 seconds per visitor, and none when the wait is under half a second. Empty text, or the notice Off, = silent.

### Script Event

`Activation/Enable Script Event` (Off) listens to `Activation/Script Event Name` (default `mpp_store_open`). Set an **MPP - Action Button** to send that name as a script event: the listing opens for the avatar who pressed the button, under the same cooldown, without a "please wait" message (the button has its own). Every opener listening to the same name opens at once: give each opener its own event name.

---

## Sound

`Sound/Click Sound`: an optional sound from your inventory, played at the object when the listing opens, for a click or a Script Event. `Sound/Sound Volume` goes from 0 to 200 percent (100 = the sound as recorded, 0 = no sound). The sound only plays when the listing really opened.

---

## Editor Properties Reference (11 total)

### Activation
| Property | Type | Default | Description |
|---|---|---|---|
| Activation/Enable Click | bool | On | Click on the object opens the listing |
| Activation/Hover Text | string | "Show Details" | Hover text, one line of 128 characters at most |
| Activation/Cooldown Seconds | number, 0-60 | 0.75 | Wait per visitor between two openings |
| Activation/Cooldown Notice | bool | On | Private "please wait" message for a click during the cooldown |
| Activation/Cooldown Notice Text | string | "Please wait {time} before opening this listing again." | Text of that message; `{time}` and `{seconds}` are replaced, empty = no message |
| Activation/Enable Script Event | bool | Off | Listen to the Script Event below |
| Activation/Script Event Name | string | "mpp_store_open" | Event sent by MPP - Action Button; one name per opener |

### Listing
| Property | Type | Default | Description |
|---|---|---|---|
| Listing/Listing URL Or UUID | string | (an MPP listing link) | Full Store link, or the listing UUID alone |

### Sound
| Property | Type | Default | Description |
|---|---|---|---|
| Sound/Click Sound | SoundResource | (none) | Sound played at the object when the listing opens |
| Sound/Sound Volume | integer, 0-200 | 100 | Loudness in percent; 0 = no sound |

### Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Debug/Debug Logging | bool | Off | Writes the setup, the opened listings and the refused requests, with the avatar handle and UUID, to the script console |

---

## Version Notes

| Version | What changed |
|---|---|
| V1.0 | First release: one click, one listing |
| V1.1 | New Store link format, UUID alone accepted, fallback for other links |
| V1.2 | Script Event trigger, compatible with MPP - Action Button. Sold until V1.3.1 |
| V1.3.0 | Per-visitor cooldown with the "please wait" message, listing opened before the sound, link checked once at start (unusable value = no interaction, warning), Sound Volume 0 silent, one-line hover text, guarded calls, settings grouped by category |
| **V1.3.1** (this version) | Version number only |

### Updating from V1.2

- **Your values carry over**: the 8 settings of V1.2 keep their internal names and their values. As with any update, take a screenshot of the Build panel first, update one opener and check its panel before doing the others.
- **Labels**: the settings now sit in four groups. Same settings, same values:

| V1.2 | V1.3.1 |
|---|---|
| Enable Click Interaction | Activation/Enable Click |
| Prompt | Activation/Hover Text |
| Enable Script Event, Script Event Name | Activation/Enable Script Event, Script Event Name |
| Listing URL Or UUID | Listing/Listing URL Or UUID |
| Click Sound, Volume | Sound/Click Sound, Sound Volume |
| Debug Logging | Debug/Debug Logging |

- **Three new settings** at their defaults: `Activation/Cooldown Seconds` (0.75), `Cooldown Notice` (On) and `Cooldown Notice Text`.
- **What behaves differently**: a second click of the same visitor within 0.75 s is ignored, with the "please wait" message (set `Cooldown Seconds` to 0 and `Cooldown Notice` Off for the V1.2 behaviour, minus the double clicks). The sound plays after the listing opened, not before. A value without a UUID that is not an http(s) link (V1.2 sent it to the detail view anyway) now gives a warning and no interaction. `Sound Volume` 0 is silent.

---

## Recipes

**A - A product in a showroom.** The product itself, its listing link, `Hover Text` "Buy this lamp".

**B - A poster wall.** One poster per product, each with its own link and hover text; `Cooldown Seconds` 2 to keep the panel from reopening on impatient clicks.

**C - A "Buy" button on a control desk.** An MPP - Action Button set to send the script event `mpp_store_open`, `Activation/Enable Script Event` On on the opener, `Enable Click` Off if the product itself should not be clickable.

**D - Several openers on one desk.** Give each opener its own `Script Event Name` (`mpp_store_open_lamp`, `mpp_store_open_chair`) and one button per name.

---

## Troubleshooting

| Symptom | Check |
|---|---|
| The object has no hover text and cannot be clicked | `Listing URL Or UUID` empty or without a UUID (warning at start: paste the Store link or its UUID), or `Enable Click` Off |
| Nothing opens on click | Your own cooldown (you get the "please wait" message), or the listing was refused by Sansar for a moment (warning in the script console: try again after the cooldown) |
| The wrong window opens | A link without a UUID opens as a location detail view (warning at start): paste the full listing link |
| The Action Button does nothing | `Enable Script Event` On, the button's command equal to `Script Event Name`; the button must be an MPP - Action Button (it carries the avatar) |
| Two openers open at once | They share the same `Script Event Name`: give each its own |
| No sound | A sound in `Click Sound`, `Sound Volume` above 0; the sound only plays when the listing really opened |
| The hover text is cut | It is limited to one line of 128 characters |
| I want to know what the script does | Turn `Debug/Debug Logging` On: the script console shows the start summary ("Target=listing UUID ..."), every opening and every refusal |

---

## Limits

- The listing must be visible to the visitor on the Store (a hidden or unlisted product opens nothing for them).
- The cooldown is per visitor: there is no scene-wide limit.
- One listing per opener: for several products, use several objects.

---

## Related MPP Items

| Item | What it adds |
|---|---|
| **Action Button Script** | Buttons that open the listing through a script event. Store: https://www.sansar.com/store/listings/3e1a3546-6c79-4527-bc1e-78d02648d19e/action-button-script |
| **Open Creator Store Script** | Opens a creator's whole store instead of one listing. Store: https://www.sansar.com/store/listings/3d87d439-c908-4c2d-bd55-3d9969d2a524/open-creator-store-script |
| **Send Website To Nearby Chat Script** | Sends a website link in the chat. Store: https://www.sansar.com/store/listings/2b1465e7-ca59-4f7c-b01f-797ffb860ebe/send-website-to-nearby-chat-script |

---

*MPP - My Pretty Pixels. Store Listing Opener Script V1.3.1 (script `MPP - Store Listing Opener`). Store: https://www.sansar.com/store/listings/8c7e1415-e339-4db5-98d1-6dfacee78d14/store-listing-opener-script*