SgPositionalAudio

Plays 3D spatialized sound, with volume and panning based on listener distance and orientation. Used for immersive effects like footsteps, explosions, or ambient sounds. Can be attached to moving objects for realistic audio tracking in the scene.

Inherits from

SceneObject

Usage

To use this class, add the following require at the top of your script:

local SgPositionalAudio = require 'engine/sceneobjects/sgpositionalaudio'

Reference

create

static create(self, options, parent)

Create a new positional audio object in the scenegraph.

Parameters

self
options (table): A table of options to fill the parameters
parent (SceneObject): The parent scene object to add this to

Returns

Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgPositionalAudio.create({
    active = true,
    name = "",
    transform = Transform.new(),
    tags = {},
    sourceType = SgPositionalAudio.SourceType.Single,
    audioItem = nil,
    audioCollectionItem = nil,
    audioCollectionEntry = "",
    autoplay = false,
    loop = false,
    loopSection = false,
    loopStart = 0,
    loopEnd = 1,
    volume = 1,
    panning = 0,
    duration = 0,
    detune = 0,
    playbackRate = 1,
    offset = 0,
    refDistance = 1,
    maxDistance = 10000,
    rolloffFactor = 1,
    distanceModel = SgPositionalAudio.DistanceModel.Inverse,
    direction = SgPositionalAudio.Direction.Omnidirectional,
    coneInnerAngle = 90,
    coneOuterAngle = 180,
    coneOuterGain = 0.2
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

Property	Type	Default	Description
active	Boolean	true	Whether this 3D audio source is enabled and audible in the scene.
transform	Transform	Transform.new()	Position and orientation of the sound in 3D space.
tags	Tags	[]	Labels for filtering and lookup from scripts.
sourceType	Enum	Single	Whether this prefab plays a single Audio item or picks a random entry from an Audio Collection. \| Options: Single, Collection
autoplay	Boolean	false	Starts playback when the scene loads and this node is active.
loop	Boolean	false	Repeats playback when the clip ends.
volume	Float	1	Base gain before distance attenuation (0–1).
panning	Float	0	Stereo pan when not using full 3D panning (-1 left to 1 right).
duration	Float	0	Length of the audio clip in seconds.
detune	Float	0	Pitch offset in cents applied to playback.
playbackRate	Float	1	Playback speed multiplier.
offset	Float	0	Start time offset within the clip before playback begins.
refDistance	Float	1	Reference distance for inverse distance models where gain is 1.
maxDistance	Float	10000	Distance at which attenuation reaches minimum audibility.
rolloffFactor	Float	1	How quickly level drops after the reference distance.
distanceModel	Enum	Inverse	How volume attenuates with distance: linear, inverse, or exponential. \| Options: Linear, Inverse, Exponential
direction	Enum	Omnidirectional	Orientation vector for directional cones (used with PositionalAudio panning model). \| Options: Omnidirectional, Directional

play

play(force)

playback the audio

Parameters

force (boolean): Force the sound to replay even if it is already playing

stop

stop()

stop the audio

isPlaying

isPlaying()

Checks if the audio is playing

Returns

boolean: if sound is playing, false otherwise

getAudioCollectionEntry

getAudioCollectionEntry()

setAudioCollectionEntry

setAudioCollectionEntry(name)

Parameters

name

Enum: SourceType

Enumeration of audio source selection modes.

Field Name	Description

Enum: DistanceModel

Enumeration of distance attenuation models.

Field Name	Description

Enum: Direction

Enumeration of spatial audio direction modes.

Field Name	Description