Latest revision as of 11:51, 12 September 2026

playSound

AVAILABLE FROM UPDATE 0.1.2

This function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.

Starts a non-spatial OGG Vorbis sound owned by the current client resource.

number|false playSound(string relativePath [, bool looped = false, number volume = 1])

Name	Type	Required	Description
`relativePath`	`string`	yes	The exact relative path of a same-resource `<file download="join">` entry ending in `.ogg`.
`looped`	`bool`	no	Whether playback should loop; defaults to false.
`volume`	`number`	no	Initial linear volume from 0 to 1; defaults to 1.

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

Play a client UI notification:

local sound = playSound("sounds/notification.ogg", false, 0.65)
if not sound then
    outputDebugString("Could not start notification audio", 2)
end

Available only in client-side resource scripts.
The first audio release supports Ogg Vorbis. An Ogg container using another codec, such as Opus, is not accepted.
The file must be declared for join-time download by the current resource. URLs, absolute paths, traversal, reparse-point escapes, undeclared files, and files owned by another resource are rejected.
The runtime revalidates the file size and SHA-256 from the signed resource catalog before decoding it.
Resource audio uses the normal Windows default playback endpoint. The communications-device selection is reserved for voice microphone capture and does not reroute 2D or 3D playback.
2D playback preserves the source channel layout. When source and output sample rates differ, the runtime converts once with the bundled libsamplerate 0.2.2 sinc converter using SRC_SINC_MEDIUM_QUALITY and bypasses miniaudio's pitch-oriented linear converter.
Each resource may own at most 128 active sounds; the client runtime may own at most 512 in total.
Expanded limits apply from update 0.1.3 BUILD81. See Scripting limits; earlier 0.1.3 binaries retain their old limits.

@@ Line 42: / Line 42: @@
 * Resource audio uses the normal Windows default playback endpoint. The communications-device selection is reserved for voice microphone capture and does not reroute 2D or 3D playback.
 * 2D playback preserves the source channel layout. 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.
-* Each resource may own at most 32 active sounds; the client runtime may own at most 128 in total.
+* Each resource may own at most 128 active sounds; the client runtime may own at most 512 in total.
+* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.
 [[Category:Lua Functions]]
 [[Category:Client Functions]]
 [[Category:Audio Functions]]