@downdraft/engine 0.0.0 → 0.1.0

package/core/src/audio/interface.ts

@@ -0,0 +1,130 @@
+export type AudioFormat = "wav" | "ogg" | "mp3" | "flac";
+
+export type AudioChannel = "master" | "sfx" | "music" | "voice" | "ambient" | "ui";
+
+export interface AudioBufferFormat {
+  sampleRate: number;
+  channels: number;
+  sampleFormat: string;
+}
+
+export interface AudioBufferDesc {
+  id: string;
+  format: AudioBufferFormat | AudioFormat;
+  sampleRate?: number;
+  channels?: number;
+  samples: Float32Array;
+  duration?: number;
+}
+
+export interface AudioSourceHandle {
+  id?: number;
+  sourceId?: number;
+  bufferId: string | number;
+  playing?: boolean;
+  paused?: boolean;
+  loop?: boolean;
+  volume?: number;
+  pitch?: number;
+  pan?: number;
+  spatial?: boolean;
+  position?: [number, number, number];
+  velocity?: [number, number, number];
+  minDistance?: number;
+  maxDistance?: number;
+  rolloffFactor?: number;
+  channel?: AudioChannel;
+}
+
+export interface AudioListenerState {
+  position: [number, number, number];
+  orientation: [number, number, number] | [number, number, number, number];
+  up?: [number, number, number];
+  velocity?: [number, number, number];
+  gain?: number;
+}
+
+export type AudioEffectType = "reverb" | "lowpass" | "highpass" | "echo" | "distortion" | "chorus";
+
+export interface AudioEffectDesc {
+  type: AudioEffectType;
+  params: Record<string, number>;
+  wet?: number;
+  dry?: number;
+}
+
+export interface AudioChannelConfig {
+  name: AudioChannel;
+  volume: number;
+  muted: boolean;
+  effects: AudioEffectDesc[];
+}
+
+export interface AudioBackendConfig {
+  sampleRate: number;
+  bufferSize: number;
+  channels: number;
+  spatialEnabled: boolean;
+  maxSources: number;
+  speedOfSound: number;
+}
+
+export const DEFAULT_AUDIO_CONFIG: AudioBackendConfig = {
+  sampleRate: 44100,
+  bufferSize: 1024,
+  channels: 2,
+  spatialEnabled: true,
+  maxSources: 64,
+  speedOfSound: 343.3,
+};
+
+export interface AudioBackend {
+  readonly name: string;
+  readonly version: string;
+
+  init(config: AudioBackendConfig): Promise<void>;
+  isInitialized(): boolean;
+
+  loadBuffer(desc: AudioBufferDesc): void;
+  unloadBuffer(bufferId: string | number): void;
+  getBuffer?(bufferId: string | number): AudioBufferDesc | undefined;
+
+  play(bufferId: string | number, opts?: Partial<AudioSourceHandle>): AudioSourceHandle;
+  stop(sourceId: number | AudioSourceHandle): void;
+  pause(sourceId?: number | AudioSourceHandle): void;
+  resume(sourceId?: number | AudioSourceHandle): void;
+  seek?(sourceId: number, positionSec: number): void;
+
+  setSourceVolume?(sourceId: number, volume: number): void;
+  setSourcePitch?(sourceId: number, pitch: number): void;
+  setSourcePan?(sourceId: number, pan: number): void;
+  setSourceLoop?(sourceId: number, loop: boolean): void;
+  setSourcePosition?(sourceId: number, pos: [number, number, number]): void;
+  setSourceVelocity?(sourceId: number, vel: [number, number, number]): void;
+  setSourceSpatial?(sourceId: number, spatial: boolean): void;
+  setSourceDistanceModel?(sourceId: number, minDist: number, maxDist: number, rolloff: number): void;
+  setSourceChannel?(sourceId: number, channel: AudioChannel): void;
+
+  getSourceState?(sourceId: number): AudioSourceHandle | null;
+  getActiveSources?(): AudioSourceHandle[];
+
+  setListener(listener: AudioListenerState): void;
+  getListener?(): AudioListenerState;
+
+  setChannelVolume(channel: AudioChannel, volume: number): void;
+  setChannelMuted?(channel: AudioChannel, muted: boolean): void;
+  getChannelVolume(channel: AudioChannel): number;
+  isChannelMuted(channel: AudioChannel): boolean;
+
+  addEffect(channel: AudioChannel, effect: AudioEffectDesc): number;
+  removeEffect(channel: AudioChannel, effectId: number): void;
+  updateEffect?(channel: AudioChannel, effectId: number, params: Record<string, number>): void;
+
+  update(dt?: number): void;
+  syncPositions?(positionBuffer: Float32Array, sourceCount: number): void;
+
+  setMasterVolume?(v: number): void;
+  getMasterVolume?(): number;
+
+  destroy(): void;
+}

