Audio3D

A node that plays sounds in 3D space. It can be used to play a looping sound or a one-off sound. See the Audio system for playing audio without using a node.

Inheritance: * Node * Node3D

---

SetSoundWave

Assign a sound wave asset to be played.

Sig: Audio3D:SetSoundWave(soundWave) - Arg: SoundWave soundWave SoundWave asset

---

GetSoundWave

Get the currently assigned sound wave.

Sig: soundWave = Audio3D:GetSoundWave() - Ret: SoundWave soundWave SoundWave asset

---

SetInnerRadius

Set the inner radius. The inner radius defines the distance away from the node at which the sound is the loudest. Going closer to the node won't increase the volume any further.

Sig: Audio3D:SetInnerRadius(radius) - Arg: number radius Inner radius

---

GetInnerRadius

Get the inner radius. The inner radius defines the distance away from the node at which the sound is the loudest. Going closer to the node won't increase the volume any further.

Sig: radius = Audio3D:GetInnerRadius() - Ret: number radius Inner radius

---

SetOuterRadius

Set the outer radius. The outer radius defines the distance away from the node at which the sound can't be heard anymore. Volume will increase when moving from the outer radius distance to the inner radius distance.

Sig: Audio3D:SetOuterRadius(radius) - Arg: number radius Outer radius

---

GetOuterRadius

Get the outer radius. The outer radius defines the distance away from the node at which the sound can't be heard anymore. Volume will increase when moving from the outer radius distance to the inner radius distance.

Sig: radius = Audio3D:GetOuterRadius() - Ret: number radius Outer radius

---

SetVolume

Set the volume multiplier.

Sig: Audio3D:SetVolume(volume) - Arg: number volume Volume

---

GetVolume

Get the volume multiplier.

Sig: volume = Audio3D:GetVolume() - Ret: number volume Volume

---

SetPitch

Set the pitch multiplier.

Sig: Audio3D:SetPitch(pitch) - Arg: number pitch Pitch

---

GetPitch

Get the pitch multiplier.

Sig: pitch = Audio3D:GetPitch() - Ret: number pitch Pitch

---

SetStartOffset

Adjust the start time when the audio is played.

Sig: Audio3D:SetStartOffset(offset) - Arg: number offset Time offset in seconds

---

GetStartOffset

Get the start time offset.

Sig: offset = Audio3D:GetStartOffset() - Ret: number offset Time offset in seconds

---

SetPriority

Set the priority of this node's audio. If the number of concurrent sounds has been reached, sounds with lower priority will be stopped to allow sounds with higher priority to play. Default priority is 0. Priority is stored as 32-bit integer and can be negative.

Sig: Audio3D:SetPriority(priority) - Arg: integer priority Sound priority

---

GetPriority

Get the audio priority of this node. If the number of concurrent sounds has been reached, sounds with lower priority will be stopped to allow sounds with higher priority to play. Default priority is 0. Priority is stored as 32-bit integer and can be negative.

Sig: priority = Audio3D:GetPriority() - Ret: integer priority Sound priority

---

SetAttenuationFunc

Set the sound intensity attenuation function. The attenuation controls how quickly a sound's volume fades out when moving from the inner radius to the outer radius, or alternatively, how quickly a sound's volume fades in when moving from the outer radius to the inner radius.

See the AttenuationFunc enumeration.

Sig: Audio3D:SetAttenuationFunc(attenFunc) - Arg: AttenuationFunc(integer) attenFunc Attenuation function

---

GetAttenuationFunc

Get the sound intensity attenuation function. The attenuation controls how quickly a sound's volume fades out when moving from the inner radius to the outer radius, or alternatively, how quickly a sound's volume fades in when moving from the outer radius to the inner radius.

See the AttenuationFunc enumeration.

Sig: attenFunc = Audio3D:GetAttenuationFunc() - Ret: AttenuationFunc(integer) attenFunc Attenuation function

---

SetLoop

Set whether the sound wave should loop.

Sig: Audio3D:SetLoop(loop) - Arg: boolean loop Loop

---

GetLoop

Check if the sound wave is set to loop after finishing playing.

Sig: loop = Audio3D:GetLoop() - Ret: boolean loop Loop

---

SetAutoPlay

