Sound.defs.ts

Sound — definitions.

Holds the SoundComponent class and the shapes its data and events travel in. No System lives here, which is the point: another component can name Sound in a query, or type an event it listens for, without pulling Sound's behaviour into its own bundle. Import from here, not from Sound.ts.

Sound.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { SoundSpec } from '@babylonjsmarket/ecs/renderer-types';
export { SoundEvents, SoundInputEvents } from './Sound.events';

/** WebAudio distance model — how volume falls off between min and max distance. */
export type SoundDistanceModel = 'linear' | 'inverse' | 'exponential';

export interface SoundInput {
  /** App-resolved URL of the clip. Empty = nothing to play (a placeholder slot). */
  src?: string;
  /** Loop the clip. Default false. */
  loop?: boolean;
  /**
   * Start as soon as the clip is loaded. Default true. Browsers hold audio
   * behind a user gesture, so an autoplay may sit silent until the first
   * click — the System retries then, nothing throws.
   */
  autoplay?: boolean;
  /** Gain. 1 = as recorded; the engine may allow more. Default 1. */
  volume?: number;
  /**
   * Positional: the sound has a place in the world — its own entity's mesh —
   * and pans and attenuates from it, so a cabinet's attract loop gets louder
   * as you walk up. Default false: a flat bed heard everywhere at once.
   */
  spatial?: boolean;
  /** Inside this distance the sound plays at full volume. Default 1. */
  minDistance?: number;
  /** Beyond this it attenuates no further (or, for `linear`, is silent). Default 100. */
  maxDistance?: number;
  /** How fast volume falls between the two. Default 1; a hall of cabinets wants ~3. */
  rolloff?: number;
  /** Falloff curve between min and max. Default 'inverse'. */
  distanceModel?: SoundDistanceModel;
  /**
   * Live control. Leave unset and `autoplay` decides; set true/false from a
   * panel or another system and the System plays/stops to match.
   */
  playing?: boolean;
}

export class SoundComponent extends Component {
  // Declared, not read off the class name: a minified build renames classes,
  // and the scene file still has to find this class by name.
  static componentType = 'Sound';

  src: string;
  loop: boolean;
  autoplay: boolean;
  volume: number;
  spatial: boolean;
  minDistance: number;
  maxDistance: number;
  rolloff: number;
  distanceModel: SoundDistanceModel;
  playing?: boolean;

  constructor(data: SoundInput = {}) {
    super();
    this.src = data.src ?? '';
    this.loop = data.loop ?? false;
    this.autoplay = data.autoplay ?? true;
    this.volume = data.volume ?? 1;
    this.spatial = data.spatial ?? false;
    this.minDistance = data.minDistance ?? 1;
    this.maxDistance = data.maxDistance ?? 100;
    this.rolloff = data.rolloff ?? 1;
    this.distanceModel = data.distanceModel ?? 'inverse';
    this.playing = data.playing;
  }

  /** The adapter's shape: the spatial block is present only for a positional sound. */
  toSpec(): SoundSpec {
    const spec: SoundSpec = {
      url: this.src,
      loop: this.loop,
      autoplay: this.autoplay,
      volume: this.volume,
    };
    if (this.spatial) {
      spec.spatial = {
        minDistance: this.minDistance,
        maxDistance: this.maxDistance,
        rolloff: this.rolloff,
        distanceModel: this.distanceModel,
      };
    }
    return spec;
  }

  serialize(): SoundInput {
    const out: SoundInput = {
      src: this.src,
      loop: this.loop,
      autoplay: this.autoplay,
      volume: this.volume,
      spatial: this.spatial,
      minDistance: this.minDistance,
      maxDistance: this.maxDistance,
      rolloff: this.rolloff,
      distanceModel: this.distanceModel,
    };
    if (this.playing !== undefined) out.playing = this.playing;
    return out;
  }
}

Sound.events.ts

Sound — event names.

The EventBus contract for Sound: what it emits and what it listens for. A listener imports these names from here, never from Sound.ts, so it can hear Sound without carrying Sound's System. bjs download hands this file out free with any component that imports it, and it does not make Sound a dependency to buy.

Sound.events.ts

// SoundEvents — from Sound
export const SoundEvents = {
  /** The clip loaded and has a live handle. `{ entityId, src }`. */
  READY: 'sound.ready',
  /**
   * The audio engine refused to start — no WebAudio, or the browser is holding
   * it behind a user gesture. Fired once per world; the system retries on the
   * first click/key and goes quiet in between. `{ }`.
   */
  BLOCKED: 'sound.blocked',
  /** The clip could not be fetched or decoded; it will not be retried. `{ entityId, src }`. */
  ERROR: 'sound.error',
} as const;

