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(),
    layers = {0},
    tags = {},
    autoplay = false,
    loop = false,
    volume = 1,
    panning = 0,
    playbackRate = 1,
    offset = 0,
    refDistance = 1,
    maxDistance = 10000,
    rolloffFactor = 1,
    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
transform	Transform	Transform.new()
tags	Tags	[]
sourceType	Enum	Single	Options: Single, Collection
autoplay	Boolean	false
loop	Boolean	false
volume	Float	1
panning	Float	0
duration	Float	0
detune	Float	0
playbackRate	Float	1
offset	Float	0
refDistance	Float	1
maxDistance	Float	10000
rolloffFactor	Float	1
distanceModel	Enum	Inverse	Options: Linear, Inverse, Exponential
direction	Enum	Omnidirectional	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