@galfus/engine 0.0.0-stage → 0.31.1-alpha

package/src/animation/player.ts

@@ -0,0 +1,287 @@
+/**
+ * Multi-track Animation Player component and ECS evaluation system.
+ */
+
+import type { Component } from '../ecs/component';
+import type { System } from '../ecs/system';
+import type { EcsWorld } from '../ecs/world';
+import { common } from '../math/index';
+import type { Model3DComponent } from '../realm3d/components';
+import type { Realm3D } from '../realm3d/realm';
+import {
+  blendPoses,
+  clearAnimationPose,
+  copyAnimationPose,
+  createAnimationPose,
+  evaluateClip
+} from './blending';
+import type { AnimationClip } from './clip';
+
+export type AnimationLoopMode = 'once' | 'repeat' | 'ping-pong';
+
+export interface ActiveClipState {
+  clipName: string;
+  clip: AnimationClip;
+  time: number;
+  weight: number;
+  speed: number;
+  loopMode: AnimationLoopMode;
+  isPlaying: boolean;
+  isForward: boolean;
+}
+
+export interface AnimationPlayer3DComponent extends Component {
+  readonly type: 'AnimationPlayer3D';
+  clips: Map<string, AnimationClip>;
+  activeStates: Map<string, ActiveClipState>;
+  fadeTransition?: {
+    fromClip: string;
+    toClip: string;
+    duration: number;
+    elapsed: number;
+  };
+
+  /** Adds a clip to the player repository */
+  addClip(clip: AnimationClip): void;
+
+  /** Starts playing a clip with an initial weight and loop mode */
+  play(clipName: string, loopMode?: AnimationLoopMode, speed?: number): ActiveClipState | undefined;
+
+  /** Stops playback of a specific clip or all active clips */
+  stop(clipName?: string): void;
+
+  /** Initiates a smooth crossfade from the currently playing clip to target clip */
+  crossfade(
+    toClipName: string,
+    durationSecs: number,
+    loopMode?: AnimationLoopMode
+  ): ActiveClipState | undefined;
+}
+
+export function createAnimationPlayer3D(clips?: AnimationClip[]): AnimationPlayer3DComponent {
+  const clipMap = new Map<string, AnimationClip>();
+  if (clips) {
+    for (const clip of clips) {
+      clipMap.set(clip.name, clip);
+    }
+  }
+
+  const player: AnimationPlayer3DComponent = {
+    type: 'AnimationPlayer3D',
+    clips: clipMap,
+    activeStates: new Map(),
+
+    addClip(clip: AnimationClip) {
+      this.clips.set(clip.name, clip);
+    },
+
+    play(clipName: string, loopMode: AnimationLoopMode = 'repeat', speed = 1.0) {
+      const clip = this.clips.get(clipName);
+      if (!clip) return undefined;
+
+      const state: ActiveClipState = {
+        clipName,
+        clip,
+        time: 0,
+        weight: 1.0,
+        speed,
+        loopMode,
+        isPlaying: true,
+        isForward: true
+      };
+
+      this.activeStates.set(clipName, state);
+      return state;
+    },
+
+    stop(clipName?: string) {
+      if (clipName) {
+        this.activeStates.delete(clipName);
+      } else {
+        this.activeStates.clear();
+      }
+    },
+
+    crossfade(toClipName: string, durationSecs: number, loopMode: AnimationLoopMode = 'repeat') {
+      const targetClip = this.clips.get(toClipName);
+      if (!targetClip) return undefined;
+
+      // Find first playing clip to crossfade from
+      let fromClipName: string | undefined;
+      for (const [name, state] of this.activeStates) {
+        if (state.isPlaying && state.weight > 0 && name !== toClipName) {
+          fromClipName = name;
+          break;
+        }
+      }
+
+      const toState: ActiveClipState = {
+        clipName: toClipName,
+        clip: targetClip,
+        time: 0,
+        weight: fromClipName ? 0.0 : 1.0,
+        speed: 1.0,
+        loopMode,
+        isPlaying: true,
+        isForward: true
+      };
+      this.activeStates.set(toClipName, toState);
+
+      if (fromClipName && durationSecs > 0) {
+        this.fadeTransition = {
+          fromClip: fromClipName,
+          toClip: toClipName,
+          duration: durationSecs,
+          elapsed: 0
+        };
+      } else {
+        this.fadeTransition = undefined;
+        if (fromClipName) {
+          this.activeStates.delete(fromClipName);
+        }
+      }
+
+      return toState;
+    }
+  };
+
+  return player;
+}
+
+// Scratch poses for zero-allocation ECS updates
+const SCRATCH_COMBINED_POSE = createAnimationPose();
+const SCRATCH_CLIP_POSE = createAnimationPose();
+const SCRATCH_ACCUMULATOR_POSE = createAnimationPose();
+
+/**
+ * Creates the ECS System driving continuous animation playback and blending.
+ */
+export function createAnimationPlaybackSystem(realm3d?: Realm3D): System<EcsWorld> {
+  return (world: EcsWorld, context) => {
+    const playerEntities = world.query('AnimationPlayer3D');
+    if (playerEntities.length === 0) return;
+
+    const dt = context.dt;
+
+    for (const playerEntity of playerEntities) {
+      const player = world.getComponent<AnimationPlayer3DComponent>(
+        playerEntity,
+        'AnimationPlayer3D'
+      );
+      if (!player || player.activeStates.size === 0) continue;
+
+      // 1. Advance crossfade transition if active
+      if (player.fadeTransition) {
+        const trans = player.fadeTransition;
+        trans.elapsed += dt;
+        const progress = common.clamp(trans.elapsed / trans.duration, 0, 1);
+
+        const fromState = player.activeStates.get(trans.fromClip);
+        const toState = player.activeStates.get(trans.toClip);
+
+        if (fromState) fromState.weight = 1.0 - progress;
+        if (toState) toState.weight = progress;
+
+        if (progress >= 1.0) {
+          if (fromState) player.activeStates.delete(trans.fromClip);
+          player.fadeTransition = undefined;
+        }
+      }
+
+      // 2. Advance time for all active playing clips
+      for (const [_, state] of player.activeStates) {
+        if (!state.isPlaying || state.speed === 0) continue;
+
+        const dur = Math.max(0.0001, state.clip.duration);
+        const delta = dt * state.speed;
+
+        if (state.loopMode === 'repeat') {
+          state.time = (state.time + delta) % dur;
+          if (state.time < 0) state.time += dur;
+        } else if (state.loopMode === 'ping-pong') {
+          if (state.isForward) {
+            state.time += delta;
+            if (state.time >= dur) {
+              state.time = dur;
+              state.isForward = false;
+            }
+          } else {
+            state.time -= delta;
+            if (state.time <= 0) {
+              state.time = 0;
+              state.isForward = true;
+            }
+          }
+        } else {
+          // 'once'
+          state.time += delta;
+          if (state.time >= dur) {
+            state.time = dur;
+            state.isPlaying = false;
+          }
+        }
+      }
+
+      // 3. Evaluate and blend poses
+      clearAnimationPose(SCRATCH_COMBINED_POSE);
+      let isFirst = true;
+
+      for (const [_, state] of player.activeStates) {
+        if (state.weight <= 0) continue;
+
+        clearAnimationPose(SCRATCH_CLIP_POSE);
+        evaluateClip(state.clip, state.time, SCRATCH_CLIP_POSE);
+
+        if (isFirst) {
+          copyAnimationPose(SCRATCH_CLIP_POSE, SCRATCH_COMBINED_POSE);
+          isFirst = false;
+        } else {
+          copyAnimationPose(SCRATCH_COMBINED_POSE, SCRATCH_ACCUMULATOR_POSE);
+          blendPoses(
+            SCRATCH_COMBINED_POSE,
+            SCRATCH_ACCUMULATOR_POSE,
+            SCRATCH_CLIP_POSE,
+            state.weight
+          );
+        }
+      }
+
+      if (isFirst) continue; // No active clips with weight > 0
+
+      // 4. Apply combined pose to ECS entities
+      // Apply Translations
+      for (const [id, t] of SCRATCH_COMBINED_POSE.translations) {
+        const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+        if (model) {
+          model.setPosition(t[0], t[1], t[2]);
+        }
+      }
+
+      // Apply Rotations
+      for (const [id, r] of SCRATCH_COMBINED_POSE.rotations) {
+        const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+        if (model) {
+          model.setRotation(r[0], r[1], r[2], r[3]);
+        }
+      }
+
+      // Apply Scales
+      for (const [id, s] of SCRATCH_COMBINED_POSE.scales) {
+        const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+        if (model) {
+          model.setScale(s[0], s[1], s[2]);
+        }
+      }
+
+      // Apply Morph Weights
+      for (const [id, weights] of SCRATCH_COMBINED_POSE.weights) {
+        if (realm3d) {
+          const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+          if (model) {
+            realm3d.setModelMorphWeights(model.modelId, weights);
+          }
+        }
+      }
+    }
+  };
+}

