SetGameSound3DPosition

setGameSound3DPosition

PLANNED FOR UPDATE 0.1.7

This function is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.

Requests a new world position for a sound created by playSound3DFromGame.

Syntax

number|false setGameSound3DPosition(number handle, number x, number y, number z)

Parameters

Name	Type	Required	Description
handle	number	yes	Positive integer handle returned by playSoundFromGame or playSound3DFromGame, owned by the current resource. Valid IDs do not exceed 9007199254740991.
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.

Returns

Returns a positive integer request ID when the command is accepted for asynchronous processing, or false when rejected locally. The request ID identifies this command; it is not a new sound handle. Observe onClientGameSoundResult for the result.

Examples

Move a 3D campfire source after one second. Replace both positions with locations near the player:

local sound = playSound3DFromGame("event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop", 125.5, -48.0, 3.25, {volume = 0.4})
if sound then
    setTimer(function()
        local requestId = setGameSound3DPosition(sound, 129.5, -48.0, 3.25)
        if not requestId then outputDebugString("Position request rejected") end
    end, 1000, 1)
    setTimer(function() stopGameSound(sound) end, 4000, 1)
end

Notes

• Planned for update 0.1.7; not included in public 0.1.6.
• Available only in client-side resource scripts. See Game audio for ownership, lifecycle, limits and server-triggered playback.
• Controls require a nonterminal handle owned by the current resource. Unknown, expired, foreign-resource or terminal handles are rejected.
• A return value of false has no result event for that attempted command. Rejection can also mean the game is not ready or a request limit has been reached.
• Control acceptance does not change the cached playback state immediately. Native acknowledgements and observed state changes arrive asynchronously.
• Only handles created with playSound3DFromGame are accepted. A listener-relative sound created with playSoundFromGame is still a 2D request and cannot be moved through this function.
• Coordinates use metres and the game world axis order. The cached sound state does not include the current position.