StopGameSound

stopGameSound

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 that a game sound owned by this client resource stop, including a sound whose play request is still loading.

Syntax

number|false stopGameSound(number handle)

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.

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

Start a campfire sound and cancel or stop it after three seconds:

local sound = playSoundFromGame("event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop", {volume = 0.3})
if sound then
    setTimer(function()
        local requestId = stopGameSound(sound)
        if not requestId then
            outputDebugString("Stop rejected; the sound may already have ended")
        end
    end, 3000, 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.
• Successful stopping reports state = "stopped". A stopped, finished or failed sound cannot be restarted with its old handle.
• Cancelling a pending play can produce a successful result for the original play request whose data already says stopped and confirmed = false. Other queued controls for that sound can fail with cancelled.
• This stops only the selected owned instance. It does not stop unrelated game ambience, music or dialogue.