Audio

A 3D positional audio source attached to the active camera's AudioListener.

import {
  Behaviour,
  
} from "@relu-interactives/spatial-ecs";

export default class SpawnSound extends Behaviour {
  init() {
    const objects = this.world.getObjectManagementSystem();
    objects?.requestCreate("audio", {
      name: "Ambience",
      path: "/assets/audio/ambience.mp3",
      transform: { position: { x: 0, y: 1, z: 0 } },
      options: {
        autoplay: true,
        loop: true,
        volume: 0.5,
        positional: true,
        distanceModel: "linear",
        refDistance: 1,
        rolloffFactor: 1,
      },
    });
  }
}

Payload

Field	Type	Default	Description
name	string	"Audio"	Display name.
path	string	""	URL or local-asset path to the audio clip (MP3, WAV, OGG).
transform	TransformData	identity	Position / rotation / scale (position drives spatialization).
parentId	EntityId | null	null	Optional parent entity.

options

Option	Type	Default	Description
autoplay	boolean	false	Start playback as soon as the clip is loaded.
loop	boolean	false	Loop playback indefinitely.
volume	number (0–1)	1	Linear gain.
pitch	number	1	Playback rate multiplier (1 = normal speed/pitch).
positional	boolean	false	When true, audio is spatialized using the entity's transform.
refDistance	number	1	Distance at which volume is unattenuated (positional only).
distanceModel	"linear" | "inverse" | "exponential"	"inverse"	WebAudio distance model (positional only).
rolloffFactor	number	1	How quickly volume falls off past refDistance.

⚠️ Common mistake — wrong payload shape

path and options must be top-level keys on the payload. Never nest them inside an audio: sub-object.

// ✅ Correct
objects?.requestCreate("audio", {
  name: "SFX",
  path: "localasset://assets/sfx/hit.mp3",
  options: { autoplay: true, volume: 0.8 },
});

// ❌ Wrong — do NOT wrap inside audio:{}
objects?.requestCreate("audio", {
  name: "SFX",
  audio: { path: "...", options: { autoplay: true } }, // ← this will be ignored
});

Components attached

Transform, Object3DRef, Name, EntityType, ParentId, Selectable, Audio.