@forgeax/engine-audio 0.0.0-dev.8d955ade1c79

package/src/audio-intent.ts

@@ -0,0 +1,92 @@
+import type { AudioClipAsset, AudioError } from '@forgeax/engine-types';
+import type {
+  AudioBackend,
+  AudioListenerPose,
+  AudioPlayOptions,
+  AudioState,
+  BusName,
+} from './audio-backend';
+
+export type AudioIntent =
+  | {
+      readonly kind: 'play';
+      readonly entityId: number;
+      readonly sourceKey: string;
+      readonly bytes?: Uint8Array;
+      readonly options: AudioPlayOptions;
+    }
+  | { readonly kind: 'stop'; readonly entityId: number }
+  | { readonly kind: 'set-volume'; readonly entityId: number; readonly volume: number }
+  | { readonly kind: 'set-bus-volume'; readonly bus: BusName; readonly volume: number }
+  | { readonly kind: 'set-bus-mute'; readonly bus: BusName; readonly muted: boolean }
+  | { readonly kind: 'set-listener-pose'; readonly pose: AudioListenerPose }
+  | { readonly kind: 'destroy' };
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false;
+  for (let index = 0; index < left.byteLength; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+export interface AudioIntentBackendOptions {
+  readonly emit: (intent: AudioIntent) => void;
+  readonly state?: () => AudioState;
+}
+
+const DISCONNECTED_AUDIO_STATE: AudioState = {
+  contextState: 'suspended',
+  activeSourceCount: 0,
+  lastError: null,
+};
+
+export function createAudioIntentBackend(options: AudioIntentBackendOptions): AudioBackend {
+  const publishedSources = new Map<string, Uint8Array>();
+  let destroyed = false;
+  const emit = (intent: AudioIntent): void => {
+    if (!destroyed || intent.kind === 'destroy') options.emit(intent);
+  };
+  const backend: AudioBackend = {
+    play(entityId: number, clip: AudioClipAsset, playOptions: AudioPlayOptions): void {
+      const publishedBytes = publishedSources.get(clip.sourceKey);
+      const publishBytes = publishedBytes === undefined || !sameBytes(publishedBytes, clip.bytes);
+      if (publishBytes) publishedSources.set(clip.sourceKey, clip.bytes.slice());
+      emit({
+        kind: 'play',
+        entityId,
+        sourceKey: clip.sourceKey,
+        ...(publishBytes ? { bytes: clip.bytes } : {}),
+        options: playOptions,
+      });
+    },
+    stop: (entityId) => emit({ kind: 'stop', entityId }),
+    setVolume: (entityId, volume) => emit({ kind: 'set-volume', entityId, volume }),
+    setBusVolume: (bus, volume) => {
+      const intent = { kind: 'set-bus-volume', bus, volume } as const;
+      emit(intent);
+    },
+    setBusMute: (bus, muted) => {
+      const intent = { kind: 'set-bus-mute', bus, muted } as const;
+      emit(intent);
+    },
+    setListenerPose: (pose) => {
+      const intent = { kind: 'set-listener-pose', pose } as const;
+      emit(intent);
+    },
+    getState: () => options.state?.() ?? DISCONNECTED_AUDIO_STATE,
+    getActiveSourceCount: () => (options.state?.() ?? DISCONNECTED_AUDIO_STATE).activeSourceCount,
+    destroy(): void {
+      if (destroyed) return;
+      const intent = { kind: 'destroy' } as const;
+      emit(intent);
+      destroyed = true;
+      publishedSources.clear();
+    },
+  };
+  return backend;
+}
+
+export function audioIntentErrorState(error: AudioError): AudioState {
+  return { contextState: 'suspended', activeSourceCount: 0, lastError: error };
+}

package/src/audio-tick-system.ts

@@ -0,0 +1,120 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+import type { AudioBackend, AudioPlayOptions, BusName } from './audio-backend';
+import { AudioSource } from './components';
+
+export function listenerPoseFromWorldMatrix(world: Float32Array) {
+  const forwardLength = Math.hypot(world[8] ?? 0, world[9] ?? 0, world[10] ?? 0) || 1;
+  const upLength = Math.hypot(world[4] ?? 0, world[5] ?? 0, world[6] ?? 0) || 1;
+  return {
+    positionX: world[12] ?? 0,
+    positionY: world[13] ?? 0,
+    positionZ: world[14] ?? 0,
+    forwardX: -(world[8] ?? 0) / forwardLength,
+    forwardY: -(world[9] ?? 0) / forwardLength,
+    forwardZ: -(world[10] ?? 0) / forwardLength,
+    upX: (world[4] ?? 0) / upLength,
+    upY: (world[5] ?? 0) / upLength,
+    upZ: (world[6] ?? 0) / upLength,
+  };
+}
+
+export type EdgeAction = 'none' | 'play-start' | 'play-stop';
+
+export function detectEdge(previous: boolean, current: boolean): EdgeAction {
+  if (!previous && current) return 'play-start';
+  if (previous && !current) return 'play-stop';
+  return 'none';
+}
+
+export function detectRemovedEntities(
+  previous: readonly number[],
+  current: readonly number[],
+): number[] {
+  const currentSet = new Set(current);
+  return previous.filter((entity) => !currentSet.has(entity));
+}
+
+interface TickState {
+  playing: Map<number, boolean>;
+  previousEntities: Set<number>;
+  volumes: Map<number, number>;
+}
+
+const states = new WeakMap<AudioBackend, TickState>();
+
+function stateFor(backend: AudioBackend): TickState {
+  const existing = states.get(backend);
+  if (existing !== undefined) return existing;
+  const created: TickState = {
+    playing: new Map(),
+    previousEntities: new Set(),
+    volumes: new Map(),
+  };
+  states.set(backend, created);
+  return created;
+}
+
+export function createClipResolver(
+  world: World,
+): (clipHandle: number) => AudioClipAsset | undefined {
+  return (clipHandle) => {
+    const resolved = world.sharedRefs.resolve<string, AudioClipAsset>(
+      clipHandle as unknown as Parameters<typeof world.sharedRefs.resolve>[0],
+    );
+    return resolved.ok && resolved.value.kind === 'audio' ? resolved.value : undefined;
+  };
+}
+
+export function audioTickSystem(world: World, backend: AudioBackend): void {
+  const state = stateFor(backend);
+  const resolveClip = createClipResolver(world);
+  const currentEntities: number[] = [];
+  const query = world.query({ read: [AudioSource] });
+  if (!query.ok) return;
+  for (const queryRow of query.value) {
+    const entity = queryRow.entity as number;
+    const source = queryRow.get(AudioSource);
+    const playing = source.playing === true;
+    const previous = state.playing.get(entity) ?? false;
+    const edge = detectEdge(previous, playing);
+    if (edge === 'play-start') {
+      const clip = resolveClip(source.clip as number);
+      if (clip === undefined) {
+        state.playing.set(entity, false);
+      } else {
+        const options: AudioPlayOptions = {
+          loop: source.loop === true,
+          volume: typeof source.volume === 'number' ? source.volume : 1,
+          spatialBlend: typeof source.spatialBlend === 'number' ? source.spatialBlend : 0,
+          bus: (typeof source.bus === 'string' ? source.bus : 'sfx') as BusName,
+        };
+        backend.play(entity, clip, options);
+        state.playing.set(entity, true);
+        state.volumes.set(entity, options.volume);
+      }
+    } else {
+      state.playing.set(entity, playing);
+      if (edge === 'play-stop') {
+        backend.stop(entity);
+      } else if (
+        playing &&
+        typeof source.volume === 'number' &&
+        state.volumes.get(entity) !== source.volume
+      ) {
+        backend.setVolume(entity, source.volume);
+        state.volumes.set(entity, source.volume);
+      }
+    }
+    currentEntities.push(entity);
+  }
+  for (const entity of detectRemovedEntities([...state.previousEntities], currentEntities)) {
+    if (state.playing.get(entity) === true) {
+      backend.stop(entity);
+    }
+    state.playing.delete(entity);
+    state.volumes.delete(entity);
+  }
+  state.previousEntities.clear();
+  for (const entity of currentEntities) state.previousEntities.add(entity);
+}

package/src/components.ts

@@ -0,0 +1,23 @@
+// @forgeax/engine-audio -- AudioSource + AudioListener ECS components (feat-20260527-audio-system M1 / w9)
+//
+// Decision anchors:
+// - requirements S-3 (AudioSource single-component surface, 6 fields)
+// - requirements S-4 (AudioListener independent marker component)
+// - plan-strategy D-4 (edge-detection tick system; AudioSource.playing drives play/stop edges)
+// - plan-strategy D-5 (AudioSource.bus defaults to 'sfx'; BusName is 'sfx' | 'music')
+// - plan-strategy section 3.1 (6-field AudioSource + marker AudioListener)
+// - charter P1 (progressive disclosure: 3-symbol core surface)
+// - charter P4 (consistent abstraction: same defineComponent pattern as Transform/Camera)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+export const AudioSource = defineComponent('AudioSource', {
+  clip: { type: 'shared<AudioClipAsset>' },
+  playing: { type: 'bool', default: false },
+  loop: { type: 'bool', default: false },
+  volume: { type: 'f32', default: 1.0 },
+  spatialBlend: { type: 'f32', default: 0 },
+  bus: { type: 'string', default: 'sfx' },
+});
+
+export const AudioListener = defineComponent('AudioListener', {});

