PlaySoundFromGame

playSoundFromGame

AVAILABLE SINCE UPDATE 0.1.7

This function is available since G1R:MP 0.1.7.

Requests local, listener-relative or authored-2D playback of a sound from the installed game's catalog.

Syntax

number|false playSoundFromGame(string key [, table options])

Parameters

Name	Type	Required	Description
key	string	yes	Exact, case-sensitive key from getGameSoundCatalog. Accepts catalog entries only; no filename, URL or arbitrary event name.
options	table	no	Optional settings: volume = 1, minDistance = 1, maxDistance = 30. Only these three keys are accepted. Volume must be finite and between 0 and 1. Distances must be finite, with 0 <= minDistance < maxDistance <= 200000 and maxDistance >= 0.01. An empty table uses the defaults.

Returns

Returns a positive integer sound handle when the request is accepted, or false when rejected locally. The handle is also the play request ID in onClientGameSoundResult. Acceptance does not confirm playback or audibility; the initial state is loading.

Examples

Play a game UI sound from a client resource and observe its initial result:

local sound
addEventHandler("onClientGameSoundResult", resourceRoot,
    function(requestId, ok, reason, dataJson)
        if requestId == sound then
            outputDebugString("Play result: " .. tostring(ok) .. " " .. reason)
        end
    end)
sound = playSoundFromGame("event:/SFX/UI/SFX_UI_Jingle_LevelUp", {volume = 0.6})
if not sound then
    outputDebugString("Game sound request rejected")
end

Notes

• Available since update 0.1.7.
• Available only in client-side resource scripts. See Game audio for ownership, lifecycle, limits and server-triggered playback.
• Keys are case-sensitive even though catalog search is case-insensitive.
• For an authored 3D event, playback follows the game camera with per-instance distance overrides and reports mode listener-relative. An authored 2D event reports authored-2d. Optional distance values are validated, but are not used to configure 2D playback.
• Looping, sustain behavior and attenuation details belong to the game event. There is no loop option, and oneShot = false does not guarantee a simple repeating loop.
• Dialogue uses the selected game voice language. Catalog membership does not guarantee that a recording exists in every game language or version.
• The current resource owns the handle. Cleanup occurs when the resource stops or the game session resets. Playback requests require a connected, ready game session.