PlaySound3D

playSound3D

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 positional OGG Vorbis sound at a world position owned by the current client resource.

Syntax

number|false playSound3D(string relativePath, number x, number y, number z [, bool looped = false, number volume = 1, number minDistance = 1, number maxDistance = 50])

Parameters

Name	Type	Required	Description
relativePath	string	yes	The exact relative path of a same-resource <file download="join"> entry ending in .ogg.
x	number	yes	World X coordinate in metres.
y	number	yes	World Y coordinate in metres.
z	number	yes	World Z coordinate in metres.
looped	bool	no	Whether playback should loop; defaults to false.
volume	number	no	Initial linear volume from 0 to 1; defaults to 1.
minDistance	number	no	Distance in metres at or below which the sound retains full volume; defaults to 1.
maxDistance	number	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 false when validation, integrity verification, decoding, or playback setup fails.

Examples

Play a looping forge sound in the world:

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

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 minDistance, fades linearly, and is silent at and beyond maxDistance.
• 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 playSound 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.