package/core/src/audio/listener.ts

@@ -0,0 +1,32 @@
+import { Component } from "../ecs/component";
+import type { AudioListenerState } from "./interface";
+
+export interface AudioListenerData {
+  [key: string]: unknown;
+  position: [number, number, number];
+  orientation: [number, number, number, number];
+  velocity: [number, number, number];
+  gain: number;
+  active: boolean;
+}
+
+export const AudioListener = Component.register<AudioListenerData>("AudioListener", {
+  position: [0, 0, 0],
+  orientation: [0, 0, 0, 1],
+  velocity: [0, 0, 0],
+  gain: 1.0,
+  active: true,
+});
+
+export function createAudioListener(opts?: Partial<AudioListenerData>): AudioListenerData {
+  return AudioListener.create(opts);
+}
+
+export function listenerToState(data: AudioListenerData): AudioListenerState {
+  return {
+    position: data.position,
+    orientation: data.orientation,
+    velocity: data.velocity,
+    gain: data.gain,
+  }
+}

package/core/src/audio/mixer.ts

@@ -0,0 +1,141 @@
+import type { AudioBackend, AudioChannel, AudioEffectDesc, AudioEffectType } from "./interface";
+
+export interface MixerChannelState {
+  name: AudioChannel;
+  volume: number;
+  muted: boolean;
+  effects: Map<number, AudioEffectDesc>;
+}
+
+const DEFAULT_CHANNELS: AudioChannel[] = ["master", "sfx", "music", "voice", "ambient", "ui"];
+
+const DEFAULT_EFFECT_PARAMS: Record<AudioEffectType, Record<string, number>> = {
+  reverb: { roomSize: 0.5, decay: 0.5, diffusion: 0.7 },
+  lowpass: { cutoff: 1000, resonance: 0.1 },
+  highpass: { cutoff: 100, resonance: 0.1 },
+  echo: { delay: 0.3, feedback: 0.4, mix: 0.3 },
+  distortion: { drive: 0.5, threshold: 0.1 },
+  chorus: { rate: 0.5, depth: 0.3, mix: 0.3 },
+};
+
+export class AudioMixer {
+  private backend: AudioBackend;
+  private channels: Map<AudioChannel, MixerChannelState> = new Map();
+  private nextEffectId = 1;
+
+  constructor(backend: AudioBackend) {
+    this.backend = backend;
+    DEFAULT_CHANNELS.forEach((name) => {
+      this.channels.set(name, {
+        name,
+        volume: name === "master" ? 1.0 : 0.8,
+        muted: false,
+        effects: new Map(),
+      });
+      this.backend.setChannelVolume(name, name === "master" ? 1.0 : 0.8);
+    });
+  }
+
+  setVolume(channel: AudioChannel, volume: number): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    state.volume = Math.max(0, Math.min(1, volume));
+    this.backend.setChannelVolume(channel, state.volume);
+  }
+
+  getVolume(channel: AudioChannel): number {
+    return this.channels.get(channel)?.volume ?? 0;
+  }
+
+  mute(channel: AudioChannel): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    state.muted = true;
+    this.backend.setChannelMuted?.(channel, true);
+  }
+
+  unmute(channel: AudioChannel): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    state.muted = false;
+    this.backend.setChannelMuted?.(channel, false);
+  }
+
+  isMuted(channel: AudioChannel): boolean {
+    return this.channels.get(channel)?.muted ?? false;
+  }
+
+  setChannelVolume(channel: AudioChannel, volume: number): void {
+    this.setVolume(channel, volume);
+  }
+
+  getChannelVolume(channel: AudioChannel): number {
+    return this.getVolume(channel);
+  }
+
+  setChannelMute(channel: AudioChannel, muted: boolean): void {
+    if (muted) this.mute(channel);
+    else this.unmute(channel);
+  }
+
+  isChannelMuted(channel: AudioChannel): boolean {
+    return this.isMuted(channel);
+  }
+
+  addEffect(channel: AudioChannel, typeOrEffect: AudioEffectType | AudioEffectDesc, params?: Partial<Record<string, number>>, wet = 1.0, dry = 1.0): number {
+    const state = this.channels.get(channel);
+    if (!state) return -1;
+    let effect: AudioEffectDesc;
+    if (typeof typeOrEffect === "object") {
+      effect = typeOrEffect;
+    } else {
+      effect = {
+        type: typeOrEffect,
+        params: { ...DEFAULT_EFFECT_PARAMS[typeOrEffect], ...params } as Record<string, number>,
+        wet,
+        dry,
+      };
+    }
+    const id = this.backend.addEffect(channel, effect);
+    const safeId = id >= 0 ? id : this.nextEffectId;
+    if (safeId === this.nextEffectId) {
+      this.nextEffectId = (this.nextEffectId + 1) % 0x7fffffff;
+    }
+    state.effects.set(safeId, effect);
+    return safeId;
+  }
+
+  removeEffect(channel: AudioChannel, effectId: number): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    this.backend.removeEffect(channel, effectId);
+    state.effects.delete(effectId);
+  }
+
+  updateEffect(channel: AudioChannel, effectId: number, params: Partial<Record<string, number>>): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    const effect = state.effects.get(effectId);
+    if (!effect) return;
+    effect.params = { ...effect.params, ...params } as Record<string, number>;
+    this.backend.updateEffect?.(channel, effectId, effect.params);
+  }
+
+  getChannelState(channel: AudioChannel): MixerChannelState | undefined {
+    return this.channels.get(channel);
+  }
+
+  listChannels(): AudioChannel[] {
+    return [...this.channels.keys()];
+  }
+
+  reset(): void {
+    for (const [name, state] of this.channels.entries()) {
+      state.volume = name === "master" ? 1.0 : 0.8;
+      state.muted = false;
+      state.effects.clear();
+      this.backend.setChannelVolume(name, state.volume);
+      this.backend.setChannelMuted?.(name, false);
+    }
+  }
+}

