https://g1r-mp.com/wiki/index.php?action=history&feed=atom&title=OnClientGameSoundResultOnClientGameSoundResult - Revision history2026-10-01T16:14:54ZRevision history for this page on the wikiMediaWiki 1.46.0https://g1r-mp.com/wiki/index.php?title=OnClientGameSoundResult&diff=1181&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:35Z<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>= onClientGameSoundResult =<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 event is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.</div><br />
</div><br />
<br />
Reports an asynchronous game audio command result or an observed playback/lifecycle change to the client resource that owns it.<br />
<br />
== Availability ==<br />
This event is available in '''client''' scripts.<br />
<br />
== Callback signature ==<br />
<syntaxhighlight lang="lua"><br />
function(requestId, ok, reason, dataJson)<br />
</syntaxhighlight><br />
<br />
== Parameters ==<br />
{| class="wikitable"<br />
! Name !! Type !! Description<br />
|-<br />
| <code>requestId</code> || <code>number</code> || Positive request ID returned by a game audio command, or 0 for an unsolicited playback/lifecycle notification. A play request's ID equals its sound handle; control request IDs do not.<br />
|-<br />
| <code>ok</code> || <code>bool</code> || Whether this command or notification succeeded. A successful play acknowledgement can still be followed by a playback failure.<br />
|-<br />
| <code>reason</code> || <code>string</code> || Empty on ordinary success; otherwise a diagnostic reason such as event-is-2d, native-loading-timeout, native-timeout, playback-not-observed or world-reset.<br />
|-<br />
| <code>dataJson</code> || <code>string</code> || JSON text, not a Lua table. Decode with fromJSON. Fields depend on the operation or notification; data.id is the affected sound handle when present.<br />
|}<br />
<br />
== Examples ==<br />
Decode result data, handle session cleanup, and read accumulated sound state:<br />
<syntaxhighlight lang="lua" line><br />
local sound<br />
addEventHandler("onClientGameSoundResult", resourceRoot,<br />
function(requestId, ok, reason, dataJson)<br />
if requestId == 0 and reason == "world-reset" then<br />
sound = nil<br />
outputDebugString("Game audio session reset")<br />
return<br />
end<br />
local data = fromJSON(dataJson)<br />
if type(data) ~= "table" then return end<br />
if not ok then outputDebugString("Game audio failed: " .. reason) end<br />
if sound and data.id == sound then<br />
local state = getGameSoundState(sound)<br />
if state then outputDebugString("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("Request rejected before native processing") end<br />
</syntaxhighlight><br />
<br />
== Notes ==<br />
* Planned for update 0.1.7; not included in public 0.1.6.<br />
* See [[Game audio]] for the complete lifecycle and examples. This event is delivered only to the owning client resource. Attach a handler to <code>resourceRoot</code>; no remote event registration is required.<br />
* A function returning <code>false</code> did not accept that command and does not generate its own result event. Register handlers before submitting requests.<br />
* An accepted play normally acknowledges <code>state = "starting"</code>, <code>confirmed = false</code>, its <code>id</code>, key/capability metadata and <code>mode</code>. A play failure supplies <code>state = "failed"</code>, <code>confirmed = false</code> and <code>reason</code>, with diagnostic metadata when available.<br />
* Preload results contain capability metadata and may have dialogue diagnostics, but do not create a sound handle or contain a sound <code>id</code>. See [[getGameSoundInfo]].<br />
* Volume, pause, position and distance acknowledgements contain <code>id</code>, <code>operation</code> and <code>accepted</code>. A successful stop contains <code>id</code>, <code>state = "stopped"</code> and <code>confirmed</code>. Completed native processing normally also supplies <code>nativeMs</code>; early rejections, cancellations, timeouts and notifications may omit it.<br />
* Unsolicited playback notifications use <code>requestId = 0</code> and normally contain <code>id</code>, <code>state</code>, <code>confirmed</code> and <code>reason</code>. Optional fields can be absent. Decode the payload and use [[getGameSoundState]] when accumulated state is needed.<br />
* A session reset uses <code>requestId = 0</code>, <code>ok = false</code>, <code>reason = "world-reset"</code> and an empty JSON object. All current-resource handles, pending requests and cached preload metadata are removed; do not expect a separate result for each cancelled request.<br />
* Stopping a still-loading sound can acknowledge its original play with <code>ok = true</code> and <code>state = "stopped"</code>. This does not mean playback occurred. Other queued controls for the same sound can fail with <code>cancelled</code>.<br />
* Common asynchronous errors include <code>event-is-2d</code>, <code>event-lookup-not-found</code>, <code>preload-cache-full</code>, <code>sample-load-failed</code>, <code>localized-recording-path-missing</code>, <code>localized-recording-missing</code>, <code>native-start-failed</code>, <code>native-control-failed</code>, <code>sound-not-owned-or-ended</code>, <code>active-sound-limit</code>, <code>owner-limit</code>, <code>native-queue-full</code>, <code>world-not-ready</code>, <code>listener-lost</code>, <code>native-instance-lost</code> and <code>playback-not-observed</code>. Other detailed native diagnostics can also appear.<br />
* <code>native-loading-timeout</code> is the native loading/retry deadline (12 seconds); <code>native-timeout</code> is the client's command acknowledgement timeout (15 seconds). The latter also cancels a timed-out play request.<br />
* Neither <code>ok</code>, <code>confirmed</code> nor <code>recordingPrepared</code> proves audibility. Observed playback may still be silent due to authored event behavior or the game's audio settings.<br />
<br />
[[Category:Lua Events]]<br />
[[Category:Client Events]]<br />
[[Category:Audio Events]]</div>QCherry