SoundService

Provides sound-related functions.

# Methods

[{"index":"boolean IsPlayBGM() (ClientOnly)","0":"Returns whether background music is playing."}]

[{"index":"void LoadSound(string id) (ClientOnly)","0":"Loads the audio clip."}]

[{"index":"void PauseBGM() (Client)","0":"Pauses the background music being played."}]

[{"index":"void PauseBGM(Entity messageOwnerEntity = nil) (Client)","0":"Pauses the background music being played."}]

[{"index":"void PauseBGM(string targetUserId = nil) (Client)","0":"Pauses the background music being played."}]

[{"index":"void PauseSound(string id) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clip playing through SoundService. Background music is not included."}]

[{"index":"void PauseSound(string id, Entity messageOwnerEntity = nil) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clip playing through SoundService. Background music is not included."}]

[{"index":"void PauseSound(string id, string targetUserId = nil) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clip playing through SoundService. Background music is not included."}]

[{"index":"void PlayBGM(string id, float volume) (Client)","0":"Plays background music."}]

[{"index":"void PlayBGM(string id, float volume, Entity messageOwnerEntity = nil) (Client)","0":"Plays background music."}]

[{"index":"void PlayBGM(string id, float volume, string targetUserId = nil) (Client)","0":"Plays background music."}]

[{"index":"void PlayLoopSound(string id, float volume) (Client)","0":"Plays the audio clip repeatedly."}]

[{"index":"void PlayLoopSound(string id, float volume, Entity messageOwnerEntity = nil) (Client)","0":"Plays the audio clip repeatedly."}]

[{"index":"void PlayLoopSound(string id, float volume, string targetUserId = nil) (Client)","0":"Plays the audio clip repeatedly."}]

[{"index":"void PlayLoopSoundAtPos(string id, Vector3 pos, Entity listener, float volume) (Client)","0":"Plays the audio clip repeatedly at the target location."}]

[{"index":"void PlayLoopSoundAtPos(string id, Vector3 pos, Entity listener, float volume, Entity messageOwnerEntity = nil) (Client)","0":"Plays the audio clip repeatedly at the target location."}]

[{"index":"void PlayLoopSoundAtPos(string id, Vector3 pos, Entity listener, float volume, string targetUserId = nil) (Client)","0":"Plays the audio clip repeatedly at the target location."}]

[{"index":"void PlaySound(string id, float volume) (Client)","0":"Plays the audio clip."}]

[{"index":"void PlaySound(string id, float volume, Entity messageOwnerEntity = nil) (Client)","0":"Plays the audio clip."}]

[{"index":"void PlaySound(string id, float volume, string targetUserId = nil) (Client)","0":"Plays the audio clip."}]

[{"index":"void PlaySoundAtPos(string id, Vector3 pos, Entity listener, float volume) (Client)","0":"Plays the audio clip at the target location."}]

[{"index":"void PlaySoundAtPos(string id, Vector3 pos, Entity listener, float volume, Entity messageOwnerEntity = nil) (Client)","0":"Plays the audio clip at the target location."}]

[{"index":"void PlaySoundAtPos(string id, Vector3 pos, Entity listener, float volume, string targetUserId = nil) (Client)","0":"Plays the audio clip at the target location."}]

[{"index":"void ResumeBGM() (Client)","0":"Resumes paused background music."}]

[{"index":"void ResumeBGM(Entity messageOwnerEntity = nil) (Client)","0":"Resumes paused background music."}]

[{"index":"void ResumeBGM(string targetUserId = nil) (Client)","0":"Resumes paused background music."}]

[{"index":"void ResumeSound(string id) (Client)","0":"Among the audio clips paused through SoundService, resumes playing all audio clips corresponding to the id passed as a parameter. Background music is not included."}]

[{"index":"void ResumeSound(string id, Entity messageOwnerEntity = nil) (Client)","0":"Among the audio clips paused through SoundService, resumes playing all audio clips corresponding to the id passed as a parameter. Background music is not included."}]

[{"index":"void ResumeSound(string id, string targetUserId = nil) (Client)","0":"Among the audio clips paused through SoundService, resumes playing all audio clips corresponding to the id passed as a parameter. Background music is not included."}]

[{"index":"void SetBGMVolume(float volume) (Client)","0":"Sets the volume of background music."}]

[{"index":"void SetBGMVolume(float volume, Entity messageOwnerEntity = nil) (Client)","0":"Sets the volume of background music."}]

[{"index":"void SetBGMVolume(float volume, string targetUserId = nil) (Client)","0":"Sets the volume of background music."}]

[{"index":"void StopBGM(boolean immediately) (Client)","0":"Stops playing the background music."}]

[{"index":"void StopBGM(boolean immediately, Entity messageOwnerEntity = nil) (Client)","0":"Stops playing the background music."}]