package/core/src/audio/registry.ts

@@ -0,0 +1,52 @@
+import type { AudioBackend } from "./interface";
+
+class AudioBackendRegistry {
+  private backends: Map<string, AudioBackend> = new Map();
+  private defaultBackend: AudioBackend | null = null;
+
+  register(name: string, backend: AudioBackend): void {
+    this.backends.set(name, backend);
+    if (!this.defaultBackend) {
+      this.defaultBackend = backend;
+    }
+  }
+
+  unregister(name: string): void {
+    const backend = this.backends.get(name);
+    if (backend) {
+      backend.destroy();
+      this.backends.delete(name);
+      if (this.defaultBackend === backend) {
+        this.defaultBackend = this.backends.values().next().value ?? null;
+      }
+    }
+  }
+
+  get(name: string): AudioBackend | undefined {
+    return this.backends.get(name);
+  }
+
+  getDefault(): AudioBackend | null {
+    return this.defaultBackend;
+  }
+
+  setDefault(name: string): void {
+    const backend = this.backends.get(name);
+    if (!backend) throw new Error(`Audio backend "${name}" not registered`);
+    this.defaultBackend = backend;
+  }
+
+  list(): string[] {
+    return [...this.backends.keys()];
+  }
+
+  destroyAll(): void {
+    for (const backend of this.backends.values()) {
+      backend.destroy();
+    }
+    this.backends.clear();
+    this.defaultBackend = null;
+  }
+}
+
+export const audioBackendRegistry = new AudioBackendRegistry();

package/core/src/audio/sab.ts

