QCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release

2026-10-01T10:20:40Z

Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release

New page

= playSoundFromGame =
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">PLANNED FOR UPDATE 0.1.7</div>
<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>
</div>

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

== Syntax ==
<syntaxhighlight lang="lua">
number|false playSoundFromGame(string key [, table options])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>key</code> || <code>string</code> || yes || Exact, case-sensitive key from [[getGameSoundCatalog]]. Accepts catalog entries only; no filename, URL or arbitrary event name.
|-
| <code>options</code> || <code>table</code> || 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 <code>false</code> when rejected locally. The handle is also the play request ID in [[onClientGameSoundResult]]. Acceptance does not confirm playback or audibility; the initial state is <code>loading</code>.

== Examples ==
Play a game UI sound from a client resource and observe its initial result:
<syntaxhighlight lang="lua" line>
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
</syntaxhighlight>

== 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.
* 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 <code>listener-relative</code>. An authored 2D event reports <code>authored-2d</code>. 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 <code>oneShot = false</code> 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.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Audio Functions]]

PlaySoundFromGame - Revision history

QCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release