PlaySound3DFromGame

playSound3DFromGame

AVAILABLE SINCE UPDATE 0.1.7

This function is available since G1R:MP 0.1.7.

Requests a game sound at a fixed world position on the local client.

Syntax

number|false playSound3DFromGame(string key, number x, number y, number z [, table options])

Parameters

Name	Type	Required	Description
key	string	yes	Exact, case-sensitive key from getGameSoundCatalog. Accepts catalog entries only; no filename, URL or arbitrary event name.
x	number	yes	World X coordinate in metres; finite and between -200000 and 200000, inclusive.
y	number	yes	World Y coordinate in metres; finite and between -200000 and 200000, inclusive.
z	number	yes	World Z coordinate in metres; finite and between -200000 and 200000, inclusive.
options	table	no	Optional settings: volume = 1, minDistance = 1, maxDistance = 30. Only these keys are accepted. Volume must be finite and between 0 and 1. Distances are metres, must be finite, and require 0 <= minDistance < maxDistance <= 200000 with maxDistance >= 0.01.

Returns

Returns a positive integer sound handle when the request is accepted, or false when rejected locally. The handle is also the initial play request ID. onClientGameSoundResult reports native success or failure; a returned handle does not prove playback.

Examples

Place a campfire sound at a chosen world position and stop it after five seconds. Replace the coordinates with a location near the player:

local sound = playSound3DFromGame(
    "event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop",
    125.5, -48.0, 3.25,
    {volume = 0.5, minDistance = 1, maxDistance = 30}
)
if sound then
    setTimer(function() stopGameSound(sound) end, 5000, 1)
else
    outputDebugString("3D game sound request rejected")
end

Notes

• Available since update 0.1.7.
• Available only in client-side resource scripts. See Game audio for ownership, lifecycle, limits and server-triggered playback.
• Coordinates and distances use metres. Keep the usual game world axis order; no manual axis conversion is needed.
• A 3D request for an authored 2D event fails asynchronously with event-is-2d. Successful 3D playback reports mode world-3d.
• Playback stays at the requested world position until setGameSound3DPosition moves it. It is not automatically attached to a player or object.
• Distance settings are per-instance FMOD overrides. The event's authored attenuation and parameters still affect the result; no fixed falloff curve or silence boundary is guaranteed.
• The same catalog, language, ownership and lifecycle rules as playSoundFromGame apply.