Audio¶

Overview¶

The audio system allows plugins to create sound instances for builtin sound resources or for their custom audio resources, and control their playback.

Example¶

local curSound = audio.Play(Plugin.resources.click_long)

curSound:Pause()
print(curSound.isPaused, curSound.isPlaying)
curSound:Resume()
print(curSound.isPaused, curSound.isPlaying)

curSound:Stop()

local soundParams = audio.SoundPlaybackParams.new()
soundParams.type = audio.SoundType.SCRIPT
soundParams.audioBus = audio.AudioBus.SFX
soundParams.volume = 0.5 -- 50%
soundParams.numLoops = 2
soundParams.delayTick = 0
soundParams.samplingRate = 100 -- Default = 256, which is also used when samplingRate is 0

-- Disable spatial audio with audio.EmitterShape.NONE
-- Using audio.EmitterShapes.SPHERE/BOX/SPHERE_NO_PANNING/BOX_NO_PANNING enables that instead
soundParams.emitterShape = audio.EmitterShape.NONE

-- These are only relevant for spatial audio sounds
soundParams.origin = Vector3.new(0.0)
soundParams.minDistance = 0.0
soundParams.maxDistance = 1.0
soundParams.level = -1

audio.Play(Plugin.resources.click, soundParams)

-- Sound parameters are reusable
audio.Play(Plugin.resources.click_long, soundParams)

Enumerations¶

audio.SoundType¶

Identifies the type of sound associated with a SoundInstance's playback.
Unless otherwise stated, these are just used to categorise sounds and don't affect playback.

audio.AudioBus¶

Identifies the audio bus a sound instance is playing into, used by the audio mixer system.
These are used to identify certain elements used during audio playback, such as the desired volume based on game settings.

audio.EmitterShape¶

Controls how spatial audio applies to this sound instance.

Types¶

audio.SoundInstance¶

SoundInstances represent a single playable sound. By default they're created dormant, and a plugin must then manually call Play on them for playback to start.

SoundInstances can also expire naturally (via shutdown of the plugin they were created in, or by being played and finishing), or through script requests (via Stop).

Methods¶

Start¶

function audio.SoundInstance:Start(ticksDelay : Int?)

Starts playing this sound instance, or requests playback to start in the specified number of logic ticks.

Does nothing if this sound has already expired.

Stop¶

function audio.SoundInstance:Stop()

Stops playing this sound instance immediately.

Does nothing if this sound has already expired.

Pause¶

function audio.SoundInstance:Pause()

Pauses playback for this sound instance immediately.

Does nothing if this sound has already been paused or has expired.

Resume¶

function audio.SoundInstance:Resume()

Resumes playback for this sound instance immediately.

Does nothing if this sound isn't paused or has expired.

Properties¶

audio.SoundPlaybackParams¶

Functions¶

audio.Play¶

function audio.Play(resource : PluginAudioResource, params : audio.SoundPlaybackParams?) -> audio.SoundInstance?
function audio.Play(builtinResourceID : Int, params : audio.SoundPlaybackParams?) -> audio.SoundInstance?

Creates an instance for an audio resource that can then be played back.

audio.Stop¶

function audio.Stop(soundInstanceID : Int)

Immediately stops playback for the sound instance associated with the provided ID if it exists and is live.

audio.StopSoundsUsingResource¶

function audio.StopSoundsUsingResource(resource : PluginAudioResource)
function audio.StopSoundsUsingResource(builtinResourceID : Int)

Stops playback for all sound instances currently using the provided resource.