// SoundInputEvents — from Sound
export const SoundInputEvents = {
  /** Start (or restart from the top) an entity's sound. `{ entityId }`. */
  PLAY: 'sound.play',
  /** Stop an entity's sound. `{ entityId }`. */
  STOP: 'sound.stop',
  /** Set an entity's gain at runtime. `{ entityId, volume }`. */
  SET_VOLUME: 'sound.volume.set',
} as const;

Sound.ts

Sound.ts — renderer-agnostic System for audio clips, flat or positional.

One component = one clip. A flat one (spatial: false) is the hall's bed — crowd murmur, everywhere at once. A positional one rides its own entity's mesh, so a cabinet's attract loop is loud at the machine and gone three metres away.

Three things make this more than "call play":

Browsers refuse to start audio until the user has clicked or pressed a key. initAudio is awaited once per world before any clip is created; if it comes back false the System warns ONCE, becomes inert, and arms a one-shot retry on the first pointerdown / keydown, creating every clip that was waiting when the engine finally comes up. - Spatial falloff is judged from the audio LISTENER, which must ride the player's camera. The camera components announce their handle on their CREATED events; this System attaches the listener to whichever arrives. No camera event, no listener — sounds still play, judged from the origin. - A clip lands asynchronously, so a positional sound is pinned to its mesh once BOTH exist — the mesh handle comes from MeshPrimitive's CREATED / Mesh's LOADED, whichever the entity carries.

Sound.ts

import { SoundEvents, SoundInputEvents } from './Sound.events';
import { ArcCameraEvents } from '../ArcCamera/ArcCamera.events';
import { FirstPersonCameraEvents } from '../FirstPersonCamera/FirstPersonCamera.events';
import { MeshEvents } from '../Mesh/Mesh.events';
import { MeshPrimitiveEvents } from '../MeshPrimitive/MeshPrimitive.events';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import type { CameraHandle, MeshHandle, SoundHandle } from '@babylonjsmarket/ecs/renderer-types';
import { SoundComponent, type SoundDistanceModel, type SoundInput } from './Sound.defs';

export { SoundComponent, type SoundDistanceModel, type SoundInput };

interface SoundRuntime {
  handle?: SoundHandle;
  /** A createSound is in flight. */
  loading: boolean;
  /** The clip failed to load; never retried. */
  failed: boolean;
  /** The entity was destroyed while the clip was still loading. */
  orphaned: boolean;
  /** The entity is parked in a pool (silenced, clip kept). */
  parked: boolean;
  /** Pinned to its mesh already. */
  attached: boolean;
  lastVolume?: number;
  lastPlaying?: boolean;
}

/** Payload shape shared by the two camera CREATED events. */
interface CameraCreatedEvent {
  entityId: string;
  handle?: CameraHandle;
}
/** Payload shape shared by MeshPrimitive CREATED and Mesh LOADED. */
interface MeshHandleEvent {
  entityId: string;
  handle?: MeshHandle;
}

type AudioState = 'unknown' | 'pending' | 'ready' | 'blocked';

export class SoundSystem extends System {
  protected query = { required: [SoundComponent] };
  private runtime = new WeakMap<SoundComponent, SoundRuntime>();
  private audio: AudioState = 'unknown';
  /** The one warning this System ever prints about a silent world. */
  private warned = false;
  /** Mesh handles by entity id, for pinning positional clips. */
  private meshHandles = new Map<string, MeshHandle>();
  private gestureTarget: EventTarget | null = null;
  private gestureHandler: (() => void) | null = null;

  constructor(eventBus: EventBus) {
    super(eventBus);
  }