@@ -0,0 +1,87 @@
+import type { SABChannel } from "../module/module";
+import { defineChannel } from "../sab/define";
+import type { AudioListenerState } from "./interface";
+
+export const AudioSABChannelDef = defineChannel({
+  name: "audio-position",
+  magic: 0x41554449,
+  version: 1,
+  mode: "record",
+  header: { size: 64, fields: {} },
+  fields: {
+    sourcePositions: { type: "f32", count: 32 },
+    listenerPosition: { type: "f32", count: 3 },
+    listenerOrientation: { type: "f32", count: 4 },
+  },
+});
+
+export interface AudioSABData {
+  sourcePositions: number[];
+  listenerPosition: number[];
+  listenerOrientation: number[];
+}
+
+export class AudioSABChannel {
+  private writer: ReturnType<typeof AudioSABChannelDef.writer>;
+  private reader: ReturnType<typeof AudioSABChannelDef.reader>;
+  private sourcePositions: number[] = new Array(32).fill(0);
+  private listener: AudioListenerState = {
+    position: [0, 0, 0],
+    orientation: [0, 0, 0, 1],
+    velocity: [0, 0, 0],
+    gain: 1.0,
+  };
+
+  constructor(channel: SABChannel) {
+    this.writer = AudioSABChannelDef.writer(channel.buffer);
+    this.reader = AudioSABChannelDef.reader(channel.buffer);
+  }
+
+  setListener(listener: AudioListenerState): void {
+    this.listener = listener;
+  }
+
+  setSourcePositions(positions: Array<[number, number, number]>): void {
+    if (positions.length > 32) {
+      throw new RangeError(`setSourcePositions: positions.length ${positions.length} exceeds max 32`);
+    }
+    for (let i = 0; i < 32; i++) {
+      const offset = i * 3;
+      if (i < positions.length) {
+        this.sourcePositions[offset] = positions[i][0];
+        this.sourcePositions[offset + 1] = positions[i][1];
+        this.sourcePositions[offset + 2] = positions[i][2];
+      } else {
+        this.sourcePositions[offset] = 0;
+        this.sourcePositions[offset + 1] = 0;
+        this.sourcePositions[offset + 2] = 0;
+      }
+    }
+  }
+
+  write(): void {
+    const w = this.writer;
+    const off = AudioSABChannelDef.offsets.fields;
+    for (let i = 0; i < 32; i++) {
+      (w.fields.sourcePositions as Float32Array)[i] = this.sourcePositions[i];
+    }
+    (w.fields.listenerPosition as Float32Array)[0] = this.listener.position[0];
+    (w.fields.listenerPosition as Float32Array)[1] = this.listener.position[1];
+    (w.fields.listenerPosition as Float32Array)[2] = this.listener.position[2];
+    (w.fields.listenerOrientation as Float32Array)[0] = this.listener.orientation[0];
+    (w.fields.listenerOrientation as Float32Array)[1] = this.listener.orientation[1];
+    (w.fields.listenerOrientation as Float32Array)[2] = this.listener.orientation[2];
+    (w.fields.listenerOrientation as Float32Array)[3] = this.listener.orientation[3] ?? 0;
+    w.bumpSequence();
+  }
+
+  read(): AudioSABData | null {
+    const data = this.reader.snapshot();
+    if (!data) return null;
+    return {
+      sourcePositions: data.sourcePositions as number[],
+      listenerPosition: data.listenerPosition as number[],
+      listenerOrientation: data.listenerOrientation as number[],
+    };
+  }
+}

package/core/src/audio/source.ts

@@ -0,0 +1,89 @@
+import type { IComponent } from "../ecs/component";
+import { Component } from "../ecs/component";
+import type { AudioChannel } from "./interface";
+
+export interface AudioSourceData {
+  [key: string]: unknown;
+  bufferId: string;
+  playing: boolean;
+  paused: boolean;
+  loop: boolean;
+  looping: boolean;
+  volume: number;
+  pitch: number;
+  pan: number;
+  spatial: boolean;
+  spatialized: boolean;
+  position: [number, number, number];
+  velocity: [number, number, number];
+  minDistance: number;
+  maxDistance: number;
+  rolloffFactor: number;
+  channel: AudioChannel;
+  sourceId: number;
+  autoPlay: boolean;
+}
+
+export const AudioSource = Component.register<AudioSourceData>("AudioSource", {
+  bufferId: "",
+  playing: false,
+  paused: false,
+  loop: false,
+  looping: false,
+  volume: 1.0,
+  pitch: 1.0,
+  pan: 0.0,
+  spatial: false,
+  spatialized: false,
+  position: [0, 0, 0],
+  velocity: [0, 0, 0],
+  minDistance: 1.0,
+  maxDistance: 100.0,
+  rolloffFactor: 1.0,
+  channel: "master",
+  sourceId: -1,
+  autoPlay: false,
+});
+
+const _originalCreate = AudioSource.create;
+AudioSource.create = (overrides?: Partial<AudioSourceData>): AudioSourceData & IComponent => {
+  const { looping, ...rest } = overrides ?? {};
+  if (looping !== undefined && rest.loop === undefined) {
+    rest.loop = looping;
+  }
+  const instance = _originalCreate(rest);
+  Object.defineProperty(instance, "looping", {
+    get(this: AudioSourceData) { return this.loop; },
+    set(this: AudioSourceData, v: boolean) { this.loop = v; },
+    enumerable: true,
+    configurable: true,
+  });
+  return instance as AudioSourceData & IComponent;
+};
+
+export function createAudioSource(bufferId: string, opts?: Partial<AudioSourceData>): AudioSourceData {
+  return AudioSource.create({ bufferId, spatialized: false, spatial: false, looping: opts?.loop ?? false, ...opts });
+}
+
+export function createSpatialAudioSource(bufferId: string, opts?: Partial<AudioSourceData>): AudioSourceData {
+  return AudioSource.create({
+    bufferId,
+    position: opts?.position ?? [0, 0, 0],
+    maxDistance: opts?.maxDistance ?? 100,
+    ...opts,
+    spatialized: true,
+    spatial: true,
+  });
+}
+
+export function createAmbientAudioSource(bufferId: string, opts?: Partial<AudioSourceData>): AudioSourceData {
+  return AudioSource.create({
+    bufferId,
+    channel: "ambient",
+    ...opts,
+    spatialized: false,
+    spatial: false,
+    looping: opts?.looping ?? true,
+    loop: opts?.loop ?? true,
+  });
+}

