SetGameSound3DMinMaxDistance

setGameSound3DMinMaxDistance

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 new per-instance attenuation distances for a sound created by playSound3DFromGame.

Syntax

number|false setGameSound3DMinMaxDistance(number handle, number minDistance, number maxDistance)

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.
minDistance	number	yes	Finite minimum distance in metres, at least 0 and strictly less than maxDistance.
maxDistance	number	yes	Finite maximum distance in metres, at least 0.01 and no greater than 200000; must exceed minDistance.

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

Change the distance overrides of a 3D campfire after one second. Replace the position 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.4})
if sound then
    setTimer(function()
        local requestId = setGameSound3DMinMaxDistance(sound, 1, 8)
        if not requestId then outputDebugString("Distance 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 sounds requested with playSound3DFromGame accept this control.
• These settings override instance distances within the game's authored event. They do not guarantee a linear fade or complete silence at a particular distance.
• The cached sound state does not expose the current distance values.