  private getRuntime(comp: SoundComponent): SoundRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { loading: false, failed: false, orphaned: false, parked: false, attached: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  protected onInitialize(): void {
    const onCamera = (e: CameraCreatedEvent) => {
      if (!e?.handle) return;
      // The adapter applies this once its engine is up, so it is safe to call
      // before initAudio has resolved.
      this.world?.renderer?.attachAudioListener(e.handle);
    };
    this.listen(FirstPersonCameraEvents.CREATED, onCamera);
    this.listen(ArcCameraEvents.CREATED, onCamera);

    const onMesh = (e: MeshHandleEvent) => {
      if (!e?.handle) return;
      this.meshHandles.set(e.entityId, e.handle);
      const entity = this.world?.getEntity(e.entityId);
      if (entity && this.entities.has(entity)) this.pin(entity);
    };
    this.listen(MeshPrimitiveEvents.CREATED, onMesh);
    this.listen(MeshEvents.LOADED, onMesh);

    this.listen(SoundInputEvents.PLAY, (e: { entityId: string }) => {
      const comp = this.componentFor(e?.entityId);
      if (!comp) return;
      comp.playing = true;
      const rt = this.getRuntime(comp);
      // A PLAY while already playing restarts from the top — the diff below
      // would see no change, so drive the adapter directly.
      if (rt.handle) {
        this.world?.renderer?.playSound(rt.handle);
        rt.lastPlaying = true;
      }
    });
    this.listen(SoundInputEvents.STOP, (e: { entityId: string }) => {
      const comp = this.componentFor(e?.entityId);
      if (!comp) return;
      comp.playing = false;
      const rt = this.getRuntime(comp);
      if (rt.handle) {
        this.world?.renderer?.stopSound(rt.handle);
        rt.lastPlaying = false;
      }
    });
    this.listen(SoundInputEvents.SET_VOLUME, (e: { entityId: string; volume: number }) => {
      const comp = this.componentFor(e?.entityId);
      if (comp && typeof e.volume === 'number') comp.volume = e.volume;
    });

    this.armGestureRetry();
    void this.ensureAudio();
  }

  protected onShutdown(): void {
    if (this.gestureTarget && this.gestureHandler) {
      this.gestureTarget.removeEventListener('pointerdown', this.gestureHandler);
      this.gestureTarget.removeEventListener('keydown', this.gestureHandler);
    }
    this.gestureTarget = null;
    this.gestureHandler = null;
  }

  protected onEntityAdded(entity: Entity): void {
    const comp = entity.get(SoundComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    rt.parked = false;
    if (rt.handle) {
      // Back from a pooled park: the clip survived, so just resume it.
      const wants = comp.playing ?? comp.autoplay;
      if (wants) this.world?.renderer?.playSound(rt.handle);
      rt.lastPlaying = wants;
      return;
    }
    this.ensureSound(entity); // a no-op while a load is still in flight
  }

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(SoundComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    const r = this.world?.renderer;
    if (!entity.active) {
      // Park-aware: a pooled entity keeps its clip for the next spawn, just
      // silenced. A clip still loading is silenced when it lands (see
      // ensureSound). A true destroy, below, releases it.
      rt.parked = true;
      if (rt.handle) {
        r?.stopSound(rt.handle);
        rt.lastPlaying = false;
      }
      return;
    }
    if (rt.handle) {
      r?.disposeSound(rt.handle);
      rt.handle = undefined;
      rt.attached = false;
    } else if (rt.loading) {
      // Destroyed mid-load: release the clip the moment it lands.
      rt.orphaned = true;
    }
    this.meshHandles.delete(entity.id);
  }

  protected onUpdate(_dt: number): void {
    const r = this.world?.renderer;
    if (!r) return;
    for (const entity of this.entities) {
      const comp = entity.get(SoundComponent);
      if (!comp) continue;
      const rt = this.getRuntime(comp);
      if (!rt.handle) continue;

      if (rt.lastVolume !== comp.volume) {
        r.setSoundVolume(rt.handle, comp.volume);
        rt.lastVolume = comp.volume;
      }
      if (comp.playing !== undefined && comp.playing !== rt.lastPlaying) {
        if (comp.playing) r.playSound(rt.handle);
        else r.stopSound(rt.handle);
        rt.lastPlaying = comp.playing;
      }
    }
  }

  /** The Sound component on a live entity of ours, by id. */
  private componentFor(entityId: string | undefined): SoundComponent | undefined {
    if (!entityId) return undefined;
    const entity = this.world?.getEntity(entityId);
    if (!entity || !this.entities.has(entity)) return undefined;
    return entity.get(SoundComponent);
  }

  /**
   * Bring the audio engine up, once. Resolves when the answer is known; the
   * waiting clips are created on success, and a single warning is printed on
   * the first refusal — never per entity, never per frame.
   */
  private async ensureAudio(): Promise<void> {
    if (this.audio === 'ready' || this.audio === 'pending') return;
    const r = this.world?.renderer;
    if (!r) return;
    this.audio = 'pending';
    const ok = await r.initAudio();
    if (ok) {
      this.audio = 'ready';
      for (const entity of this.entities) this.ensureSound(entity);
      return;
    }
    this.audio = 'blocked';
    if (!this.warned) {
      this.warned = true;
      console.warn(
        '[Sound] The audio engine is unavailable or blocked until a user gesture; ' +
          'the room stays silent and will retry on the first click or key.',
      );
      this.eventBus.emit(SoundEvents.BLOCKED, {});
    }
  }

  /** Retry a refused engine on the first click / key, then get out of the way. */
  private armGestureRetry(): void {
    const canvas = this.world?.renderer?.getRenderingCanvas();
    const target: EventTarget | null = canvas ?? (typeof window !== 'undefined' ? window : null);
    if (!target) return;
    this.gestureHandler = () => {
      if (this.audio === 'ready') return;
      if (this.audio === 'blocked') this.audio = 'unknown';
      void this.ensureAudio();
    };
    // pointerdown lands on the canvas; keydown goes to whatever has focus, and
    // a canvas usually doesn't, so a key on the page counts too.
    target.addEventListener('pointerdown', this.gestureHandler);
    target.addEventListener('keydown', this.gestureHandler);
    this.gestureTarget = target;
  }

  /** Load one entity's clip if the engine is up and nothing is in flight. */
  private ensureSound(entity: Entity): void {
    const comp = entity.get(SoundComponent);
    if (!comp || !comp.src) return;
    const rt = this.getRuntime(comp);
    if (rt.handle || rt.loading || rt.failed) return;
    if (this.audio !== 'ready') return; // created when ensureAudio succeeds
    const r = this.world?.renderer;
    if (!r) return;

    rt.loading = true;
    const src = comp.src;
    void r.createSound(entity.id, comp.toSpec()).then((handle) => {
      rt.loading = false;
      if (!handle) {
        rt.failed = true;
        this.eventBus.emit(SoundEvents.ERROR, { entityId: entity.id, src });
        return;
      }
      if (rt.orphaned) {
        r.disposeSound(handle);
        return;
      }
      rt.handle = handle;
      rt.lastVolume = comp.volume;
      // The spec's autoplay already decided the initial state; honour an
      // explicit `playing` that disagrees with it — or the park that happened
      // while the clip was still on its way (a pool pre-building its slots).
      const wants = rt.parked ? false : (comp.playing ?? comp.autoplay);
      if (wants !== comp.autoplay) {
        if (wants) r.playSound(handle);
        else r.stopSound(handle);
      }
      rt.lastPlaying = wants;
      this.pin(entity);
      this.eventBus.emit(SoundEvents.READY, { entityId: entity.id, src });
    });
  }

  /** Pin a positional clip to its entity's mesh once both handles exist. */
  private pin(entity: Entity): void {
    const comp = entity.get(SoundComponent);
    if (!comp || !comp.spatial) return;
    const rt = this.getRuntime(comp);
    if (!rt.handle || rt.attached) return;
    const mesh = this.meshHandles.get(entity.id);
    if (!mesh) return;
    this.world?.renderer?.attachSoundToMesh(rt.handle, mesh);
    rt.attached = true;
  }
}
export { SoundEvents, SoundInputEvents } from './Sound.events';

Sound.contract.test.ts

12 ✓

ArcadeECS contract: Sound

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Registers a listener for each declared input event

Last run 2026-10-08

Sound.contract.test.ts

import { SoundInputEvents } from './Sound.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { SoundComponent, SoundSystem } from './Sound';

runMechanicContract({
  name: 'Sound',
  componentClass: SoundComponent,
  systemClass: SoundSystem,
  sampleInput: { src: '/arcade/sounds/pacman.mp3', loop: true, spatial: true, rolloff: 3 },
  events: {
    input: [SoundInputEvents.PLAY, SoundInputEvents.STOP, SoundInputEvents.SET_VOLUME],
    // Outputs (READY / BLOCKED / ERROR) all follow an awaited adapter call, so
    // none lands inside the battery's synchronous update ticks; Sound.test.ts
    // covers them with real awaits.
  },
  makeInputPayload: () => ({ entityId: 'nobody', volume: 0.5 }),
});

Sound.test.ts

28 ✓

SoundComponent

defaults to an empty, autoplaying, flat one-shot
serialize round-trips through the constructor (playing only when set)
toSpec carries the spatial block only for a positional sound

SoundSystem

brings the audio engine up once, before any clip
creates the clip from the component and emits READY
an empty src is a placeholder: no clip is created
does not recreate the clip on later frames
records a failed load, emits ERROR, and never retries
listens on the rendering canvas when the renderer has one
removes its gesture listeners on shutdown
attaches the audio listener to whichever camera announces itself
pins a spatial clip to its mesh once both exist (mesh first)
pins a spatial clip once both exist (clip first), and only once
a flat (non-spatial) clip is never pinned
pushes a volume change made from outside
drives play / stop off the `playing` field
honours an explicit `playing` that disagrees with autoplay at load
PLAY / STOP / SET_VOLUME input events drive the matching entity
PLAY / STOP before the clip has landed only set the intent
disposes the clip when the entity is destroyed
releases a clip that lands after its entity was destroyed
is park-aware: a pooled entity keeps its clip, silenced, and resumes on re-acquire
creates clips for entities that already existed before initialize
stays inert when the world has no renderer

SoundSystem › when the audio engine is unavailable

warns exactly once, emits BLOCKED once, and creates nothing
retries on the first user gesture and creates the waiting clips
a second refusal on retry stays quiet (no second warning)
a gesture while a retry is still pending does not stack another

Last run 2026-10-08

Sound.test.ts

// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import type { CameraHandle, MeshHandle, SoundHandle } from '@babylonjsmarket/ecs/renderer-types';
import { SoundEvents, SoundInputEvents } from './Sound.events';
import { ArcCameraEvents } from '../ArcCamera/ArcCamera.events';
import { FirstPersonCameraEvents } from '../FirstPersonCamera/FirstPersonCamera.events';
import { MeshEvents } from '../Mesh/Mesh.events';
import { MeshPrimitiveEvents } from '../MeshPrimitive/MeshPrimitive.events';
import { SoundComponent, SoundSystem } from './Sound';

/** Let every queued microtask (initAudio, createSound) settle. */
const settle = async () => {
  for (let i = 0; i < 4; i++) await Promise.resolve();
};
const mesh = (id: string) => ({ __mockHandle: `mesh:${id}` }) as unknown as MeshHandle;
const camera = (id: string) => ({ __mockHandle: `camera:${id}` }) as unknown as CameraHandle;

describe('SoundComponent', () => {
  it('defaults to an empty, autoplaying, flat one-shot', () => {
    const c = new SoundComponent();
    expect(c.src).toBe('');
    expect(c.loop).toBe(false);
    expect(c.autoplay).toBe(true);
    expect(c.volume).toBe(1);
    expect(c.spatial).toBe(false);
    expect(c.minDistance).toBe(1);
    expect(c.maxDistance).toBe(100);
    expect(c.rolloff).toBe(1);
    expect(c.distanceModel).toBe('inverse');
    expect(c.playing).toBeUndefined();
  });

  it('serialize round-trips through the constructor (playing only when set)', () => {
    const c = new SoundComponent({
      src: '/arcade/sounds/galaga.mp3',
      loop: true,
      autoplay: false,
      volume: 1.8,
      spatial: true,
      minDistance: 1,
      maxDistance: 3,
      rolloff: 3,
      distanceModel: 'exponential',
    });
    expect(new SoundComponent(c.serialize()).serialize()).toEqual(c.serialize());
    expect('playing' in c.serialize()).toBe(false);
    const live = new SoundComponent({ playing: false });
    expect(live.serialize().playing).toBe(false);
    expect(new SoundComponent(live.serialize()).playing).toBe(false);
  });

  it('toSpec carries the spatial block only for a positional sound', () => {
    expect(new SoundComponent({ src: 'a.mp3' }).toSpec()).toEqual({
      url: 'a.mp3',
      loop: false,
      autoplay: true,
      volume: 1,
    });
    expect(new SoundComponent({ src: 'a.mp3', spatial: true, rolloff: 3, maxDistance: 3 }).toSpec().spatial).toEqual({
      minDistance: 1,
      maxDistance: 3,
      rolloff: 3,
      distanceModel: 'inverse',
    });
  });
});

describe('SoundSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let warn: ReturnType<typeof vi.spyOn>;

  beforeEach(() => {
    warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer, detectRaces: false });
  });
  afterEach(() => {
    // Shut the system down so its window listener never outlives the test.
    world.destroy();
    warn.mockRestore();
  });