package/src/index.ts

@@ -0,0 +1,44 @@
+// @forgeax/engine-audio -- public barrel (feat-20260527-audio-system M1 / w10)
+//
+// Single-entry surface: AI users import `@forgeax/engine-audio` and discover
+// the full audio subsystem surface in one go (charter P1 progressive disclosure).
+//
+// Re-exports from @forgeax/engine-types (error model SSOT):
+//   AudioError, AudioErrorCode, AudioErrorDetail, AUDIO_ERROR_HINTS
+//
+// Package-internal exports:
+//   AudioBackend interface, BusName, AudioPlayOptions, AudioState,
+//   AUDIO_ENGINE_RESOURCE_KEY
+//   AudioSource component, AudioListener component
+
+export {
+  AUDIO_ERROR_HINTS,
+  type AudioClipAsset,
+  AudioError,
+  type AudioErrorCode,
+  type AudioErrorDetail,
+} from '@forgeax/engine-types';
+export { audioContribution } from './assets/audio-decoder';
+export type { AudioListenerPose, AudioPlayOptions, AudioState } from './audio-backend';
+export {
+  AUDIO_ENGINE_RESOURCE_KEY,
+  type AudioBackend,
+  type BusName,
+} from './audio-backend';
+export {
+  type AudioIntent,
+  type AudioIntentBackendOptions,
+  audioIntentErrorState,
+  createAudioIntentBackend,
+} from './audio-intent';
+export {
+  audioTickSystem,
+  createClipResolver,
+  detectEdge,
+  detectRemovedEntities,
+  type EdgeAction,
+  listenerPoseFromWorldMatrix,
+} from './audio-tick-system';
+export { AudioListener, AudioSource } from './components';
+export { AUDIO_TICK_SYSTEM_NAME, audioPlugin } from './plugin-factory';
+export { audioBackendPlugin } from './plugin-service';

