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:37Z

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

New page

= playSound3DFromGame =
<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 a game sound at a fixed world position on the local client.

== Syntax ==
<syntaxhighlight lang="lua">
number|false playSound3DFromGame(string key, number x, number y, number z [, 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>x</code> || <code>number</code> || yes || World X coordinate in metres; finite and between -200000 and 200000, inclusive.
|-
| <code>y</code> || <code>number</code> || yes || World Y coordinate in metres; finite and between -200000 and 200000, inclusive.
|-
| <code>z</code> || <code>number</code> || yes || World Z coordinate in metres; finite and between -200000 and 200000, inclusive.
|-
| <code>options</code> || <code>table</code> || no || Optional settings: volume = 1, minDistance = 1, maxDistance = 30. Only these keys are accepted. Volume must be finite and between 0 and 1. Distances are metres, must be finite, and require 0 <= minDistance < maxDistance <= 200000 with maxDistance >= 0.01.
|}

== Returns ==
Returns a positive integer sound handle when the request is accepted, or <code>false</code> when rejected locally. The handle is also the initial play request ID. [[onClientGameSoundResult]] reports native success or failure; a returned handle does not prove playback.

== Examples ==
Place a campfire sound at a chosen world position and stop it after five seconds. Replace the coordinates with a location near the player:
<syntaxhighlight lang="lua" line>
local sound = playSound3DFromGame(
"event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop",
125.5, -48.0, 3.25,
{volume = 0.5, minDistance = 1, maxDistance = 30}
)
if sound then
setTimer(function() stopGameSound(sound) end, 5000, 1)
else
outputDebugString("3D 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.
* Coordinates and distances use metres. Keep the usual game world axis order; no manual axis conversion is needed.
* A 3D request for an authored 2D event fails asynchronously with <code>event-is-2d</code>. Successful 3D playback reports mode <code>world-3d</code>.
* Playback stays at the requested world position until [[setGameSound3DPosition]] moves it. It is not automatically attached to a player or object.
* Distance settings are per-instance FMOD overrides. The event's authored attenuation and parameters still affect the result; no fixed falloff curve or silence boundary is guaranteed.
* The same catalog, language, ownership and lifecycle rules as [[playSoundFromGame]] apply.

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

PlaySound3DFromGame - Revision history

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