GetGameSoundState

getGameSoundState

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.

Reads the latest cached state of a game sound owned by the current client resource.

Syntax

table|false getGameSoundState(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 Lua table, or false if the handle is unknown, belongs to another resource, was removed by lifecycle cleanup, or its terminal history record has been evicted. Reading state does not submit a native query.

The initial table contains id (number), key (string), spatial (bool), state = "loading" and confirmed = false. Later result fields are merged into this table; fields may be absent until supplied.

Field	Type	Meaning
state	string	loading, starting, playing, paused, finished, stopped or failed.
confirmed	bool	Playback observations set this to whether playing has been observed. Successful stopping of an existing instance also sets it to true; cancellation before start leaves it false. It never proves audibility.
mode	string	When supplied: world-3d, listener-relative or authored-2d.
reason	string	When supplied: a failure reason or an empty string.
operation, accepted	string, bool	Most recent merged control acknowledgement. Operations are volume, pause, position or distance.
nativeMs	number	When supplied: native processing time in milliseconds for the result that last supplied this field; not total loading time or sound duration.

Native playback replies can also add the capability and dialogue diagnostic fields described in getGameSoundInfo. The state table does not automatically include that function's speaker or verifiedInGame fields.

Examples

Read a sound's cached state when a result refers to its handle:

local sound
addEventHandler("onClientGameSoundResult", resourceRoot,
    function(requestId, ok, reason, dataJson)
        local data = fromJSON(dataJson)
        if sound and type(data) == "table" and data.id == sound then
            local state = getGameSoundState(sound)
            if state then outputDebugString("Game sound state: " .. state.state) end
        end
    end)
sound = playSoundFromGame("event:/SFX/UI/SFX_UI_Jingle_LevelUp", {volume = 0.5})
if not sound then outputDebugString("Game sound request rejected") 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.
• States are asynchronous observations. Do not assume every intermediate state will be reported or that a fixed sequence is guaranteed.
• finished, stopped and failed are terminal. Terminal handles cannot be controlled, and late updates do not revive them.
• The client retains up to 512 sound records across resources, evicting terminal history as new plays are accepted. Resource cleanup and world resets remove records immediately.
• State is accumulated metadata, so optional fields can describe earlier results. It is not a live property snapshot and has no volume, position or distance getter.