https://g1r-mp.com/wiki/index.php?action=history&feed=atom&title=GetGameSoundStateGetGameSoundState - Revision history2026-10-01T14:28:19ZRevision history for this page on the wikiMediaWiki 1.46.0https://g1r-mp.com/wiki/index.php?title=GetGameSoundState&diff=1180&oldid=prevQCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release2026-10-01T10:20:32Z<p>Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release</p>
<p><b>New page</b></p><div>= getGameSoundState =<br />
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;"><br />
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">PLANNED FOR UPDATE 0.1.7</div><br />
<div style="color:#111111; margin-top:0.25rem;">This function is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.</div><br />
</div><br />
<br />
Reads the latest cached state of a game sound owned by the current client resource.<br />
<br />
== Syntax ==<br />
<syntaxhighlight lang="lua"><br />
table|false getGameSoundState(number handle)<br />
</syntaxhighlight><br />
<br />
== Parameters ==<br />
{| class="wikitable"<br />
! Name !! Type !! Required !! Description<br />
|-<br />
| <code>handle</code> || <code>number</code> || yes || Positive integer handle returned by [[playSoundFromGame]] or [[playSound3DFromGame]], owned by the current resource. Valid IDs do not exceed 9007199254740991.<br />
|}<br />
<br />
== Returns ==<br />
Returns a Lua table, or <code>false</code> 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.<br />
<br />
The initial table contains <code>id</code> (number), <code>key</code> (string), <code>spatial</code> (bool), <code>state = "loading"</code> and <code>confirmed = false</code>. Later result fields are merged into this table; fields may be absent until supplied.<br />
<br />
{| class="wikitable"<br />
! Field !! Type !! Meaning<br />
|-<br />
| <code>state</code> || string || <code>loading</code>, <code>starting</code>, <code>playing</code>, <code>paused</code>, <code>finished</code>, <code>stopped</code> or <code>failed</code>.<br />
|-<br />
| <code>confirmed</code> || 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.<br />
|-<br />
| <code>mode</code> || string || When supplied: <code>world-3d</code>, <code>listener-relative</code> or <code>authored-2d</code>.<br />
|-<br />
| <code>reason</code> || string || When supplied: a failure reason or an empty string.<br />
|-<br />
| <code>operation</code>, <code>accepted</code> || string, bool || Most recent merged control acknowledgement. Operations are <code>volume</code>, <code>pause</code>, <code>position</code> or <code>distance</code>.<br />
|-<br />
| <code>nativeMs</code> || number || When supplied: native processing time in milliseconds for the result that last supplied this field; not total loading time or sound duration.<br />
|}<br />
<br />
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 <code>speaker</code> or <code>verifiedInGame</code> fields.<br />
<br />
== Examples ==<br />
Read a sound's cached state when a result refers to its handle:<br />
<syntaxhighlight lang="lua" line><br />
local sound<br />
addEventHandler("onClientGameSoundResult", resourceRoot,<br />
function(requestId, ok, reason, dataJson)<br />
local data = fromJSON(dataJson)<br />
if sound and type(data) == "table" and data.id == sound then<br />
local state = getGameSoundState(sound)<br />
if state then outputDebugString("Game sound state: " .. state.state) end<br />
end<br />
end)<br />
sound = playSoundFromGame("event:/SFX/UI/SFX_UI_Jingle_LevelUp", {volume = 0.5})<br />
if not sound then outputDebugString("Game sound request rejected") end<br />
</syntaxhighlight><br />
<br />
== Notes ==<br />
* Planned for update 0.1.7; not included in public 0.1.6.<br />
* Available only in client-side resource scripts. See [[Game audio]] for ownership, lifecycle, limits and server-triggered playback.<br />
* States are asynchronous observations. Do not assume every intermediate state will be reported or that a fixed sequence is guaranteed.<br />
* <code>finished</code>, <code>stopped</code> and <code>failed</code> are terminal. Terminal handles cannot be controlled, and late updates do not revive them.<br />
* 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.<br />
* 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.<br />
<br />
[[Category:Lua Functions]]<br />
[[Category:Client Functions]]<br />
[[Category:Audio Functions]]</div>QCherry