package/src/audio/index.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath export for Audio subsystem.
+ */
+export * from './manager';

package/src/audio/manager.ts

@@ -0,0 +1,371 @@
+/**
+ * AudioManager manages audio sound loading, voices, and direct 3D spatial playback.
+ */
+
+import type {
+  GalfusEngine,
+  SpatialAudio,
+  SpatialAudioConfig,
+  SpatialTransform
+} from '@galfus/transport-types';
+import { IdAllocator, type SoundId, type VoiceId } from '../types';
+
+export interface PlaySoundOptions {
+  volume?: number;
+  panning?: number;
+  speed?: number;
+  looping?: boolean;
+}
+
+interface VoiceSpatialEntry {
+  spatial: SpatialAudio;
+  explicitListener: boolean;
+}
+
+function vec3Equals(
+  a: [number, number, number],
+  x: number,
+  y: number,
+  z: number,
+  eps = 1e-5
+): boolean {
+  return Math.abs(a[0] - x) < eps && Math.abs(a[1] - y) < eps && Math.abs(a[2] - z) < eps;
+}
+
+function quatEquals(
+  a?: [number, number, number, number],
+  x?: number,
+  y?: number,
+  z?: number,
+  w?: number,
+  eps = 1e-5
+): boolean {
+  if (!a) return false;
+  return (
+    Math.abs(a[0] - (x ?? 0)) < eps &&
+    Math.abs(a[1] - (y ?? 0)) < eps &&
+    Math.abs(a[2] - (z ?? 0)) < eps &&
+    Math.abs(a[3] - (w ?? 1)) < eps
+  );
+}
+
+export class AudioManager {
+  private _engine: GalfusEngine | null = null;
+  private readonly _idAllocator = new IdAllocator<SoundId>(1);
+  private readonly _sounds = new Set<SoundId>();
+  private readonly _activeVoices = new Set<VoiceId>();
+
+  // Global listener for voices without an explicit spatial listener
+  private readonly _listener: SpatialTransform = {
+    position: [0, 0, 0],
+    rotation: [0, 0, 0, 1]
+  };
+  private readonly _voiceSpatialCache = new Map<VoiceId, VoiceSpatialEntry>();
+  private readonly _voiceFinishListeners = new Map<VoiceId, Set<() => void>>();
+
+  bindEngine(engine: GalfusEngine): void {
+    this._engine = engine;
+  }
+
+  /**
+   * Loads raw audio bytes (WAV, MP3, OGG, FLAC) into core memory under a tracked SoundId.
+   */
+  loadSound(data: Uint8Array): SoundId {
+    const soundId = this._idAllocator.allocate('SoundId');
+    if (this._engine) {
+      this._engine.audioLoadSound(soundId, data, data.byteLength);
+    }
+    this._sounds.add(soundId);
+    return soundId;
+  }
+
+  /**
+   * Unloads a sound from core memory.
+   */
+  unloadSound(soundId: SoundId): void {
+    if (!this._sounds.has(soundId)) return;
+    if (this._engine) {
+      this._engine.audioUnloadSound(soundId);
+    }
+    this._sounds.delete(soundId);
+  }
+
+  /**
+   * Plays a loaded sound and returns its controllable VoiceId.
+   */
+  playSound(soundId: SoundId, options: PlaySoundOptions = {}): VoiceId {
+    if (!this._engine) {
+      throw new Error('Cannot play sound: AudioManager is not bound to an engine instance.');
+    }
+    const voiceId = this._engine.audioPlaySound(
+      soundId,
+      options.volume ?? 1.0,
+      options.panning ?? 0.0,
+      options.speed ?? 1.0,
+      options.looping ?? false
+    ) as VoiceId;
+    this._activeVoices.add(voiceId);
+    return voiceId;
+  }
+
+  /**
+   * Plays a 3D spatial sound and returns its controllable VoiceId.
+   * Can be called with a full SpatialAudio descriptor or directly with emitter position.
+   * Preserves explicit 1:1 acoustic listeners without overwriting them with the global listener.
+   */
+  playSoundSpatial(
+    soundId: SoundId,
+    spatialOrPosition: SpatialAudio | [number, number, number],
+    config?: SpatialAudioConfig
+  ): VoiceId {
+    if (!this._engine) {
+      throw new Error(
+        'Cannot play spatial sound: AudioManager is not bound to an engine instance.'
+      );
+    }
+
+    const hasExplicitListener = !Array.isArray(spatialOrPosition) && !!spatialOrPosition.listener;
+    const listenerToUse = hasExplicitListener
+      ? {
+          position: [...(spatialOrPosition as SpatialAudio).listener.position] as [
+            number,
+            number,
+            number
+          ],
+          rotation: (spatialOrPosition as SpatialAudio).listener.rotation
+            ? ([...(spatialOrPosition as SpatialAudio).listener.rotation!] as [
+                number,
+                number,
+                number,
+                number
+              ])
+            : undefined
+        }
+      : this._listener;
+
+    const spatial: SpatialAudio = Array.isArray(spatialOrPosition)
+      ? {
+          emitter: { position: spatialOrPosition },
+          listener: listenerToUse,
+          config: config ?? { volume: 1.0 }
+        }
+      : { ...spatialOrPosition, listener: listenerToUse };
+
+    const voiceId = this._engine.audioPlaySoundSpatial(soundId, spatial) as VoiceId;
+    this._activeVoices.add(voiceId);
+    this._voiceSpatialCache.set(voiceId, {
+      spatial: {
+        emitter: {
+          position: [...spatial.emitter.position],
+          rotation: spatial.emitter.rotation ? [...spatial.emitter.rotation] : undefined
+        },
+        listener: listenerToUse,
+        config: spatial.config
+      },
+      explicitListener: hasExplicitListener
+    });
+    return voiceId;
+  }
+
+  /**
+   * Updates listener world-space position directly without allocating JSON objects.
+   * Only propagates to voices bound to the global listener.
+   */
+  setListenerPosition(x: number, y: number, z: number): void {
+    if (vec3Equals(this._listener.position, x, y, z)) return;
+    this._listener.position = [x, y, z];
+    if (this._engine) {
+      for (const [voiceId, entry] of this._voiceSpatialCache) {
+        if (!entry.explicitListener) {
+          entry.spatial.listener = this._listener;
+          this._engine.audioUpdateSoundSpatial(voiceId, entry.spatial);
+        }
+      }
+    }
+  }
+
+  /**
+   * Updates listener orientation quaternion directly.
+   * Only propagates to voices bound to the global listener.
+   */
+  setListenerRotation(x: number, y: number, z: number, w: number): void {
+    if (quatEquals(this._listener.rotation, x, y, z, w)) return;
+    this._listener.rotation = [x, y, z, w];
+    if (this._engine) {
+      for (const [voiceId, entry] of this._voiceSpatialCache) {
+        if (!entry.explicitListener) {
+          entry.spatial.listener = this._listener;
+          this._engine.audioUpdateSoundSpatial(voiceId, entry.spatial);
+        }
+      }
+    }
+  }
+
+  /**
+   * Updates emitter position of an active 3D voice directly with coalescing dirty check.
+   */
+  setVoiceEmitterPosition(voiceId: VoiceId, x: number, y: number, z: number): void {
+    const entry = this._voiceSpatialCache.get(voiceId);
+    if (!entry) {
+      const spatial: SpatialAudio = {
+        emitter: { position: [x, y, z] },
+        listener: this._listener,
+        config: { volume: 1.0 }
+      };
+      this._voiceSpatialCache.set(voiceId, { spatial, explicitListener: false });
+      if (this._engine) {
+        this._engine.audioUpdateSoundSpatial(voiceId, spatial);
+      }
+      return;
+    }
+
+    if (vec3Equals(entry.spatial.emitter.position, x, y, z)) {
+      return; // Identical coordinates: zero ABI calls issued
+    }
+
+    entry.spatial.emitter.position = [x, y, z];
+    if (this._engine) {
+      this._engine.audioUpdateSoundSpatial(voiceId, entry.spatial);
+    }
+  }
+
+  /**
+   * Updates emitter rotation quaternion of an active 3D voice with coalescing dirty check.
+   */
+  setVoiceEmitterRotation(voiceId: VoiceId, x: number, y: number, z: number, w: number): void {
+    const entry = this._voiceSpatialCache.get(voiceId);
+    if (!entry) return;
+
+    if (quatEquals(entry.spatial.emitter.rotation, x, y, z, w)) {
+      return; // Identical orientation: zero ABI calls issued
+    }
+
+    entry.spatial.emitter.rotation = [x, y, z, w];
+    if (this._engine) {
+      this._engine.audioUpdateSoundSpatial(voiceId, entry.spatial);
+    }
+  }
+
+  /**
+   * Updates spatial positioning of an active sound voice.
+   */
+  updateSoundSpatial(voiceId: VoiceId, spatial: SpatialAudio): void {
+    this._voiceSpatialCache.set(voiceId, {
+      spatial,
+      explicitListener: !!spatial.listener
+    });
+    if (this._engine) {
+      this._engine.audioUpdateSoundSpatial(voiceId, spatial);
+    }
+  }
+
+  /**
+   * Registers a natural termination completion listener for a voice.
+   * Multiple independent listeners are supported with cumulative execution and isolated unsubscribes.
+   */
+  onVoiceFinished(voiceId: VoiceId, callback: () => void): () => void {
+    let set = this._voiceFinishListeners.get(voiceId);
+    if (!set) {
+      set = new Set();
+      this._voiceFinishListeners.set(voiceId, set);
+    }
+    set.add(callback);
+    return () => {
+      set?.delete(callback);
+      if (set && set.size === 0) {
+        this._voiceFinishListeners.delete(voiceId);
+      }
+    };
+  }
+
+  /**
+   * Handles voice completion (via engine callback or natural playback termination).
+   */
+  handleVoiceFinished(voiceId: VoiceId): void {
+    this._activeVoices.delete(voiceId);
+    this._voiceSpatialCache.delete(voiceId);
+    const listeners = this._voiceFinishListeners.get(voiceId);
+    if (listeners) {
+      for (const listener of [...listeners]) {
+        try {
+          listener();
+        } catch (err) {
+          console.error(`[AudioManager] Error in voice finish listener for voice ${voiceId}:`, err);
+        }
+      }
+      this._voiceFinishListeners.delete(voiceId);
+    }
+  }
+
+  /**
+   * Pauses an active sound voice.
+   */
+  pauseSound(voiceId: VoiceId): void {
+    if (this._engine) {
+      this._engine.audioPauseSound(voiceId);
+    }
+  }
+
+  /**
+   * Resumes a paused sound voice.
+   */
+  resumeSound(voiceId: VoiceId): void {
+    if (this._engine) {
+      this._engine.audioResumeSound(voiceId);
+    }
+  }
+
+  /**
+   * Stops an active sound voice, unregistering spatial caches and firing finish handlers.
+   */
+  stopSound(voiceId: VoiceId): void {
+    if (this._engine) {
+      this._engine.audioStopSound(voiceId);
+    }
+    this.handleVoiceFinished(voiceId);
+  }
+
+  /**
+   * Updates the volume of an active sound voice.
+   */
+  setVolume(voiceId: VoiceId, volume: number): void {
+    if (this._engine) {
+      this._engine.audioSetVolume(voiceId, volume);
+    }
+  }
+
+  /**
+   * Updates the panning of an active sound voice.
+   */
+  setPanning(voiceId: VoiceId, panning: number): void {
+    if (this._engine) {
+      this._engine.audioSetPanning(voiceId, panning);
+    }
+  }
+
+  /**
+   * Returns the count of active cached spatial voices.
+   */
+  getActiveSpatialVoiceCount(): number {
+    return this._voiceSpatialCache.size;
+  }
+
+  /**
+   * Unloads all active sounds and resets all voices and spatial caches.
+   */
+  dispose(): void {
+    if (this._engine) {
+      for (const voiceId of this._activeVoices) {
+        this._engine.audioStopSound(voiceId);
+      }
+      for (const soundId of this._sounds) {
+        this._engine.audioUnloadSound(soundId);
+      }
+    }
+    this._sounds.clear();
+    this._activeVoices.clear();
+    this._voiceSpatialCache.clear();
+    this._voiceFinishListeners.clear();
+    this._engine = null;
+  }
+}