Sound States On Grab Script

Audio Behavior Scripting – Dynamic Grab/Release States

------------------------------

OVERVIEW

SoundStatesOnGrab manages three audio states on an object:

1. Base (Idle) – background sound when the object is free
2. Held – sound while the object is grabbed
3. Release – sound when the object is released (loop or one-shot)

The script prioritizes an AudioComponent attached to the object (sound follows the object) and falls back to PlaySoundAtPosition if none is found.
Volume is defined in percent (0–200%), internally converted to decibels:
20·log10(percent / 100) → 200% ≈ +6 dB (roughly twice the amplitude).

If a RigidBodyComponent is present, the script automatically subscribes to Grab and Release events.
At startup, it can optionally auto-play the base loop if assigned.

------------------------------

INSPECTOR PARAMETERS

Audio Component Selection
• Audio Component Name (string) — Name of the AudioComponent to use. If empty, the first one is used, or playback defaults to world position.

Base (Idle) Sound
• Base Sound (SoundResource) — Played when the object is idle (typically looped)
• Volume (0–200%, default 100)
• Looping (default: On)
→ May auto-play on start if assigned

Held Sound (On Grab)
• Held Sound — Played when the object is grabbed
• Volume and Looping (default: On)
→ Stops base and release sounds before starting held sound

Release Sound (On Release)
• Release Sound — Played when the object is released
• Volume and Looping (default: Off)
→ If looping is enabled, plays until interrupted or base resumes

Auto-Resume Base
• Resume Base After Release (default: On)
• Base Resume Delay (0–5 s, default: 0.10 s)
→ Resumes the base loop after release or stops the release loop before doing so

Debug Log
• Enables log messages for playback events and diagnostics

------------------------------

INTERNAL LOGIC

Event Flow
Grab: stop base → stop release → start held
Release: stop held → play release → optionally resume base

Playback Handling
Priority: PlaySoundOnComponent
Fallback: PlaySoundAtPosition (object world position)

Volume Conversion
Automatic dB conversion
0% = silent (-80 dB), 200% ≈ +6 dB

------------------------------

SETUP GUIDE

1. Add the script to your object
2. (Optional) Add and name an AudioComponent
3. Assign Base, Held, and Release sounds
4. (Recommended) Add a RigidBodyComponent
5. Adjust volume, looping, and delay values as needed

------------------------------

EXAMPLE RECIPES

Lamp – hum idle, click on grab, whoosh on release
Base: hum_loop (loop On, 60%)
Held: click (loop Off, 100%)
Release: air_whoosh (loop Off, 90%)
Resume: On / Delay 0.15 s

Musical Pad – idle pad, arpeggio on grab, reverb tail on release
Base: pad_idle (loop On, 40%)
Held: pluck_arpeggio (loop On, 100%)
Release: reverb_tail (loop On)
Resume: On / Delay 1 s

------------------------------

TROUBLESHOOTING

• No sound on Grab/Release: check that a RigidBodyComponent is present.
• Sound plays at a fixed point: check the AudioComponent name or add one.
• Volume too low or high: adjust the percentage instead of stacking gain nodes.

------------------------------

Enjoy and Keep Good Vibes.
Hugs from Morgane.

------------------------------