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:PlayEdit

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 soundEdit

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:CreateInstanceEdit

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 soundEdit

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:StopEdit

SoundInstance:Play()
SoundInstance:Stop()

SoundInstance:Pause, SoundInstance:ResumeEdit

Pauses or resumes an instance of a sound

SoundInstance:Pause()
SoundInstance:Resume()

SoundInstance:GetStateEdit

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:GetLoopEdit

Sets or gets whether the sound should loop or not.

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

SoundInstance:SetVolume, SoundInstance:GetVolumeEdit

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 soundEdit

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:GetPitchEdit

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:GetPanEdit

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

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

FANDOM