Scripting Reference/Sound

Sound assets let you play sound effects. You can create and upload sounds in your project and then play them back in scripting.

You can get a Sound asset by using CraftStudio.FindAsset.

There are two ways to play sounds: either directly by using the Sound asset (which doesn't give you much control but is good for one-shot effects) or by creating a SoundInstance (which lets you pause / stop / resume / loop / set parameters while playing).

Sound:Play

Plays the specified sound once. You can call it multiple times to play the same sound several times. The volume can be anything between 0.0 (mute) and 1.0 (full). You can also control the sound's pitch (both negative and positive numbers are accepted) and pan (left / right positioning).

For looping and stopping playing sounds, check out Sound:CreateInstance below.

Sound:Play(
    [number] volume=1,
    [number] pitch=0,
    [number] pan=0
)

Example: Playing a sound

local sound = CraftStudio.FindAsset( "my sound" )

-- Plays the sound with default parameters (full volume)
sound:Play()

-- Plays the sound at half volume, with a higher pitch and panning to the right
sound:Play( 0.5, 0.8, 1 )

Sound:CreateInstance

Creates an instance of the sound. Instances can be paused / resumed / stopped / looped and their parameters can be updated while playing.

[SoundInstance] Sound:CreateInstance()

Example: Looping a sound

local sound = CraftStudio.FindAsset( "my sound" )

-- Create an instance of the sound
local myInstance = sound:CreateInstance()

-- Set the instance to loop:
myInstance:SetLoop( true )

-- Play it
myInstance:Play()

-- ... Later on ...
-- Stop it
myInstance:Stop()

SoundInstance:Play, SoundInstance:Stop

SoundInstance:Play()
SoundInstance:Stop()

SoundInstance:Pause, SoundInstance:Resume

Pauses or resumes an instance of a sound

SoundInstance:Pause()
SoundInstance:Resume()

SoundInstance:GetState

Returns the sound instance's current state. Possible states are SoundInstance.State.Playing, SoundInstance.State.Paused and SoundInstance.State.Stopped.

[SoundInstance.State] SoundInstance:GetState()

SoundInstance:SetLoop, SoundInstance:GetLoop

Sets or gets whether the sound should loop or not.

SoundInstance:SetLoop( [boolean] loop )
[boolean] SoundInstance:GetLoop()

SoundInstance:SetVolume, SoundInstance:GetVolume

Sets volume of sound instance, in the 0.0-1.0 range. With simple linear tweening, it may be used for fading music in/out.

SoundInstance:SetVolume( [number] volume )
[number] SoundInstance:GetVolume()

Example: Fading in a sound

function Behavior:Awake()
    local sound = CraftStudio.FindAsset( "some sound" )
    self.mySoundInstance = sound:CreateInstance()
    self.mySoundVolume = 0
    
    self.mySoundInstance:SetVolume( 0 )
    self.mySoundInstance:Play()
end

function Behavior:Update()
    if self.mySoundVolume < 1 then
        self.mySoundVolume = self.mySoundVolume + 0.05
        self.mySoundInstance:SetVolume( self.mySoundVolume )
    end
end

SoundInstance:SetPitch, SoundInstance:GetPitch

Gets or sets the pitch adjustment, ranging from -1.0 (down one octave) to 1.0f (up one octave). 0.0f is normal pitch.

SoundInstance:SetPitch( [number] pitch )
[number] SoundInstance:GetPitch()

SoundInstance:SetPan, SoundInstance:GetPan

Panning, ranging from -1.0f (full left) to 1.0f (full right). 0.0f is centered.

SoundInstance:SetPan( [number] pan )
[number] SoundInstance:GetPan()