OnClientGameSoundResult

onClientGameSoundResult

PLANNED FOR UPDATE 0.1.7

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

Reports an asynchronous game audio command result or an observed playback/lifecycle change to the client resource that owns it.

Availability

This event is available in client scripts.

Callback signature

function(requestId, ok, reason, dataJson)

Parameters

Name	Type	Description
requestId	number	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.
ok	bool	Whether this command or notification succeeded. A successful play acknowledgement can still be followed by a playback failure.
reason	string	Empty on ordinary success; otherwise a diagnostic reason such as event-is-2d, native-loading-timeout, native-timeout, playback-not-observed or world-reset.
dataJson	string	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.

Examples

Decode result data, handle session cleanup, and read accumulated sound state:

local sound
addEventHandler("onClientGameSoundResult", resourceRoot,
    function(requestId, ok, reason, dataJson)
        if requestId == 0 and reason == "world-reset" then
            sound = nil
            outputDebugString("Game audio session reset")
            return
        end
        local data = fromJSON(dataJson)
        if type(data) ~= "table" then return end
        if not ok then outputDebugString("Game audio failed: " .. reason) end
        if sound and data.id == sound then
            local state = getGameSoundState(sound)
            if state then outputDebugString("Sound state: " .. state.state) end
        end
    end)
sound = playSoundFromGame("event:/SFX/UI/SFX_UI_Jingle_LevelUp", {volume = 0.5})
if not sound then outputDebugString("Request rejected before native processing") end

Notes

• Planned for update 0.1.7; not included in public 0.1.6.
• See Game audio for the complete lifecycle and examples. This event is delivered only to the owning client resource. Attach a handler to resourceRoot; no remote event registration is required.
• A function returning false did not accept that command and does not generate its own result event. Register handlers before submitting requests.
• An accepted play normally acknowledges state = "starting", confirmed = false, its id, key/capability metadata and mode. A play failure supplies state = "failed", confirmed = false and reason, with diagnostic metadata when available.
• Preload results contain capability metadata and may have dialogue diagnostics, but do not create a sound handle or contain a sound id. See getGameSoundInfo.
• Volume, pause, position and distance acknowledgements contain id, operation and accepted. A successful stop contains id, state = "stopped" and confirmed. Completed native processing normally also supplies nativeMs; early rejections, cancellations, timeouts and notifications may omit it.
• Unsolicited playback notifications use requestId = 0 and normally contain id, state, confirmed and reason. Optional fields can be absent. Decode the payload and use getGameSoundState when accumulated state is needed.
• A session reset uses requestId = 0, ok = false, reason = "world-reset" 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.
• Stopping a still-loading sound can acknowledge its original play with ok = true and state = "stopped". This does not mean playback occurred. Other queued controls for the same sound can fail with cancelled.
• Common asynchronous errors include event-is-2d, event-lookup-not-found, preload-cache-full, sample-load-failed, localized-recording-path-missing, localized-recording-missing, native-start-failed, native-control-failed, sound-not-owned-or-ended, active-sound-limit, owner-limit, native-queue-full, world-not-ready, listener-lost, native-instance-lost and playback-not-observed. Other detailed native diagnostics can also appear.
• native-loading-timeout is the native loading/retry deadline (12 seconds); native-timeout is the client's command acknowledgement timeout (15 seconds). The latter also cancels a timed-out play request.
• Neither ok, confirmed nor recordingPrepared proves audibility. Observed playback may still be silent due to authored event behavior or the game's audio settings.