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

2026-09-12T11:51:50Z

Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

← Older revision		Revision as of 11:51, 12 September 2026
Line 54:		Line 54:
	* The native player transform is sampled for the listener only while at least one spatial sound exists; this path does not use Angelscript and does not install a ProcessEvent hook.		* The native player transform is sampled for the listener only while at least one spatial sound exists; this path does not use Angelscript and does not install a ProcessEvent hook.
	* The same declaration, path, integrity, codec, ownership, and active-sound limits as <code>playSound</code> apply.		* The same declaration, path, integrity, codec, ownership, and active-sound limits as <code>playSound</code> apply.
			* Expanded limits apply from update 0.1.3 BUILD81. Client limits: 128 owned sounds per resource and 512 globally. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

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

QCherry: Document client audio API for update 0.1.2

2026-09-04T19:28:59Z

Document client audio API for update 0.1.2

New page

= playSound3D =
<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;">This function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Starts a positional OGG Vorbis sound at a world position owned by the current client resource.

== Syntax ==
<syntaxhighlight lang="lua">
number|false playSound3D(string relativePath, number x, number y, number z [, bool looped = false, number volume = 1, number minDistance = 1, number maxDistance = 50])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>relativePath</code> || <code>string</code> || yes || The exact relative path of a same-resource <code><file download="join"></code> entry ending in <code>.ogg</code>.
|-
| <code>x</code> || <code>number</code> || yes || World X coordinate in metres.
|-
| <code>y</code> || <code>number</code> || yes || World Y coordinate in metres.
|-
| <code>z</code> || <code>number</code> || yes || World Z coordinate in metres.
|-
| <code>looped</code> || <code>bool</code> || no || Whether playback should loop; defaults to false.
|-
| <code>volume</code> || <code>number</code> || no || Initial linear volume from 0 to 1; defaults to 1.
|-
| <code>minDistance</code> || <code>number</code> || no || Distance in metres at or below which the sound retains full volume; defaults to 1.
|-
| <code>maxDistance</code> || <code>number</code> || no || Distance in metres at or beyond which the sound is silent; defaults to 50.
|}

== Returns ==
Returns a non-zero resource-owned sound handle, or <code>false</code> when validation, integrity verification, decoding, or playback setup fails.

== Examples ==
Play a looping forge sound in the world:
<syntaxhighlight lang="lua" line>
local forge = playSound3D(
"sounds/forge.ogg",
125.5, -48.0, 3.25,
true, 0.8, 2.0, 45.0
)
</syntaxhighlight>

== Notes ==
* Available only in client-side resource scripts.
* Coordinates and attenuation distances use metres. Coordinates must be finite and remain within +/-1,000,000 metres on every axis.
* The minimum distance must be at least 0.01 metres. The maximum must be greater than the minimum and no greater than 10,000 metres.
* Positional audio is downmixed to mono as a point source. It remains at full gain through <code>minDistance</code>, fades linearly, and is silent at and beyond <code>maxDistance</code>.
* Resource audio uses the normal Windows default playback endpoint. The communications-device selection is reserved for voice microphone capture and does not reroute 3D playback.
* The native player transform is sampled for the listener only while at least one spatial sound exists; this path does not use Angelscript and does not install a ProcessEvent hook.
* The same declaration, path, integrity, codec, ownership, and active-sound limits as <code>playSound</code> apply.

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

PlaySound3D - Revision history

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

QCherry: Document client audio API for update 0.1.2