---
generated_by: gdlink-build
generated_at: 2026-06-23T12:34:28Z
do_not_edit: true
title: Sound
brick_type: executor
tier: Basic
generated: true
---
# Sound
**Category:** Executor
**Tier:** Basic
## Purpose
Plays, stops, and controls audio including sound effects, music, UI feedback, and 3D positional audio.
## Visual Reference
```{raw} html
```
## When To Use
- Weapon sounds (gunshots, sword swings)
- Footstep sounds (walking, running)
- Background music (ambient, combat, menu)
- UI sounds (button clicks, menu navigation)
- Environmental sounds (wind, water, fire)
- Voice lines (dialogue, alerts)
- Collision sounds (impacts, explosions)
- Victory/defeat music
## Runtime Behavior
**Executes**: When activated, performs audio playback operations
**Runtime Notes**
- `Play` is idempotent for an already active matching stream on the same host. A continuous trigger can keep driving live parameter updates without restarting the sound every tick.
- Bound `volume_percent`, `volume_db`, `speed`, `pitch_semitones`, `stereo_pan`, `max_distance`, and `attenuation` are refreshed every native tick for the currently owned playing sound, even after the initial `Play` pulse has passed.
- `mode`, `loop`, `sound_path`, and spatial-mode/player-class changes still apply on explicit execution, not as passive every-tick rewrites.
- `Seek To` moves the current owned player to `seek_seconds`; `Seek Forward` and `Seek Backward` offset the current playback position by `seek_seconds`. These modes operate on the cached player created by `Play`.
- When `expose_playback=true`, the executor publishes current playback position, loaded stream duration, normalized percent, and playing state for UI sliders, timers, playlist controls, and audio-driven interactions. New scenes should map each output to an explicit variable; `expose_prefix` remains as a saved-scene compatibility fallback.
...
```{raw} html
Volume %100.0
v
Vol (dB)0.0
v
Speed1.0
v
Pitch (semi)0.0
v
Spatial Sound
Pan0.0
v
Max Dist100.0
v
Atten1.0
v
Expose
Loop
Verbose
```
## Properties
| Property | Type | Default | Notes |
|---|---|---|---|
| Sound Path | string | | Path to audio file (e.g. res://sounds/beep.wav) |
| Mode | option | Play | Shared audio surface. Mono = non-positional AudioStreamPlayer, Stereo = left/right panning, Spatial = AudioStreamPlayer2D/3D. |
| Audio Mode | option | Mono | Mono: centered non-positional playback. Stereo: simple left/right panning. Spatial: 2D/3D positional falloff. |
| Volume % | float | 100.0 | Master volume (0 = mute, 100 = full). Combined with Vol (dB) trim. |
| Vol (dB) | float | 0.0 | Fine-tune trim in decibels, added on top of Volume %. 0 dB = no change. |
| Speed | float | 1.0 | Playback rate (0.5 = half speed, 2.0 = double). Independent from Pitch. |
| Pitch (semi) | float | 0.0 | Transpose in semitones (+12 = octave up, -12 = octave down). Uses pitch shift so Speed remains playback rate. |
| Seek Sec | float | 5.0 | Seconds used by Seek To / Seek Forward / Seek Backward |
| Expose | bool | False | Write playback position, duration, percent, and playing state into variables |
| Scope | option | Local | Where exposed playback variables are written |
| Position Var | variable_name | | Destination variable for current playback position in seconds |
| Duration Var | variable_name | | Destination variable for loaded track duration in seconds |
| Percent Var | variable_name | | Destination variable for normalized playback percent 0-1 |
| Playing Var | variable_name | | Destination variable for playback state |
| Prefix | string | sound | Compatibility fallback when explicit output variables are empty |
| Loop | bool | False | Loop sound indefinitely |
| Loop Source | option | Button | Button uses the Loop toggle. Variable reads Bool or Int (0=off, nonzero=on). |
| Loop Var | variable_name | | Bool or Int variable that controls looping at runtime |
| Loop Scope | option | Local | |
| Spatial Sound | bool | False | Legacy compatibility toggle. New scenes should use Audio Mode. |
| Pan | float | 0.0 | [Stereo] -1 = left, 0 = center, 1 = right. |
| Max Dist | float | 100.0 | [Spatial] Maximum hearing distance |
| Atten | float | 1.0 | [Spatial] How quickly sound fades with distance |
| Verbose | bool | False | Log sound player type, path, volume, pitch, and spatial settings (controlled by ladybug button) |
## Example Use Cases
**Gunshot Sound**:
```
Mouse(Left Button, tap=true) -> AND -> Sound(sound=gunshot.wav, mode=Play, volume=-5.0)
// Play gunshot at slightly reduced volume
```
**Footstep Sounds**:
> Sample inspector layout removed for compatibility.
**Background Music**:
```
Always -> AND -> Sound(sound=ambient_music.ogg, mode=Play, loop=true, volume=-10.0)
// Play looping ambient music at background volume
```
**Spatial Sound**:
```
Collision(Player) -> AND -> Sound(sound=alarm.wav, mode=Play, 3d=true, max_distance=50.0)
// Play alarm with positional falloff. Uses AudioStreamPlayer3D on Node3D hosts and AudioStreamPlayer2D on Node2D hosts.
```
**UI Button Sound**:
```
Signal(button_pressed) -> AND -> Sound(sound=ui_click.wav, mode=Play, volume_percent=75)
// On Control hosts, plays a mono AudioStreamPlayer suitable for UI feedback. 75% master, no dB trim.
```
**Stereo Pan**:
```
Variable(menu_pan, Not Equal, 0) -> AND -> Sound(sound=hover.wav, audio_mode=Stereo, stereo_pan=menu_pan)
// Pans non-spatial audio left/right without positional distance attenuation.
```
**Victory Music**:
> Sample inspector layout removed for compatibility.
**Variable Speed + Pitch**:
```
Variable(rpm, Less, 1500) -> AND -> Sound(sound=engine.wav, speed=0.8, pitch_semitones=0)
Variable(rpm, Greater, 3000) -> AND -> Sound(sound=engine.wav, speed=1.5, pitch_semitones=7)
// Slow engine plays at 0.8x rate. Revved engine plays at 1.5x rate transposed up a fifth.
// Speed = playback rate; pitch_semitones = musical transpose without changing playback rate.
```
**Array Playlist + Seek Readback**:
```
...