  /** Make THIS renderer's engine answer `ok`, recording the call as the mock does. */
  const answerAudio = (ok: boolean) => {
    const r = renderer;
    r.initAudio = () => {
      r.calls.push({ method: 'initAudio', args: [] });
      return Promise.resolve(ok);
    };
  };

  const boot = async () => {
    world.addSystem(new SoundSystem(eventBus));
    world.initialize();
    await settle();
  };
  const calls = (m: string) => renderer.calls.filter((c) => c.method === m);
  const add = async (input = {}) => {
    const e = world.createEntity();
    e.add(new SoundComponent({ src: '/arcade/sounds/pacman.mp3', ...input }));
    await settle();
    return e;
  };

  it('brings the audio engine up once, before any clip', async () => {
    await boot();
    await add();
    await add();
    expect(calls('initAudio')).toHaveLength(1);
    expect(calls('createSound')).toHaveLength(2);
  });

  it('creates the clip from the component and emits READY', async () => {
    await boot();
    const ready = vi.fn();
    eventBus.on(SoundEvents.READY, ready);
    const e = await add({ loop: true, volume: 1.8, spatial: true, minDistance: 1, maxDistance: 3, rolloff: 3, distanceModel: 'exponential' });
    const [id, spec] = calls('createSound')[0].args;
    expect(id).toBe(e.id);
    expect(spec).toEqual({
      url: '/arcade/sounds/pacman.mp3',
      loop: true,
      autoplay: true,
      volume: 1.8,
      spatial: { minDistance: 1, maxDistance: 3, rolloff: 3, distanceModel: 'exponential' },
    });
    expect(ready).toHaveBeenCalledWith({ entityId: e.id, src: '/arcade/sounds/pacman.mp3' });
  });

