# MPP - Sound States On Grab Script V1.1.2 - Documentation

Gives a prop three sound states: a **base** sound while nobody holds it (a hum, an ambience, a music pad), a **held** sound while a visitor carries it, and a **release** sound when they let it go, played once or looped until the base sound comes back. The sounds play from the object itself, so they follow it around the scene.

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

**New in V1.1.2:** a quick release, grab and release no longer cuts the release sound short nor starts the base sound twice; a volume of 0 really plays no sound; warnings in the script console for a missing audio component, a wrong component name, an object that cannot be grabbed or a release loop too short to be heard; a `Debug Logging` switch that writes every sound start. Settings grouped by category in the Build panel. Your settings are kept when you update: see "Updating from v1.1".

---

## Quick Start

1. After purchase, the script is in your **Inventory** in Build mode. Add it to a prop your visitors can pick up: a lantern, a music box, a toy.
2. Make sure the object is a **physics object** (a RigidBody) that can be **grabbed**, and add an **Audio component** to it so the sounds follow the object.
3. Assign your sounds from your inventory: `Base/Sound` (usually a loop), `Held/Sound` (usually a loop), `Release/Sound` (usually a one-shot).
4. Build and visit. The base sound plays; pick the object up: the held sound takes over; let it go: the release sound plays, then the base sound comes back.

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

---

## How It Works

| Moment | What plays |
|---|---|
| **Scene start** | `Base/Sound`, if assigned (looped by default) |
| **Grab** | The base and release sounds stop, `Held/Sound` starts |
| **Release** | The held sound stops, `Release/Sound` plays (once, or looped) |
| **After the release** | With `Release/Resume Base After Release` On, the base sound comes back after `Release/Base Resume Delay Seconds`; a looping release sound stops at that moment, a one-shot one is left to finish |

Each sound has its own `Volume` (0 to 200 percent, 100 = the sound as recorded, 0 = no sound at all) and its own `Looping` switch. In the Build panel the settings are grouped by category: `Audio/`, `Base/`, `Held/`, `Release/` and `Debug/`.

---

## Audio Component

The sounds are played **on the object's Audio component**, so they move with the object when it is carried.

- `Audio/Audio Component Name` empty (default): the first Audio component of the object.
- A name: the Audio component with that exact name (spaces around it are ignored, letter case counts). If no component has that name, the first one is used and a warning says so in the script console.
- No Audio component at all: the sounds play at the position the object had when they started, and do not follow it. A warning says so at start. Add an Audio component to the object to fix it.

---

## Base Sound

- `Base/Sound`: the sound played while the object is **not** held. Empty = none.
- `Base/Volume` (100) and `Base/Looping` (On): with Looping On the sound loops until the next grab; Off, it plays once at the scene start and once after each release (when `Resume Base After Release` is On).

---

## Held Sound

- `Held/Sound`: the sound played while the object **is** held. Empty = none.
- `Held/Volume` (100) and `Held/Looping` (On): with Looping Off the sound plays once per grab, and is cut at the release if it is still playing.

---

## Release Sound

- `Release/Sound`: the sound played when the object is released. Empty = none.
- `Release/Volume` (100) and `Release/Looping` (Off): a one-shot sound (Off) is left to finish; a looping sound (On) plays until the next grab, or until the base sound comes back.
- `Release/Resume Base After Release` (On): the base sound restarts `Release/Base Resume Delay Seconds` after each release (default 0.1 s, 0 to 5). Set the delay to the length of your release sound so they do not overlap. With Looping On on the release sound, the delay is the length of that loop: with the default 0.1 s it is barely heard, and a warning says so at start (raise the delay, or turn Resume Off).
- `Resume Base After Release` Off: the base sound never comes back after the first grab.

A fast release, grab and release keeps the full delay from the **last** release: the release sound plays its full time and the base sound starts once.

---

## Volume

The three `Volume` settings go from 0 to 200 percent and are converted to decibels: 100 = the sound as recorded, 50 = about -6 dB (half the amplitude), 200 = about +6 dB (twice the amplitude). **0 = the sound is not played at all**; the other two sounds behave as usual, and a muted release sound keeps its delay before the base sound comes back.

---

## Editor Properties Reference (13 total)

### Audio
| Property | Type | Default | Description |
|---|---|---|---|
| Audio/Audio Component Name | string | (empty) | Audio component to play from; empty or not found = the first one |

### Base
| Property | Type | Default | Description |
|---|---|---|---|
| Base/Sound | SoundResource | (none) | Sound while the object is not held |
| Base/Volume | number, 0-200 | 100 | Loudness in percent; 0 = no sound |
| Base/Looping | bool | On | Loop until the next grab; Off = once |

### Held
| Property | Type | Default | Description |
|---|---|---|---|
| Held/Sound | SoundResource | (none) | Sound while the object is held |
| Held/Volume | number, 0-200 | 100 | Loudness in percent; 0 = no sound |
| Held/Looping | bool | On | Loop while held; Off = once per grab |

