QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

2026-09-12T11:51:38Z

Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

← Older revision		Revision as of 11:51, 12 September 2026
Line 111:		Line 111:
	== Ownership and limits ==		== Ownership and limits ==

	* A resource can own at most 32 active sounds; the client runtime can own at most ~~128~~ in total.		* From update 0.1.3 BUILD81, a resource can own at most 128 active sounds; the client runtime can own at most 512 in total (previously 32/128). See [[Scripting limits]].
	* A handle can be controlled only by the resource that created it.		* A handle can be controlled only by the resource that created it.
	* Stopping a resource releases all sounds that it still owns.		* Stopping a resource releases all sounds that it still owns.

QCherry: Add client audio guide for update 0.1.2

2026-09-04T19:29:28Z

Add client audio guide for update 0.1.2

New page

{{DISPLAYTITLE:Client audio}}

<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;">AVAILABLE FROM UPDATE 0.1.2</div>
<div style="color:#111111; margin-top:0.25rem;">Resource-owned OGG Vorbis playback, including positional 3D sound, is available in G1R:MP 0.1.2 and later.</div>
</div>

'''Client audio''' lets a client-side Lua resource play non-spatial interface sounds and positional world sounds. Audio handles belong to the resource that created them and cannot be controlled by another resource.

== Supported files ==

The first release accepts Ogg containers containing '''Vorbis''' audio. Ogg Opus and other codecs are not accepted. Every sound must be declared as a join-time file in the same resource:

<syntaxhighlight lang="xml" line>
<?xml version="1.0" encoding="utf-8"?>
<scripts>
<script src="client.lua" type="client" cache="true" />
<file src="sounds/notification.ogg" download="join" />
<file src="sounds/forge.ogg" download="join" />
</scripts>
</syntaxhighlight>

The runtime accepts only the exact relative path declared by the current resource. URLs, absolute paths, traversal with <code>..</code>, reparse-point escapes, undeclared files, and files owned by another resource are rejected. File size and SHA-256 are checked again against the signed resource catalog before decoding.

== Audio functions ==

* [[playSound]] creates a non-spatial 2D sound.
* [[playSound3D]] creates a positional sound at world coordinates.
* [[stopSound]] stops a sound and invalidates its handle.
* [[setSoundVolume]] and [[getSoundVolume]] control linear volume.
* [[setSoundPaused]] and [[isSoundPaused]] control and inspect pause state.
* [[isSoundPlaying]] checks active playback.
* [[setSoundLooped]] changes looping.
* [[setSound3DPosition]] moves a positional source.
* [[setSound3DMinMaxDistance]] changes its attenuation range.

== Playback quality and output device ==

2D playback preserves the source channel layout, so stereo material remains stereo. A positional source is downmixed to mono because it represents one point in the world. When source and output sample rates differ, the runtime converts once with the bundled libsamplerate 0.2.2 sinc converter using <code>SRC_SINC_MEDIUM_QUALITY</code> and bypasses miniaudio's pitch-oriented linear converter. Matching sample rates are not resampled.

Resource audio and voice playback use the normal Windows default playback device. The Windows communications-device selection is used only for voice microphone capture; it does not redirect or reduce the quality of 2D or 3D playback.

For 3D sound, volume remains full through <code>minDistance</code>, then fades linearly and is silent at and beyond <code>maxDistance</code>. Coordinates and distances use metres. The listener follows the local native player while at least one positional sound exists.

== Local playback ==

<syntaxhighlight lang="lua" line>
local notification = playSound("sounds/notification.ogg", false, 0.65)

local forge = playSound3D(
"sounds/forge.ogg",
125.5, -48.0, 3.25,
true, 0.8,
2.0, 45.0
)

if forge then
setSound3DPosition(forge, 126.0, -48.0, 3.25)
setSound3DMinMaxDistance(forge, 2.0, 60.0)
end
</syntaxhighlight>

== Playing the same 3D sound for every player ==

Audio functions are client-side. To initiate a world sound authoritatively, the server sends a validated event to the client scripts. Using <code>root</code> as the target broadcasts the same reliable ordered event to every connected player.

Calculate the source position once on the server and send identical world coordinates to all clients. Do not recalculate the source from each receiving player's position.

'''server.lua'''

<syntaxhighlight lang="lua" line>
addCommandHandler("forgeaudio", function(playerId)
local position = getPlayerPosition(playerId)
if not position then
return
end

triggerClientEvent(
root,
"forgeAudio:play",
resourceRoot,
position.x + 4.0,
position.y,
position.z
)
end)
</syntaxhighlight>

'''client.lua'''

<syntaxhighlight lang="lua" line>
local forgeSound = false

addEvent("forgeAudio:play", true)
addEventHandler("forgeAudio:play", resourceRoot, function(x, y, z)
if forgeSound then
stopSound(forgeSound)
end

forgeSound = playSound3D(
"sounds/forge.ogg",
x, y, z,
true, 0.8,
1.0, 30.0
)
end)
</syntaxhighlight>

Each client creates its own local handle. Stopping, moving, pausing, or changing a shared sound therefore requires another server event broadcast to the same clients. Delivery is reliable and ordered, but playback start is not sample-accurate and can differ slightly due to network jitter.

== Ownership and limits ==

* A resource can own at most 32 active sounds; the client runtime can own at most 128 in total.
* A handle can be controlled only by the resource that created it.
* Stopping a resource releases all sounds that it still owns.
* A stopped or finished handle must not be reused.
* Validation and playback failures are recorded in the client runtime log.

[[Category:Lua API]]
[[Category:Lua Tutorials]]
[[Category:Audio Functions]]

Client audio - Revision history

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

QCherry: Add client audio guide for update 0.1.2