  it('an empty src is a placeholder: no clip is created', async () => {
    await boot();
    await add({ src: '' });
    expect(calls('createSound')).toHaveLength(0);
  });

  it('does not recreate the clip on later frames', async () => {
    await boot();
    await add();
    world.update(1 / 60);
    world.update(1 / 60);
    expect(calls('createSound')).toHaveLength(1);
  });

  it('records a failed load, emits ERROR, and never retries', async () => {
    await boot();
    const r = renderer;
    r.createSound = (id, spec) => {
      r.calls.push({ method: 'createSound', args: [id, spec] });
      return Promise.resolve(null);
    };
    const error = vi.fn();
    eventBus.on(SoundEvents.ERROR, error);
    const e = await add();
    world.update(1 / 60);
    world.update(1 / 60);
    expect(calls('createSound')).toHaveLength(1);
    expect(error).toHaveBeenCalledWith({ entityId: e.id, src: '/arcade/sounds/pacman.mp3' });
    // Nothing to drive: no handle, so no volume/play calls either.
    expect(calls('setSoundVolume')).toHaveLength(0);
  });

  describe('when the audio engine is unavailable', () => {
    beforeEach(() => {
      answerAudio(false);
    });

    it('warns exactly once, emits BLOCKED once, and creates nothing', async () => {
      const blocked = vi.fn();
      eventBus.on(SoundEvents.BLOCKED, blocked);
      await boot();
      await add();
      await add();
      world.update(1 / 60);
      world.update(1 / 60);
      expect(warn).toHaveBeenCalledTimes(1);
      expect(blocked).toHaveBeenCalledTimes(1);
      expect(calls('createSound')).toHaveLength(0);
    });

    it('retries on the first user gesture and creates the waiting clips', async () => {
      await boot();
      const a = await add();
      const b = await add();
      expect(calls('createSound')).toHaveLength(0);
      // The gesture: the engine now says yes.
      answerAudio(true);
      window.dispatchEvent(new Event('pointerdown'));
      await settle();
      expect(calls('initAudio')).toHaveLength(2);
      expect(calls('createSound').map((c) => c.args[0])).toEqual([a.id, b.id]);
      // Once ready, further gestures do nothing.
      window.dispatchEvent(new Event('keydown'));
      await settle();
      expect(calls('initAudio')).toHaveLength(2);
      // Still only the one warning, however many refusals came before.
      expect(warn).toHaveBeenCalledTimes(1);
    });

    it('a second refusal on retry stays quiet (no second warning)', async () => {
      await boot();
      window.dispatchEvent(new Event('keydown'));
      await settle();
      expect(calls('initAudio')).toHaveLength(2);
      expect(warn).toHaveBeenCalledTimes(1);
    });

    it('a gesture while a retry is still pending does not stack another', async () => {
      await boot();
      let resolve!: (ok: boolean) => void;
      const r = renderer;
      r.initAudio = () => {
        r.calls.push({ method: 'initAudio', args: [] });
        return new Promise<boolean>((res) => {
          resolve = res;
        });
      };
      window.dispatchEvent(new Event('pointerdown'));
      window.dispatchEvent(new Event('pointerdown'));
      expect(calls('initAudio')).toHaveLength(2);
      resolve(true);
      await settle();
    });
  });