package/src/plugin-factory.ts

@@ -0,0 +1,66 @@
+import { type Component, Update, type World } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import { PROPAGATE_TRANSFORMS_SYSTEM, Transform } from '@forgeax/engine-scene';
+import { AUDIO_ENGINE_RESOURCE_KEY } from './audio-backend';
+import { audioTickSystem, listenerPoseFromWorldMatrix } from './audio-tick-system';
+import { AudioListener, AudioSource } from './components';
+
+export const AUDIO_TICK_SYSTEM_NAME = 'audio-tick' as const;
+
+const AUDIO_COMPONENTS: readonly Component[] = [AudioSource, AudioListener];
+
+function registerAudioComponents(world: World): () => void {
+  const leases = AUDIO_COMPONENTS.map((component) => world.components.register(component).unwrap());
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+
+export function audioPlugin(): Plugin {
+  return {
+    name: 'audio',
+    inject: ['world', 'audio'],
+    apply(ctx) {
+      const world = ctx.world;
+      const backend = ctx.audio;
+      if (backend === undefined) throw new Error('Cordis activated audio without its provider');
+      ctx.effect(() => registerAudioComponents(world), 'audio/components');
+      ctx.effect(() => {
+        world.insertResource(AUDIO_ENGINE_RESOURCE_KEY, backend);
+        return () => {
+          world.removeResource(AUDIO_ENGINE_RESOURCE_KEY);
+        };
+      }, 'audio/resource');
+      ctx.effect(() => {
+        world
+          .addSystem(Update, {
+            name: AUDIO_TICK_SYSTEM_NAME,
+            queries: [],
+            fn: () => audioTickSystem(world, backend),
+          })
+          .unwrap();
+        return () => world.removeSystem(Update, AUDIO_TICK_SYSTEM_NAME);
+      }, 'audio/tick');
+      ctx.effect(() => {
+        world
+          .addSystem(Update, {
+            name: 'audio-listener-sync',
+            after: [PROPAGATE_TRANSFORMS_SYSTEM],
+            queries: [],
+            fn: () => {
+              const listeners = world.query({ read: [Transform], with: [AudioListener] });
+              if (!listeners.ok) return;
+              for (const row of listeners.value) {
+                const transform = row.get(Transform);
+                const pose = listenerPoseFromWorldMatrix(transform.world);
+                backend.setListenerPose(pose);
+                break;
+              }
+            },
+          })
+          .unwrap();
+        return () => world.removeSystem(Update, 'audio-listener-sync');
+      }, 'audio/listener-sync');
+    },
+  };
+}

package/src/plugin-service.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+
+import type { AudioBackend } from './audio-backend';
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    audio?: AudioBackend;
+  }
+}
+
+export function audioBackendPlugin(backend: AudioBackend): Plugin {
+  return {
+    name: 'audio-backend',
+    provide: 'audio',
+    apply(ctx) {
+      ctx.provide('audio', backend);
+    },
+  };
+}