### Release
| Property | Type | Default | Description |
|---|---|---|---|
| Release/Sound | SoundResource | (none) | Sound played at the release |
| Release/Volume | number, 0-200 | 100 | Loudness in percent; 0 = no sound |
| Release/Looping | bool | Off | Loop until the next grab or the base resume; Off = once |
| Release/Resume Base After Release | bool | On | The base sound comes back after each release |
| Release/Base Resume Delay Seconds | number, 0-5 | 0.1 | Delay before the base sound comes back |

### Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Debug/Debug Logging | bool | Off | Writes the chosen Audio component and each sound start (base, held, release) to the script console |

---

## Version Notes

| Version | What changed |
|---|---|
| v1.0 | First release: base, held and release sounds, volumes in percent, Audio component or fixed position |
| v1.1 | Release sound loop or one-shot, base resume with delay. Sold until V1.1.2 |
| V1.1.1 | Quick release / grab / release fixed (full delay, base started once), Volume 0 = no sound, warnings for a wrong setup, Debug Logging, settings grouped by category |
| **V1.1.2** (this version) | Version number only |

### Updating from v1.1

- **Your values carry over**: the 13 settings of v1.1 keep their internal names, their defaults and their ranges. As with any update, take a screenshot of the Build panel first, update one object and check its panel before doing the others.
- **Labels**: the settings now sit in five groups. Same settings, same values:

| v1.1 | V1.1.2 |
|---|---|
| Audio Component Name | Audio/Audio Component Name |
| Base (Idle) Sound, Base Volume (%), Base Looping | Base/Sound, Volume, Looping |
| Held Sound, Held Volume (%), Held Looping | Held/Sound, Volume, Looping |
| Release Sound, Release Volume (%), Release Looping | Release/Sound, Volume, Looping |
| Resume Base After Release, Base Resume Delay (sec) | Release/Resume Base After Release, Base Resume Delay Seconds |
| Debug Log | Debug/Debug Logging |

- **What behaves differently**: a volume of 0 plays nothing (v1.1 played the sound at -80 dB, almost silent); a fast release, grab and release keeps the full delay and starts the base sound once (v1.1 cut the release loop early and started the base sound twice). The warnings at start are new.

---

## Recipes

**A - Lantern.** Base: a soft hum loop at 60. Held: a short click, Looping Off. Release: an air whoosh, Looping Off, 90. Resume On, delay 0.15.

**B - Music box.** Base: a music loop at 50. Held: the same music at 100, Looping On. Release: nothing. Resume On, delay 0: the music simply gets louder while held.

**C - Magic orb.** Base: nothing. Held: an energy loop. Release: a long reverb tail, Looping On. Resume Off: the tail loops until the next grab.

**D - One sound only.** Only `Held/Sound` set: silence, then a sound while the object is carried.

---

## Troubleshooting

| Symptom | Check |
|---|---|
| No sound on grab or release | The object needs a RigidBody that can be grabbed: "No RigidBodyComponent found" or "This object cannot be grabbed at scene start" in the script console. Check that a sound is assigned and its volume is above 0 |
| The sound stays where the object was | No Audio component on the object ("No AudioComponent found..." at start): add one. Or `Audio Component Name` is wrong ("not found on this object: using its first AudioComponent") |
| The release loop is cut almost at once | `Release/Base Resume Delay Seconds` is the length of the loop when `Resume Base After Release` is On: raise it (a warning says so at start), or turn Resume Off |
| The base sound and the release sound overlap | Set `Base Resume Delay Seconds` to the length of the release sound |
| The base sound never comes back | `Release/Resume Base After Release` Off, or `Base/Looping` Off with a short sound |
| Too loud or too quiet | Adjust the `Volume` of that sound (percent); 0 = muted |
| I want to know what the script does | Turn `Debug/Debug Logging` On: the script console shows the Audio component chosen and every sound start |

---

## Limits

- One object, one set of sounds: for two props, put the script on each.
- An avatar who leaves the scene while holding the object may leave the held sound playing until the next grab.
- The volume is applied when a sound starts, not while it plays.

---

## Related MPP Items

| Item | What it adds |
|---|---|
| **Light Drain And Restore Script** | A light that dims and a rainbow on the same prop while it is held. Store: https://www.sansar.com/store/listings/95238b17-f553-4656-88b6-6bf10e4070b9/light-drain-and-restore-script |
| **Gravity Drift On Grab Script** | The prop floats up like a balloon once released. Store: https://www.sansar.com/store/listings/d74417ad-2b75-41b2-9bd7-7a96cf12eef9/gravity-drift-on-grab-script |

---

*MPP - My Pretty Pixels. Sound States On Grab Script V1.1.2 (script `MPP - Sound States On Grab`). Store: https://www.sansar.com/store/listings/3495dbd5-f76f-452a-a43a-2445d5304815/sound-states-on-grab-script*