  it('listens on the rendering canvas when the renderer has one', async () => {
    const canvas = document.createElement('canvas');
    await renderer.init(canvas);
    answerAudio(false);
    await boot();
    answerAudio(true);
    // A page-level click is not the canvas.
    window.dispatchEvent(new Event('pointerdown'));
    await settle();
    expect(calls('initAudio')).toHaveLength(1);
    canvas.dispatchEvent(new Event('pointerdown'));
    await settle();
    expect(calls('initAudio')).toHaveLength(2);
  });

  it('removes its gesture listeners on shutdown', async () => {
    answerAudio(false);
    const system = new SoundSystem(eventBus);
    world.addSystem(system);
    world.initialize();
    await settle();
    world.removeSystem(system);
    window.dispatchEvent(new Event('pointerdown'));
    await settle();
    expect(calls('initAudio')).toHaveLength(1);
    // Shutting down twice is harmless.
    system.shutdown();
  });

  it('attaches the audio listener to whichever camera announces itself', async () => {
    await boot();
    eventBus.emit(FirstPersonCameraEvents.CREATED, { entityId: 'player', handle: camera('fp') });
    expect(calls('attachAudioListener')).toHaveLength(1);
    expect(calls('attachAudioListener')[0].args[0]).toEqual(camera('fp'));
    eventBus.emit(ArcCameraEvents.CREATED, { entityId: 'orbit', handle: camera('arc'), alpha: 0, beta: 0, radius: 1, target: [0, 0, 0] });
    expect(calls('attachAudioListener')).toHaveLength(2);
    // A camera event with no handle is ignored, not thrown on.
    eventBus.emit(ArcCameraEvents.CREATED, { entityId: 'legacy' });
    expect(calls('attachAudioListener')).toHaveLength(2);
  });

