Sound

Category: Executor Tier: Basic

Purpose

Plays, stops, and controls audio including sound effects, music, UI feedback, and 3D positional audio.

Visual Reference

As added to your scene

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.

…

Generated UI Mockup — showing expanded properties

Sound

-

x

Name:

Label this brick...

Sound Path:

v

Mode:

Play

Audio Mode:

Mono

Seek Sec:

5.0

v

Scope:

Local

Prefix:

sound

v

Loop Source:

Button

Loop Scope:

Local

Volume %

100.0

v

Vol (dB)

0.0

v

Speed

1.0

v

Pitch (semi)

0.0

v

Spatial Sound

Pan

0.0

v

Max Dist

100.0

v

Atten

1.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:

...