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

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

New page

= setGameSound3DPosition =
<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 new world position for a sound created by [[playSound3DFromGame]].

== Syntax ==
<syntaxhighlight lang="lua">
number|false setGameSound3DPosition(number handle, number x, number y, number z)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>handle</code> || <code>number</code> || yes || Positive integer handle returned by [[playSoundFromGame]] or [[playSound3DFromGame]], owned by the current resource. Valid IDs do not exceed 9007199254740991.
|-
| <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.
|}

== Returns ==
Returns a positive integer request ID when the command is accepted for asynchronous processing, or <code>false</code> when rejected locally. The request ID identifies this command; it is not a new sound handle. Observe [[onClientGameSoundResult]] for the result.

== Examples ==
Move a 3D campfire source after one second. Replace both positions with locations 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.4})
if sound then
setTimer(function()
local requestId = setGameSound3DPosition(sound, 129.5, -48.0, 3.25)
if not requestId then outputDebugString("Position request rejected") end
end, 1000, 1)
setTimer(function() stopGameSound(sound) end, 4000, 1)
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.
* Controls require a nonterminal handle owned by the current resource. Unknown, expired, foreign-resource or terminal handles are rejected.
* A return value of <code>false</code> has no result event for that attempted command. Rejection can also mean the game is not ready or a request limit has been reached.
* Control acceptance does not change the cached playback state immediately. Native acknowledgements and observed state changes arrive asynchronously.
* Only handles created with [[playSound3DFromGame]] are accepted. A listener-relative sound created with [[playSoundFromGame]] is still a 2D request and cannot be moved through this function.
* Coordinates use metres and the game world axis order. The cached sound state does not include the current position.

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

SetGameSound3DPosition - Revision history

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