  it('pins a spatial clip to its mesh once both exist (mesh first)', async () => {
    await boot();
    const e = world.createEntity();
    eventBus.emit(MeshEvents.LOADED, { entityId: e.id, meshId: e.id, animationNames: [], handle: mesh(e.id) });
    e.add(new SoundComponent({ src: 'loop.mp3', spatial: true }));
    await settle();
    expect(calls('attachSoundToMesh')).toHaveLength(1);
    expect(calls('attachSoundToMesh')[0].args[1]).toEqual(mesh(e.id));
  });

  it('pins a spatial clip once both exist (clip first), and only once', async () => {
    await boot();
    const e = await add({ spatial: true });
    expect(calls('attachSoundToMesh')).toHaveLength(0);
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: e.id, primitive: 'box', handle: mesh(e.id) });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: e.id, primitive: 'box', handle: mesh(e.id) });
    expect(calls('attachSoundToMesh')).toHaveLength(1);
    // Announcements for strangers, or without a handle, are ignored.
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'stranger', primitive: 'box', handle: mesh('stranger') });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: e.id, primitive: 'box' });
    expect(calls('attachSoundToMesh')).toHaveLength(1);
  });

  it('a flat (non-spatial) clip is never pinned', async () => {
    await boot();
    const e = await add({ spatial: false });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: e.id, primitive: 'box', handle: mesh(e.id) });
    expect(calls('attachSoundToMesh')).toHaveLength(0);
  });

  it('pushes a volume change made from outside', async () => {
    await boot();
    const e = await add({ volume: 1 });
    world.update(1 / 60);
    expect(calls('setSoundVolume')).toHaveLength(0);
    e.get(SoundComponent)!.volume = 0.3;
    world.update(1 / 60);
    expect(calls('setSoundVolume')).toHaveLength(1);
    expect(calls('setSoundVolume')[0].args[1]).toBe(0.3);
  });

  it('drives play / stop off the `playing` field', async () => {
    await boot();
    const e = await add({ autoplay: true });
    const c = e.get(SoundComponent)!;
    c.playing = false;
    world.update(1 / 60);
    expect(calls('stopSound')).toHaveLength(1);
    c.playing = true;
    world.update(1 / 60);
    expect(calls('playSound')).toHaveLength(1);
    world.update(1 / 60);
    expect(calls('playSound')).toHaveLength(1);
  });

  it('honours an explicit `playing` that disagrees with autoplay at load', async () => {
    await boot();
    await add({ autoplay: true, playing: false });
    expect(calls('stopSound')).toHaveLength(1);
    await add({ autoplay: false, playing: true });
    expect(calls('playSound')).toHaveLength(1);
  });

  it('PLAY / STOP / SET_VOLUME input events drive the matching entity', async () => {
    await boot();
    const e = await add({ autoplay: true });
    eventBus.emit(SoundInputEvents.PLAY, { entityId: e.id });
    // Already playing: a PLAY still restarts from the top.
    expect(calls('playSound')).toHaveLength(1);
    eventBus.emit(SoundInputEvents.STOP, { entityId: e.id });
    expect(calls('stopSound')).toHaveLength(1);
    expect(e.get(SoundComponent)!.playing).toBe(false);
    eventBus.emit(SoundInputEvents.SET_VOLUME, { entityId: e.id, volume: 0.12 });
    world.update(1 / 60);
    expect(calls('setSoundVolume').at(-1)!.args[1]).toBe(0.12);
    // Bad payloads are ignored.
    eventBus.emit(SoundInputEvents.SET_VOLUME, { entityId: e.id, volume: 'loud' });
    eventBus.emit(SoundInputEvents.PLAY, { entityId: 'nobody' });
    eventBus.emit(SoundInputEvents.STOP, {});
    eventBus.emit(SoundInputEvents.SET_VOLUME, { entityId: 'nobody', volume: 1 });
    world.update(1 / 60);
    expect(calls('playSound')).toHaveLength(1);
    expect(calls('stopSound')).toHaveLength(1);
  });

  it('PLAY / STOP before the clip has landed only set the intent', async () => {
    answerAudio(false);
    await boot();
    const e = await add();
    eventBus.emit(SoundInputEvents.PLAY, { entityId: e.id });
    eventBus.emit(SoundInputEvents.STOP, { entityId: e.id });
    expect(calls('playSound')).toHaveLength(0);
    expect(calls('stopSound')).toHaveLength(0);
    expect(e.get(SoundComponent)!.playing).toBe(false);
  });

  it('disposes the clip when the entity is destroyed', async () => {
    await boot();
    const e = await add();
    world.removeEntity(e);
    expect(calls('disposeSound')).toHaveLength(1);
  });

  it('releases a clip that lands after its entity was destroyed', async () => {
    await boot();
    let resolve!: (h: SoundHandle | null) => void;
    const r = renderer;
    r.createSound = (id, spec) => {
      r.calls.push({ method: 'createSound', args: [id, spec] });
      return new Promise<SoundHandle | null>((res) => {
        resolve = res;
      });
    };
    const e = world.createEntity();
    e.add(new SoundComponent({ src: 'late.mp3' }));
    await settle();
    world.removeEntity(e);
    expect(calls('disposeSound')).toHaveLength(0);
    resolve({ __mockHandle: 'sound:late' } as unknown as SoundHandle);
    await settle();
    expect(calls('disposeSound')).toHaveLength(1);
  });

  it('is park-aware: a pooled entity keeps its clip, silenced, and resumes on re-acquire', async () => {
    await boot();
    world.registerPool('cab', {
      size: 1,
      build: (e) => e.add(new SoundComponent({ src: 'loop.mp3', loop: true })),
    });
    await settle();
    expect(calls('createSound')).toHaveLength(1);
    // Building the pool parks the slot before the clip has even landed: the
    // clip is silenced when it does, and kept — not disposed.
    expect(calls('stopSound')).toHaveLength(1);
    expect(calls('disposeSound')).toHaveLength(0);
    const e = world.acquire('cab')!;
    await settle();
    expect(calls('playSound')).toHaveLength(1);
    expect(calls('createSound')).toHaveLength(1);
    // Park again, then re-acquire with playing forced off: no play.
    world.removeEntity(e);
    expect(calls('stopSound')).toHaveLength(2);
    e.get(SoundComponent)!.playing = false;
    world.acquire('cab');
    expect(calls('playSound')).toHaveLength(1);
  });

  it('creates clips for entities that already existed before initialize', async () => {
    const e = world.createEntity();
    e.add(new SoundComponent({ src: 'bed.mp3' }));
    await boot();
    expect(calls('createSound')).toHaveLength(1);
    expect(calls('createSound')[0].args[0]).toBe(e.id);
  });

  it('stays inert when the world has no renderer', async () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus, detectRaces: false });
    w.addSystem(new SoundSystem(bus));
    w.initialize();
    await settle();
    const e = w.createEntity();
    expect(() => {
      e.add(new SoundComponent({ src: 'a.mp3' }));
      w.update(1 / 60);
      bus.emit(FirstPersonCameraEvents.CREATED, { entityId: 'p', handle: camera('fp') });
      window.dispatchEvent(new Event('pointerdown'));
      w.removeEntity(e);
    }).not.toThrow();
    await settle();
    w.destroy();
  });
});