Set whether sound should automatically play when the node starts (i.e. when the node's Start() function is called).

Sig: Audio3D:SetAutoPlay(autoPlay) - Arg: boolean autoPlay Auto play

---

GetAutoPlay

Check if the sound is set to automatically play when the node starts.

Sig: autoPlay = Audio3D:GetAutoPlay() - Ret: boolean autoPlay Auto play

---

GetPlayTime

Return the amount of time in seconds that this node has been playing audio.

Sig: playTime = Audio3D:GetPlayTime() - Ret: number playTime Time in seconds that audio has been playing.

---

GetDuration

Duration of the currently assigned SoundWave in seconds. Returns 0.0 if no wave is assigned.

Sig: seconds = Audio3D:GetDuration() - Ret: number seconds Wave duration

---

GetPlayTimeNormalized

Current play position as [0, 1] of the assigned wave's duration. Looping nodes wrap (fmod); non-looping nodes clamp at 1.0. Returns 0.0 when no wave is assigned or duration is 0. Drop-in for progress sliders and seek bars.

Sig: t = Audio3D:GetPlayTimeNormalized() - Ret: number t Normalized cursor in [0, 1]

---

IsPlaying

Check if this node is currently playing a sound wave.

Sig: playing = Audio3D:IsPlaying() - Ret: boolean playing True if a sound wave is playing

---

IsAudible

Check if this node can be heard by the audio receiver (e.g. the player, or camera). If the audio receiver moves outside of this node's outer radius, then this will return false. See World.SetAudioReceiver() for how to change the receiver.

Sig: audible = Audio3D:IsAudible() - Ret: boolean audible True if receiver can hear the audio

---

PlayAudio

Play this node's assigned sound wave. An Audio3D node can only play one sound wave at a time. If the cursor is already past the end of the wave (e.g. after a natural finish), it rewinds to the beginning automatically.

Two forms: - Audio3D:PlayAudio() — resume / start playback on the currently-assigned wave. - Audio3D:PlayAudio(wave, loop) — assign wave, set the loop flag, then play. Equivalent to SetSoundWave(wave) → SetLoop(loop) → Play() in one call.

Alias: Play (no-arg form only).

Sig: Audio3D:PlayAudio() Sig: Audio3D:PlayAudio(soundWave, loop) - Arg: SoundWave soundWave Wave to assign - Arg: boolean loop Whether the assigned wave should loop

---

PauseAudio

Pause the sound wave that is being played. Calling PlayAudio() later will pick up where it left off.

Alias: Pause

Sig: Audio3D:PauseAudio()

---

StopAudio

Stop the sound wave that is being played. This will also reset the current play time back to the beginning of the sound wave. Use PauseAudio() if you want to pick up where it left off.

Alias: Stop

Sig: Audio3D:StopAudio()

---

Play

Alias for PlayAudio() — shorter spelling for the transport play call.

Sig: Audio3D:Play()

---

Pause

Alias for PauseAudio() — shorter spelling for the transport pause call.

Sig: Audio3D:Pause()

---

Stop

Alias for StopAudio() — shorter spelling for the transport stop call.

Sig: Audio3D:Stop()

---

ResetAudio

Reset the play position back to the beginning of the sound wave. This works whether the sound wave is playing or not.

Sig: Audio3D:ResetAudio()

---

PlayOneShot

Fire a transient 3D voice at this node's world position using its inner radius, outer radius, and attenuation curve. The node's own playback (if any) is untouched — this allocates a fresh voice that does not loop and decays on its own. Use it for footstep/impact sounds emitted from a positional node without disturbing its main loop.

Volume and pitch default to this node's current values (GetVolume() / GetPitch()). Pass an explicit number to override; pass a negative value to force-inherit.

Sig: Audio3D:PlayOneShot(soundWave, volume=current, pitch=current, priority=0) - Arg: SoundWave soundWave Wave to play - Arg: number volume Volume multiplier (omit or pass < 0 to inherit the node's GetVolume()) - Arg: number pitch Pitch multiplier (omit or pass < 0 to inherit the node's GetPitch()) - Arg: integer priority Sound priority

---

Seek

Move playback to an absolute time in seconds. If the node is currently audible, the live voice is released and the next AudioManager tick re-spawns it at the new cursor — works seamlessly while the song is playing. If the node is paused, the new position takes effect on the next PlayAudio(). Values past the end wrap (mod against duration).

Sig: Audio3D:Seek(seconds) - Arg: number seconds Absolute play time in seconds

---

SeekNormalized

Move playback to a [0, 1] fraction of the assigned wave's duration. Drop-in for slider scrubbing — pair with GetPlayTimeNormalized() for round-trip slider sync.

Sig: Audio3D:SeekNormalized(t) - Arg: number t Position as fraction of duration in [0, 1]

---

Signals

Audio3D emits the following signal that scripts can connect to:

Signal	Emitted When
OnFinished	The current SoundWave reaches the end of one play. Non-looping voices fire it once on natural end; looping voices fire it every wrap, which lets playlists auto-advance even from looped tracks. User-initiated StopAudio() does not fire it.

Scripts can also define a callback function with the same name (OnFinished()) which will be called automatically:

function MyAudioScript:OnFinished()
    -- the sound finished playing on this Audio3D node
end

For a global "any sound finished" notification (including 2D Audio.PlaySound2D voices and other Audio3D nodes), subscribe to SignalBus.Subscribe("SoundFinished", ...) instead — see Audio Signals.

---

Audio analysis

Real-time analysis helpers for building visualizers. Each returns 0 (or a zero-filled table) when the node isn't currently audible — visualizer code doesn't have to gate on IsPlaying(). See Audio.md for the equivalent free-function API and a longer explanation.

---

GetRMS

Root-mean-square amplitude of the most recent playback window.

Sig: rms = Audio3D:GetRMS() - Ret: number rms RMS amplitude in [0, 1]

---

GetLoudness

Perceptual loudness in [0, 1], computed from RMS with a -60 dB floor. Drop-in for bar heights.

Sig: loudness = Audio3D:GetLoudness() - Ret: number loudness Normalized loudness

---

GetLoudnessDb

Raw dBFS loudness clamped to [-60, 0].

Sig: dB = Audio3D:GetLoudnessDb() - Ret: number dB Loudness in dBFS

---

GetFrequencies

Average FFT magnitude in the band [startHz, endHz]. Use for 3-bar bass/mid/treble visualizers.

Sig: magnitude = Audio3D:GetFrequencies(startHz, endHz) - Arg: number startHz Lower edge of the band (Hz) - Arg: number endHz Upper edge of the band (Hz) - Ret: number magnitude Average band magnitude

---

GetSpectrum

FFT magnitudes binned across [startHz, endHz]. Returns a Lua array of numBins floats.

Sig: bins = Audio3D:GetSpectrum(startHz, endHz, numBins) - Arg: number startHz Lower edge of the range (Hz) - Arg: number endHz Upper edge of the range (Hz) - Arg: integer numBins Number of output bins (1..1024) - Ret: { number, ... } bins Array of magnitudes, length numBins

---