[{"index":"void StopBGM(boolean immediately, string targetUserId = nil) (Client)","0":"Stops playing the background music."}]

[{"index":"void StopSound(string id) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clips playing through SoundService. Background music is not included."}]

[{"index":"void StopSound(string id, Entity messageOwnerEntity = nil) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clips playing through SoundService. Background music is not included."}]

[{"index":"void StopSound(string id, string targetUserId = nil) (Client)","0":"Pauses all audio clips corresponding to the id passed as a factor among audio clips playing through SoundService. Background music is not included."}]

##### inherited from Service:

[{"index":"EventHandlerBase ConnectEvent(string key, IScriptFunction eventHandler)","0":"Links events. When a key-type event occurs in this service, a handler is notified. The handler receives event parameters."}]

[{"index":"EventHandlerBase ConnectEvent(Type eventType, IScriptFunction eventHandler)","0":"Links events. This service notifies a handler when an eventType event occurs. The handler receives event parameters."}]

[{"index":"boolean DisconnectEvent(string key, EventHandlerBase eventHandler)","0":"Disconnects the event with the key-type event and the handler."}]

[{"index":"boolean DisconnectEvent(Type eventType, EventHandlerBase eventHandler)","0":"Disconnects the eventType event from its handler."}]

[{"index":"void SendEvent(EventType sendEvent)","0":"Generates an event."}]

# Events

[{"index":"SoundPlayStateChangedEvent","0":"Event that occurs when the playback state of the background music for the SoundService and sound effect for the SoundComponent change."}]

# Examples

#### PlayBGM

The following is an example of creating a button that can play background music at startup and pause or resume play of that background music.
    
    
    @Component
    script BGMController extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        	local defaultUIGroup = _EntityService:GetEntityByPath("/ui/DefaultGroup")
        	if defaultUIGroup == nil then
        		return
        	end
    
        	_SoundService:PlayBGM("92dc353287df4b7894dfcec950edea49", 1)
    
        	local buttonClickCallback = function()
        		if _SoundService:IsPlayBGM() then
        			 _SoundService:PauseBGM()
        		else
        			_SoundService:ResumeBGM()
        		end
        	end
    
        	local bgmToggleButton = _SpawnService:SpawnByModelId("Model Entry ID", "BGMToggleButton", Vector3.zero, defaultUIGroup)
        	bgmToggleButton.UITransformComponent.Position.y = 350
        -- 	bgmToggleButton:ConnectEvent(ButtonClickEvent, buttonClickCallback)  -- [Commented: MLUA requires handler pattern]
    
        	local bgmToggleText = _SpawnService:SpawnByModelId("Model Entry ID", "BGMToggleText", Vector3.zero, bgmToggleButton).TextComponent
        	bgmToggleText.Text = "TOGGLE BGM"
        	bgmToggleText.Bold = true
        	bgmToggleText.FontColor = Color.white
        	bgmToggleText.UseOutLine = true
        end
    end
    

#### StopSound

The following is an example of collectively stopping audio clips played via `SoundService`. Fireworks audio clips are played 5 times over 5 seconds after the game starts, and when you press the "STOP FIREWORK" button, the fireworks sounds will all be stopped.
    
    
    @Component
    script FireworkSoundController extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        	local defaultUIGroup = _EntityService:GetEntityByPath("/ui/DefaultGroup")
        	if defaultUIGroup == nil then
        		return
        	end
    
        	-- Plays the audio clip five times for 5 seconds.
        	for i=1, 5 do
        		_SoundService:PlayLoopSound("0b52c64808f149e18532ec75417d27e1", 1)
        		wait(1)
        	end
    
        	local buttonClickCallback = function()
        		_SoundService:StopSound("0b52c64808f149e18532ec75417d27e1")
        	end
    
        	local stopFireworkSoundButton = _SpawnService:SpawnByModelId("Model Entry ID", "BGMToggleButton", Vector3.zero, defaultUIGroup)
        	stopFireworkSoundButton.UITransformComponent.Position.y = 250
        -- 	stopFireworkSoundButton:ConnectEvent(ButtonClickEvent, buttonClickCallback)  -- [Commented: MLUA requires handler pattern]
    
        	local stopFireworkSoundText = _SpawnService:SpawnByModelId("Model Entry ID", "BGMToggleText", Vector3.zero, stopFireworkSoundButton).TextComponent
        	stopFireworkSoundText.Text = "STOP FIREWORK"
        	stopFireworkSoundText.Bold = true
        	stopFireworkSoundText.FontColor = Color.white
        	stopFireworkSoundText.UseOutLine = true
        end
    end
    

# SeeAlso

  * UITransformComponent
  * Vector3
  * EntityService
  * SpawnService
  * [Creating Sound Effects](/docs?postId=578)