package/core/src/change-detection/atomics.ts

@@ -0,0 +1 @@
+export { ChangeTracker } from "./tracker";

package/core/src/change-detection/tracker.ts

@@ -0,0 +1,47 @@
+import type { ComponentId } from "../ecs/component";
+import type { Entity } from "../ecs/entity";
+import type { World } from "../ecs/world";
+import type { Archetype } from "../ecs/archetype";
+import { findEntityRow } from "../ecs/archetype";
+
+export class ChangeTracker {
+  private world: World;
+
+  constructor(world: World) {
+    this.world = world;
+  }
+
+  write<T extends { lastChanged?: number }>(
+    entity: Entity,
+    componentId: ComponentId,
+    mutator: (data: T) => void,
+  ): void {
+    const data = this.world.getComponent<T>(entity, componentId);
+    if (!data) return;
+    mutator(data);
+    data.lastChanged = this.world.tick;
+  }
+
+  wasChanged(
+    entity: Entity,
+    componentId: ComponentId,
+    sinceTick: number,
+  ): boolean {
+    const data = this.world.getComponent<{ lastChanged?: number }>(entity, componentId);
+    if (!data) return false;
+    return (data.lastChanged ?? 0) >= sinceTick;
+  }
+
+  static writeToColumn<T extends { lastChanged?: number }>(
+    arch: Archetype,
+    row: number,
+    componentId: ComponentId,
+    tick: number,
+    mutator: (data: T) => void,
+  ): void {
+    const col = arch.columns.get(componentId) as T[];
+    if (!col || row >= col.length) return;
+    mutator(col[row]);
+    col[row].lastChanged = tick;
+  }
+}

package/core/src/debug-draw/lines.ts

@@ -0,0 +1,64 @@
+import { DebugDrawQueue } from "./queue";
+
+export class DebugLines {
+  private queue: DebugDrawQueue;
+
+  constructor(queue: DebugDrawQueue) {
+    this.queue = queue;
+  }
+
+  line(
+    from: [number, number, number],
+    to: [number, number, number],
+    color?: [number, number, number, number],
+  ): void {
+    this.queue.line(from, to, color);
+  }
+
+  ray(
+    origin: [number, number, number],
+    dir: [number, number, number],
+    length: number,
+    color?: [number, number, number, number],
+  ): void {
+    this.queue.line(
+      origin,
+      [origin[0] + dir[0] * length, origin[1] + dir[1] * length, origin[2] + dir[2] * length],
+      color,
+    );
+  }
+
+  grid(
+    center: [number, number, number],
+    size: number,
+    divisions: number,
+    color?: [number, number, number, number],
+  ): void {
+    const half = size / 2;
+    const step = size / divisions;
+    for (let i = 0; i <= divisions; i++) {
+      const offset = -half + i * step;
+      this.queue.line(
+        [center[0] + offset, center[1], center[2] - half],
+        [center[0] + offset, center[1], center[2] + half],
+        color,
+      );
+      this.queue.line(
+        [center[0] - half, center[1], center[2] + offset],
+        [center[0] + half, center[1], center[2] + offset],
+        color,
+      );
+    }
+  }
+
+  cross(
+    pos: [number, number, number],
+    size: number,
+    color?: [number, number, number, number],
+  ): void {
+    const s = size / 2;
+    this.queue.line([pos[0] - s, pos[1], pos[2]], [pos[0] + s, pos[1], pos[2]], color);
+    this.queue.line([pos[0], pos[1] - s, pos[2]], [pos[0], pos[1] + s, pos[2]], color);
+    this.queue.line([pos[0], pos[1], pos[2] - s], [pos[0], pos[1], pos[2] + s], color);
+  }
+}

package/core/src/debug-draw/points.ts

@@ -0,0 +1,17 @@
+import { DebugDrawQueue } from "./queue";
+
+export class DebugPoints {
+  private queue: DebugDrawQueue;
+
+  constructor(queue: DebugDrawQueue) {
+    this.queue = queue;
+  }
+
+  point(
+    pos: [number, number, number],
+    color?: [number, number, number, number],
+    size?: number,
+  ): void {
+    this.queue.point(pos, color, size);
+  }
+}