SetGameSoundVolume

setGameSoundVolume

PLANNED FOR UPDATE 0.1.7

This function is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.

Requests a volume change for one game sound owned by the current client resource.

Syntax

number|false setGameSoundVolume(number handle, number volume)

Parameters

Name	Type	Required	Description
handle	number	yes	Positive integer handle returned by playSoundFromGame or playSound3DFromGame, owned by the current resource. Valid IDs do not exceed 9007199254740991.
volume	number	yes	Finite per-instance volume between 0 and 1, inclusive.

Returns

Returns a positive integer request ID when the command is accepted for asynchronous processing, or false when rejected locally. The request ID identifies this command; it is not a new sound handle. Observe onClientGameSoundResult for the result.

Examples

Lower a campfire sound after one second and stop it after four seconds:

local sound = playSoundFromGame("event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop", {volume = 0.5})
if sound then
    setTimer(function()
        local requestId = setGameSoundVolume(sound, 0.15)
        if not requestId then outputDebugString("Volume request rejected") end
    end, 1000, 1)
    setTimer(function() stopGameSound(sound) end, 4000, 1)
end

Notes

• Planned for update 0.1.7; not included in public 0.1.6.
• Available only in client-side resource scripts. See Game audio for ownership, lifecycle, limits and server-triggered playback.
• Controls require a nonterminal handle owned by the current resource. Unknown, expired, foreign-resource or terminal handles are rejected.
• A return value of false has no result event for that attempted command. Rejection can also mean the game is not ready or a request limit has been reached.
• Control acceptance does not change the cached playback state immediately. Native acknowledgements and observed state changes arrive asynchronously.
• Volume affects only this instance. A volume of 0 does not stop or release the sound. The cached state does not expose the current volume.