@vgai/engine 0.2.0

package/src/audio/weapons.ts

@@ -0,0 +1,152 @@
+/**
+ * Weapon sounds — procedural combat audio.
+ *
+ * gunshot and laser are one-shot. chargeUp is continuous (play/stop).
+ */
+
+function createNoiseBuffer(ctx: AudioContext, duration = 1): AudioBuffer {
+  const length = ctx.sampleRate * duration;
+  const buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+  return buffer;
+}
+
+/** Sharp gunshot — highpass-filtered noise click. */
+export function gunshot(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; duration?: number },
+) {
+  const pitch = options?.pitch ?? 1200;
+  const volume = options?.volume ?? 0.6;
+  const duration = options?.duration ?? 0.08;
+  const noiseBuffer = createNoiseBuffer(ctx, 0.3);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+
+      const hp = ctx.createBiquadFilter();
+      hp.type = 'highpass';
+      hp.frequency.value = pitch;
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      src.connect(hp);
+      hp.connect(env);
+      env.connect(out);
+      src.start(now);
+      src.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Laser — descending sawtooth frequency sweep. */
+export function laser(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { startFreq?: number; endFreq?: number; volume?: number; duration?: number },
+) {
+  const startFreq = options?.startFreq ?? 1200;
+  const endFreq = options?.endFreq ?? 200;
+  const volume = options?.volume ?? 0.4;
+  const duration = options?.duration ?? 0.2;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const osc = ctx.createOscillator();
+      osc.type = 'sawtooth';
+      osc.frequency.setValueAtTime(startFreq, now);
+      osc.frequency.exponentialRampToValueAtTime(endFreq, now + duration);
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      osc.connect(env);
+      env.connect(out);
+      osc.start(now);
+      osc.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Charge-up tone — ascending pitch, call play() to start and stop() to end. */
+export function chargeUp(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { startFreq?: number; endFreq?: number; volume?: number; duration?: number },
+) {
+  const startFreq = options?.startFreq ?? 100;
+  const endFreq = options?.endFreq ?? 800;
+  const volume = options?.volume ?? 0.3;
+  const duration = options?.duration ?? 2.0;
+
+  const out = ctx.createGain();
+  out.gain.value = 0;
+  out.connect(dest);
+
+  let osc: OscillatorNode | null = null;
+
+  return {
+    play() {
+      if (osc) return;
+      const now = ctx.currentTime;
+      osc = ctx.createOscillator();
+      osc.type = 'sawtooth';
+      osc.frequency.setValueAtTime(startFreq, now);
+      osc.frequency.exponentialRampToValueAtTime(endFreq, now + duration);
+      osc.connect(out);
+      osc.start(now);
+      out.gain.setValueAtTime(0.001, now);
+      out.gain.exponentialRampToValueAtTime(volume, now + 0.05);
+    },
+    stop() {
+      if (!osc) return;
+      const now = ctx.currentTime;
+      out.gain.setTargetAtTime(0, now, 0.02);
+      const ref = osc;
+      osc = null;
+      setTimeout(() => {
+        try {
+          ref.stop();
+        } catch {
+          /* already stopped */
+        }
+        ref.disconnect();
+      }, 100);
+    },
+    dispose() {
+      if (osc) {
+        try {
+          osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        osc.disconnect();
+        osc = null;
+      }
+      out.disconnect();
+    },
+  };
+}

package/src/core/game-loop.ts

@@ -0,0 +1,127 @@
+import type { GameLoopConfig } from './types';
+
+/**
+ * Fixed-timestep game loop with accumulator pattern.
+ *
+ * Physics/logic run at a fixed rate (default 60 Hz) regardless of display
+ * frame rate. Rendering is deliberately fixed-rate too (decided — D1, see
+ * `docs/DECISIONS-PENDING.md`): `config.update(fixedDt)` runs once per
+ * consumed substep, and per the documented phase order (`PHASE_ORDER` in
+ * `core/types.ts`) the `render` phase executes as the last phase of that
+ * same call — there is no separate per-real-frame render step and no
+ * display-refresh interpolation. A frame whose accumulator produces zero
+ * substeps therefore calls `update` zero times and renders zero times; do
+ * not reintroduce a render call outside the substep loop below.
+ */
+export function createGameLoop(config: GameLoopConfig) {
+  const fixedDt = config.fixedTimestep ?? 1 / 60;
+  const maxSubSteps = config.maxSubSteps ?? 8;
+  // Also the accumulator's hard ceiling (see the spiral-of-death guard below).
+  const maxAccumulator = fixedDt * maxSubSteps;
+
+  let accumulator = 0;
+  let lastTime = 0;
+  let running = false;
+  let rafId = 0;
+  let timeScale = 1.0;
+
+  // Idle throttle (T2.1): a hidden tab stops the loop outright; becoming
+  // visible again restarts it with the accumulator clock resynced to "now" —
+  // deliberately no catch-up burst for the wall-clock time spent hidden.
+  let hiddenPaused = false;
+  let visibilityListenerAttached = false;
+
+  function handleVisibilityChange() {
+    if (typeof document === 'undefined') return;
+    if (document.hidden) {
+      if (running) {
+        running = false;
+        cancelAnimationFrame(rafId);
+        hiddenPaused = true;
+      }
+    } else if (hiddenPaused) {
+      hiddenPaused = false;
+      running = true;
+      lastTime = performance.now();
+      accumulator = 0;
+      rafId = requestAnimationFrame(frame);
+    }
+  }
+
+  function frame(currentTime: number) {
+    if (!running) return;
+    rafId = requestAnimationFrame(frame);
+
+    // Convert to seconds
+    const rawDt = (currentTime - lastTime) / 1000;
+    lastTime = currentTime;
+
+    // Clamp large frame gaps (e.g. a slow frame) before scaling by timeScale.
+    const dt = Math.min(rawDt, maxAccumulator) * timeScale;
+    accumulator += dt;
+    // Spiral-of-death guard: bound the accumulator regardless of timeScale
+    // (up to the clamped max of 8) or frame-gap size. Time that can't
+    // possibly be caught up on is dropped, never carried forward.
+    if (accumulator > maxAccumulator) accumulator = maxAccumulator;
+
+    // Run fixed timestep updates (this is also where rendering happens —
+    // see the module doc comment above).
+    let steps = 0;
+    while (accumulator >= fixedDt && steps < maxSubSteps) {
+      config.update(fixedDt);
+      accumulator -= fixedDt;
+      steps++;
+    }
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      // A direct start() call can land while the loop is auto-hidden-paused
+      // (`hiddenPaused` true, `running` false, no rAF pending). Without this
+      // reset, a later visibilitychange-to-visible would see stale
+      // `hiddenPaused === true` and spawn a SECOND rAF chain on top of the
+      // one this call is about to start (doubled update()/render() overhead
+      // until the next stop() — no sim-speed effect, but wasted work).
+      hiddenPaused = false;
+      lastTime = performance.now();
+      accumulator = 0;
+      rafId = requestAnimationFrame(frame);
+
+      if (!visibilityListenerAttached && typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        visibilityListenerAttached = true;
+      }
+    },
+
+    stop() {
+      running = false;
+      hiddenPaused = false;
+      cancelAnimationFrame(rafId);
+
+      if (visibilityListenerAttached && typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', handleVisibilityChange);
+        visibilityListenerAttached = false;
+      }
+    },
+
+    get isRunning() {
+      return running;
+    },
+
+    set timeScale(value: number) {
+      const clamped = Math.min(8, Math.max(0, value));
+      if (clamped !== value) {
+        console.warn(
+          `[game-loop] timeScale ${value} is out of range [0, 8]; clamped to ${clamped}.`,
+        );
+      }
+      timeScale = clamped;
+    },
+
+    get timeScale() {
+      return timeScale;
+    },
+  };
+}

package/src/core/system-runner.ts

@@ -0,0 +1,298 @@
+import { PHASE_ORDER, type SystemDef, type SystemFn, type SystemPhaseName } from './types';
+
+/**
+ * Ordered system execution by named phase.
+ *
+ * Systems are registered with a phase name. When `run(dt)` is called, all
+ * phases execute in `PHASE_ORDER` via `runPhase(phase, dt)`. Within a phase,
+ * `runPhase` executes three ordered buckets (GAME-ROOT-DESIGN.md §4, T7.1
+ * slice 2):
+ *
+ *   1. **engine** — everything `add()`/`register()`ed at or before the last
+ *      `markEngineBoundary()` call, or EVERYTHING if no boundary has ever
+ *      been marked (the world2d-silo case: it never calls
+ *      `markEngineBoundary`, so its systems are all "engine").
+ *   2. **componentTick** — the single per-phase slot set via
+ *      `setComponentTick(phase, fn)`. Component ticks are engine
+ *      infrastructure: they always run after every engine system and before
+ *      every game system in that phase, REGARDLESS of when
+ *      `setComponentTick` was called relative to other `add()` calls. This
+ *      is what makes "engine systems run before component ticks" a
+ *      structural guarantee rather than a registration-order convention
+ *      (see `component-manager.ts`, which registers its tick this way).
+ *   3. **game** — everything `add()`/`register()`ed AFTER the last
+ *      `markEngineBoundary()` call.
+ *
+ * Within each bucket, systems run in registration order.
+ */
+export function createSystemRunner() {
+  const systems = new Map<SystemPhaseName, SystemFn[]>();
+  const registered: SystemDef[] = [];
+  const componentTicks = new Map<SystemPhaseName, SystemFn | null>();
+
+  // Initialize all phases with empty arrays / no component tick.
+  for (const phase of PHASE_ORDER) {
+    systems.set(phase, []);
+    componentTicks.set(phase, null);
+  }
+
+  // Membership bookkeeping for `markEngineBoundary()` (T7.2 review fix —
+  // replaces the old length/index-snapshot bookkeeping, which broke if a
+  // pre-boundary "engine" entry was ever removed: shrinking the list would
+  // shift a later "game" entry underneath the recorded length, misclassifying
+  // it as engine). `engineFns`/`engineRegistered` instead record WHICH
+  // specific function/system was present at the last `markEngineBoundary()`
+  // call — membership survives arbitrary removal of any other entry,
+  // regardless of position. `boundaryMarked` is false until the first mark
+  // (mirrors the old `boundary === null`: everything is "engine" pre-mark —
+  // the world2d-silo case, which never marks a boundary). Component-tick
+  // slots (`setComponentTick`) are NOT part of this bookkeeping at all — they
+  // are engine infrastructure and survive `removeAllNonEngine()`
+  // unconditionally.
+  let boundaryMarked = false;
+  const engineFns = new Map<SystemPhaseName, Set<SystemFn>>();
+  for (const phase of PHASE_ORDER) engineFns.set(phase, new Set());
+  const engineRegistered = new Set<SystemDef>();
+
+  /** Run one system function, isolating a throw so it never wedges the frame. */
+  function runOne(fn: SystemFn, phase: SystemPhaseName, dt: number): void {
+    try {
+      fn(dt);
+    } catch (err) {
+      const label = fn.name ? `"${fn.name}"` : '(anonymous)';
+      console.error(`[system-runner] system ${label} in phase "${phase}" threw:`, err);
+    }
+  }
+
+  return {
+    /**
+     * Register a bare system function in a specific phase.
+     * Systems within the same phase run in the order they were added.
+     */
+    add(phase: SystemPhaseName, fn: SystemFn) {
+      const list = systems.get(phase);
+      if (!list) {
+        throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+      }
+      list.push(fn);
+    },
+
+    /**
+     * Remove a bare system function from a phase. Also drops it from the
+     * engine-membership set (if present) — the fix for the length-based
+     * bookkeeping bug: removing this has no effect on how any OTHER entry
+     * (before or after it) is classified, since classification is now
+     * per-function membership, not position.
+     */
+    remove(phase: SystemPhaseName, fn: SystemFn) {
+      const list = systems.get(phase);
+      if (!list) return;
+      const idx = list.indexOf(fn);
+      if (idx !== -1) list.splice(idx, 1);
+      engineFns.get(phase)?.delete(fn);
+    },
+
+    /**
+     * Register a lifecycle system. Adds its update to the correct phase.
+     * Call runInit() after all systems are registered to invoke init hooks.
+     */
+    register(system: SystemDef) {
+      const list = systems.get(system.phase);
+      if (!list) {
+        throw new Error(`Unknown phase: ${system.phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+      }
+      list.push(system.update);
+      registered.push(system);
+    },
+
+    /**
+     * Unregister a lifecycle system. Removes its update and calls dispose.
+     */
+    unregister(system: SystemDef) {
+      const list = systems.get(system.phase);
+      if (list) {
+        const idx = list.indexOf(system.update);
+        if (idx !== -1) list.splice(idx, 1);
+      }
+      engineFns.get(system.phase)?.delete(system.update);
+      const regIdx = registered.indexOf(system);
+      if (regIdx !== -1) registered.splice(regIdx, 1);
+      engineRegistered.delete(system);
+      system.dispose?.();
+    },
+
+    /**
+     * Register the ONE component-tick function for a phase (T7.1 slice 2).
+     * Component ticks are engine infrastructure, not a bare `add()`ed
+     * system: they always execute after every engine-bucket system and
+     * before every game-bucket system in that phase (see `runPhase`),
+     * they are never touched by `removeAllNonEngine()`, and they do not
+     * count toward `markEngineBoundary()`'s bookkeeping. Throws if a tick
+     * is already set for this phase — at most one component manager may
+     * own a phase's tick slot.
+     */
+    setComponentTick(phase: SystemPhaseName, fn: SystemFn) {
+      if (!componentTicks.has(phase)) {
+        throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+      }
+      if (componentTicks.get(phase)) {
+        throw new Error(
+          `[system-runner] setComponentTick: phase "${phase}" already has a component tick registered`,
+        );
+      }
+      componentTicks.set(phase, fn);
+    },
+
+    /**
+     * Call init() on all registered lifecycle systems, in phase order.
+     * Call once after scene load, before the first game loop tick.
+     */
+    runInit() {
+      const sorted = [...registered].sort(
+        (a, b) => PHASE_ORDER.indexOf(a.phase) - PHASE_ORDER.indexOf(b.phase),
+      );
+      for (const sys of sorted) {
+        sys.init?.();
+      }
+    },
+
+    /**
+     * Call dispose() on all registered lifecycle systems and remove them.
+     */
+    runDispose() {
+      for (const sys of registered) {
+        const list = systems.get(sys.phase);
+        if (list) {
+          const idx = list.indexOf(sys.update);
+          if (idx !== -1) list.splice(idx, 1);
+        }
+        sys.dispose?.();
+      }
+      registered.length = 0;
+    },
+
+    /**
+     * Run ONE phase's three ordered buckets — engine, componentTick, game
+     * (see the module doc comment). Each system call is isolated: a
+     * throwing system is loudly logged (never swallowed) but does not stop
+     * its siblings in the same bucket, a later bucket in this phase, or a
+     * later phase, from running this frame.
+     *
+     * Public — the Game root's frame executor (`runtime/game.ts`) calls this
+     * directly per (phase, world); `run(dt)` below is just a loop over it,
+     * preserved for the world2d silo and any direct caller.
+     */
+    runPhase(phase: SystemPhaseName, dt: number) {
+      const list = systems.get(phase);
+      if (!list) {
+        throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+      }
+      // Partition by MEMBERSHIP, not position: everything in this phase's
+      // `engineFns` set (or, if no boundary has ever been marked, everything —
+      // the world2d-silo case) runs immediately, in list order, as it's
+      // encountered; everything else is queued into `gameFns` (also in list
+      // order) and run after the component tick. Because classification is
+      // per-function rather than "index < some remembered length", removing
+      // ANY entry via `remove()` — including a pre-boundary "engine" one —
+      // cannot shift a later game system into the engine bucket.
+      const engineSet = engineFns.get(phase)!;
+      const gameFns: SystemFn[] = [];
+      for (const fn of list) {
+        if (boundaryMarked && !engineSet.has(fn)) {
+          gameFns.push(fn);
+        } else {
+          runOne(fn, phase, dt);
+        }
+      }
+
+      const tick = componentTicks.get(phase);
+      if (tick) runOne(tick, phase, dt);
+
+      for (const fn of gameFns) {
+        runOne(fn, phase, dt);
+      }
+    },
+
+    /**
+     * Run all phases in order, via `runPhase`.
+     */
+    run(dt: number) {
+      for (const phase of PHASE_ORDER) {
+        this.runPhase(phase, dt);
+      }
+    },
+
+    /**
+     * Mark everything registered so far (via `add()`/`register()`, in every
+     * phase) as "engine" — infrastructure that must survive a warm restart.
+     * Call once, right after mount finishes wiring engine-level systems and
+     * BEFORE any game (`setup()`/scene load) registers its own. `hotReload`
+     * calls `removeAllNonEngine()` on every restart, which only ever removes
+     * what was added after this mark. Component-tick slots (`setComponentTick`)
+     * are unaffected — they are never part of this boundary.
+     */
+    markEngineBoundary() {
+      for (const phase of PHASE_ORDER) {
+        const set = engineFns.get(phase)!;
+        for (const fn of systems.get(phase)!) set.add(fn);
+      }
+      for (const sys of registered) engineRegistered.add(sys);
+      boundaryMarked = true;
+    },
+
+    /**
+     * Bulk-remove every system registered after the last `markEngineBoundary()`
+     * call — both bare `add()`ed functions and lifecycle `register()`ed systems
+     * (the latter get `dispose()`d, mirroring `unregister()`). A no-op if no
+     * boundary has been marked. Idempotent: calling it again with nothing new
+     * registered since is a safe no-op. Component-tick slots are NEVER cleared
+     * by this — they are engine infrastructure, not game content.
+     *
+     * This is what makes a warm restart (`hotReload`) safe to call N times
+     * without accumulating duplicate systems/listeners — each restart's
+     * outgoing game systems are fully removed before the new one registers its
+     * own, while the engine systems (input/physics/render/the ComponentManager
+     * tick/...) registered before the boundary are never touched.
+     */
+    removeAllNonEngine() {
+      if (!boundaryMarked) return;
+      // Membership-based, same reasoning as runPhase: partition by whether
+      // each entry is in the engine set, not by a remembered length/index.
+      const keptRegistered = registered.filter((sys) => engineRegistered.has(sys));
+      const removedRegistered = registered.filter((sys) => !engineRegistered.has(sys));
+      registered.length = 0;
+      registered.push(...keptRegistered);
+      for (const sys of removedRegistered) {
+        sys.dispose?.();
+      }
+
+      for (const phase of PHASE_ORDER) {
+        const list = systems.get(phase)!;
+        const engineSet = engineFns.get(phase)!;
+        const kept = list.filter((fn) => engineSet.has(fn));
+        list.length = 0;
+        list.push(...kept);
+      }
+    },
+
+    /**
+     * Total system-function count, optionally scoped to one phase. Includes
+     * component-tick slots (a set slot counts as 1 per phase it occupies).
+     * Test/introspection helper — used to assert a warm restart doesn't
+     * accumulate systems (see `removeAllNonEngine`).
+     */
+    count(phase?: SystemPhaseName): number {
+      if (phase) {
+        return (systems.get(phase)?.length ?? 0) + (componentTicks.get(phase) ? 1 : 0);
+      }
+      let total = 0;
+      for (const [p, list] of systems) {
+        total += list.length;
+        if (componentTicks.get(p)) total += 1;
+      }
+      return total;
+    },
+  };
+}
+
+export type SystemRunner = ReturnType<typeof createSystemRunner>;

package/src/core/types.ts

@@ -0,0 +1,58 @@
+/**
+ * System execution phases, in order.
+ * Each frame, systems run in this exact sequence.
+ */
+export const SystemPhase = {
+  INPUT: 'input',
+  PRE_PHYSICS: 'prePhysics',
+  PHYSICS: 'physics',
+  POST_PHYSICS: 'postPhysics',
+  GAME_LOGIC: 'gameLogic',
+  ANIMATION: 'animation',
+  PRE_RENDER: 'preRender',
+  RENDER: 'render',
+} as const;
+
+export type SystemPhaseName = (typeof SystemPhase)[keyof typeof SystemPhase];
+
+/** Order of phase execution */
+export const PHASE_ORDER: SystemPhaseName[] = [
+  SystemPhase.INPUT,
+  SystemPhase.PRE_PHYSICS,
+  SystemPhase.PHYSICS,
+  SystemPhase.POST_PHYSICS,
+  SystemPhase.GAME_LOGIC,
+  SystemPhase.ANIMATION,
+  SystemPhase.PRE_RENDER,
+  SystemPhase.RENDER,
+];
+
+/** A system is just a function that takes delta time */
+export type SystemFn = (dt: number) => void;
+
+/** A lifecycle system with init/update/dispose hooks. */
+export interface SystemDef {
+  /** Which phase the update function runs in */
+  phase: SystemPhaseName;
+  /** One-time setup after all entities are spawned, before the first frame */
+  init?(): void;
+  /** Per-frame update */
+  update: SystemFn;
+  /** Cleanup when the system is removed or the scene unloads */
+  dispose?(): void;
+}
+
+export interface GameLoopConfig {
+  /** Fixed timestep in seconds (default: 1/60) */
+  fixedTimestep?: number;
+  /** Max physics substeps per frame to prevent spiral of death (default: 8) */
+  maxSubSteps?: number;
+  /**
+   * Called once per consumed fixed substep. Rendering (the `render` phase,
+   * last in `PHASE_ORDER`) runs *inside* this call — rendering is
+   * deliberately fixed-rate (decided — D1, `docs/DECISIONS-PENDING.md`),
+   * not a separate per-real-frame step. A real frame whose accumulator
+   * produces zero substeps calls `update` zero times and renders zero times.
+   */
+  update: (dt: number) => void;
+}