@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/audio/vehicle.ts

@@ -1,235 +0,0 @@
-/**
- * Vehicle sounds — continuous sounds with real-time parameter control.
- *
- * Each returns play/stop/setX/dispose. Parameters use setTargetAtTime for smooth ramping.
- */
-
-function createNoiseBuffer(ctx: AudioContext, duration = 2): 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;
-}
-
-/** Engine drone — sawtooth oscillator with throttle-driven pitch and volume. */
-export function engineDrone(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { baseFreq?: number; volume?: number },
-) {
-  const baseFreq = options?.baseFreq ?? 60;
-  const maxVol = options?.volume ?? 0.4;
-
-  const out = ctx.createGain();
-  out.gain.value = 0;
-  out.connect(dest);
-
-  // Subtle waveshaping for grit
-  const shaper = ctx.createWaveShaper();
-  const curve = new Float32Array(256);
-  for (let i = 0; i < 256; i++) {
-    const x = (i / 128 - 1) * 1.5;
-    curve[i] = Math.tanh(x);
-  }
-  shaper.curve = curve;
-  shaper.connect(out);
-
-  let osc: OscillatorNode | null = null;
-
-  return {
-    play() {
-      if (osc) return;
-      osc = ctx.createOscillator();
-      osc.type = 'sawtooth';
-      osc.frequency.value = baseFreq;
-      osc.connect(shaper);
-      osc.start();
-      out.gain.setTargetAtTime(0.1, ctx.currentTime, 0.05);
-    },
-    stop() {
-      if (!osc) return;
-      out.gain.setTargetAtTime(0, ctx.currentTime, 0.05);
-      const ref = osc;
-      osc = null;
-      setTimeout(() => {
-        try {
-          ref.stop();
-        } catch {
-          /* already stopped */
-        }
-        ref.disconnect();
-      }, 200);
-    },
-    /** Set throttle 0–1. Adjusts pitch (1x–3x base) and volume. */
-    setThrottle(t: number) {
-      if (!osc) return;
-      const clamped = Math.max(0, Math.min(1, t));
-      osc.frequency.setTargetAtTime(baseFreq + clamped * baseFreq * 2, ctx.currentTime, 0.05);
-      out.gain.setTargetAtTime(0.1 + clamped * maxVol, ctx.currentTime, 0.05);
-    },
-    dispose() {
-      if (osc) {
-        try {
-          osc.stop();
-        } catch {
-          /* already stopped */
-        }
-        osc.disconnect();
-        osc = null;
-      }
-      shaper.disconnect();
-      out.disconnect();
-    },
-  };
-}
-
-/** Brake squeal — high-frequency oscillator with LFO tremolo. */
-export function brakeSqueal(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { pitch?: number; volume?: number },
-) {
-  const pitch = options?.pitch ?? 2000;
-  const maxVol = options?.volume ?? 0.3;
-
-  const out = ctx.createGain();
-  out.gain.value = 0;
-  out.connect(dest);
-
-  let osc: OscillatorNode | null = null;
-  let lfo: OscillatorNode | null = null;
-  let lfoGain: GainNode | null = null;
-
-  return {
-    play() {
-      if (osc) return;
-      osc = ctx.createOscillator();
-      osc.type = 'sine';
-      osc.frequency.value = pitch;
-
-      // LFO for tremolo effect
-      lfo = ctx.createOscillator();
-      lfo.type = 'sine';
-      lfo.frequency.value = 30;
-      lfoGain = ctx.createGain();
-      lfoGain.gain.value = 0.3;
-      lfo.connect(lfoGain);
-      lfoGain.connect(out.gain);
-
-      osc.connect(out);
-      osc.start();
-      lfo.start();
-    },
-    stop() {
-      if (!osc) return;
-      out.gain.setTargetAtTime(0, ctx.currentTime, 0.02);
-      const refs = { osc, lfo, lfoGain };
-      osc = null;
-      lfo = null;
-      lfoGain = null;
-      setTimeout(() => {
-        try {
-          refs.osc.stop();
-        } catch {
-          /* already stopped */
-        }
-        refs.osc.disconnect();
-        try {
-          refs.lfo?.stop();
-        } catch {
-          /* already stopped */
-        }
-        refs.lfo?.disconnect();
-        refs.lfoGain?.disconnect();
-      }, 100);
-    },
-    /** Set brake intensity 0–1. */
-    setIntensity(i: number) {
-      out.gain.setTargetAtTime(Math.max(0, Math.min(1, i)) * maxVol, ctx.currentTime, 0.02);
-    },
-    dispose() {
-      if (osc) {
-        try {
-          osc.stop();
-        } catch {
-          /* already stopped */
-        }
-        osc.disconnect();
-      }
-      if (lfo) {
-        try {
-          lfo.stop();
-        } catch {
-          /* already stopped */
-        }
-        lfo.disconnect();
-      }
-      lfoGain?.disconnect();
-      osc = null;
-      lfo = null;
-      lfoGain = null;
-      out.disconnect();
-    },
-  };
-}
-
-/** Tire skid — filtered looping noise with intensity control. */
-export function tireSkid(ctx: AudioContext, dest: AudioNode, options?: { volume?: number }) {
-  const maxVol = options?.volume ?? 0.3;
-  const noiseBuffer = createNoiseBuffer(ctx, 2);
-
-  const out = ctx.createGain();
-  out.gain.value = 0;
-  out.connect(dest);
-
-  const filter = ctx.createBiquadFilter();
-  filter.type = 'bandpass';
-  filter.frequency.value = 800;
-  filter.Q.value = 1.5;
-  filter.connect(out);
-
-  let src: AudioBufferSourceNode | null = null;
-
-  return {
-    play() {
-      if (src) return;
-      src = ctx.createBufferSource();
-      src.buffer = noiseBuffer;
-      src.loop = true;
-      src.connect(filter);
-      src.start();
-    },
-    stop() {
-      if (!src) return;
-      out.gain.setTargetAtTime(0, ctx.currentTime, 0.02);
-      const ref = src;
-      src = null;
-      setTimeout(() => {
-        try {
-          ref.stop();
-        } catch {
-          /* already stopped */
-        }
-        ref.disconnect();
-      }, 100);
-    },
-    /** Set skid intensity 0–1. */
-    setIntensity(i: number) {
-      out.gain.setTargetAtTime(Math.max(0, Math.min(1, i)) * maxVol, ctx.currentTime, 0.02);
-    },
-    dispose() {
-      if (src) {
-        try {
-          src.stop();
-        } catch {
-          /* already stopped */
-        }
-        src.disconnect();
-      }
-      src = null;
-      filter.disconnect();
-      out.disconnect();
-    },
-  };
-}

package/src/audio/weapons.ts

@@ -1,152 +0,0 @@
-/**
- * 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/runtime/scene-ui-bridge.ts

@@ -1,86 +0,0 @@
-/**
- * Scene-UI render bridge (B1, widened design/24-scene-ui.md D3) — the injection
- * seam that keeps the engine React-free.
- *
- * The engine knows the scene carries a `ui` tree (data), but it does NOT know how to
- * render React. An editor-side module registers a renderer here (a thin wrapper over
- * the React `mountSceneUI`); the first-party scene adapter calls it at game-time to
- * mount the scene's UI into `host.ui` and disposes it on teardown. Fully decoupled:
- * the engine treats `sceneUI` and the handle as opaque. The optional third `services`
- * argument carries game-sourced data/components/events/projector (D2-D7) — still
- * opaque to the engine, still zero React import here.
- */
-
-/**
- * Structural match for `@vgai/scene-ui`'s `UIDataSource` — engine stays React-free
- * (this interface is duck-typed against the real one, not imported from it).
- */
-export interface SceneUIDataSourceLike {
-  get(path: string): unknown;
-  set(path: string, value: unknown): void;
-  subscribe(listener: () => void): () => void;
-  version(): number;
-}
-
-/**
- * Game-time services fed into a scene's UI mount (D2's "dynamic" layer). Every
- * field is optional: a renderer falls back to its own registration-time registry
- * (D2 merge rule) or built-in default when a field is absent. `components`/
- * `transforms`/`strings` stay `unknown`-valued here — they're React things the
- * scene-ui renderer casts to its real `UIComponentRegistry`/`TransformRegistry`/
- * `StringTables`.
- */
-export interface SceneUIGameServices {
-  /** Reactive game state the UI binds against (D4's `gameStateDataSource`, or a
-   *  game's own bus). Absent -> the renderer falls back to an empty static store. */
-  data?: SceneUIDataSourceLike;
-  /** `kind:"component"` leaf implementations, keyed by the name authored in the scene. */
-  components?: Record<string, unknown>;
-  /** Named binding transforms (`$bind.transform`). */
-  transforms?: Record<string, unknown>;
-  /** Localized string tables, keyed by locale then textKey. */
-  strings?: Record<string, Record<string, string>>;
-  locale?: string;
-  /** Routes a `kind:"button"` (etc.) `events.onClick` handler id to the game.
-   *  Absent -> a loud console.warn per event (D6 — no magic engine event bus). */
-  onEvent?: (handlerId: string, payload?: unknown) => void;
-  /** Projects an entity id to a screen-space point for world-tracked canvases
-   *  (D5). Returns null when the entity is unknown or behind the camera. */
-  worldProjector?: (entityId: string) => { x: number; y: number } | null;
-}
-
-export interface SceneUIHandle {
-  dispose(): void;
-  /** Re-render with new services without a remount (a late `setSceneUIServices`
-   *  call after the initial mount, D7). Optional — a renderer that can't update
-   *  in place may omit it; callers dispose+remount instead. */
-  update?(services: SceneUIGameServices): void;
-}
-
-/**
- * Renderer signature — `sceneUI` is the scene's `ui` array (opaque to the engine).
- * `services` is optional so existing 2-arg renderer functions keep working
- * unchanged (back-compat, D3/D5 §5).
- */
-export type SceneUIRenderer = (
-  container: HTMLElement,
-  sceneUI: unknown,
-  services?: SceneUIGameServices,
-) => SceneUIHandle;
-
-let _renderer: SceneUIRenderer | null = null;
-
-/** Register the React renderer (called once by the editor/runtime host). */
-export function setSceneUIRenderer(renderer: SceneUIRenderer | null): void {
-  _renderer = renderer;
-}
-
-/** Render a scene's UI into `container` if a renderer is registered, else no-op. */
-export function renderSceneUI(
-  container: HTMLElement,
-  sceneUI: unknown,
-  services?: SceneUIGameServices,
-): SceneUIHandle | null {
-  if (!_renderer || sceneUI == null) return null;
-  return _renderer(container, sceneUI, services);
-}

package/src/runtime/scene-ui-data.ts

@@ -1,119 +0,0 @@
-/**
- * gameStateDataSource (design/24-scene-ui.md D4) — the default scene-UI data
- * source: binds a scene's authored UI directly against live `GameComponent`
- * instance fields, with zero game-side wiring.
- *
- * Path grammar: `"<ComponentName>.<field.path>"` — the first segment resolves
- * through the SAME `ComponentRegistry` that resolves a scene's `components:`
- * entries (name -> class) to `game.queryByComponent(Class)[0]`, the rest walks
- * the live instance's own fields (components mutate `this` freely — the
- * state-bridge contract, `runtime/state-bridge.ts`). A text node bound to
- * `S1Session.wallet.money` just works.
- *
- * React-free, plain TS — `SceneUIDataSourceLike` is a structural (duck-typed)
- * match for `@vgai/scene-ui`'s real `UIDataSource`, so the engine never
- * imports the runtime that consumes this.
- */
-import type { GameComponent, GameComponentClass } from '../ecs/game-component';
-import type { ComponentRegistry } from '../scene/component-registry';
-import type { Game } from './game';
-import type { SceneUIDataSourceLike } from './scene-ui-bridge';
-
-function splitRoot(path: string): [root: string, rest: string] {
-  const dot = path.indexOf('.');
-  return dot === -1 ? [path, ''] : [path.slice(0, dot), path.slice(dot + 1)];
-}
-
-function readRest(obj: unknown, rest: string): unknown {
-  if (!rest) return obj;
-  let cur: unknown = obj;
-  for (const key of rest.split('.')) {
-    if (cur == null || typeof cur !== 'object') return undefined;
-    cur = (cur as Record<string, unknown>)[key];
-  }
-  return cur;
-}
-
-/**
- * Build the default `SceneUIDataSourceLike` over a game's live components.
- *
- * `subscribe`/`version` are driven by `game.state` (bumps once per completed
- * frame, after every world's phases — see `state-bridge.ts`) PLUS a local
- * bump on `set()`, so a two-way control's own write echoes immediately
- * instead of waiting for the next frame.
- */
-export function gameStateDataSource(
-  game: Game,
-  registry: ComponentRegistry,
-): SceneUIDataSourceLike {
-  let version = 0;
-  const listeners = new Set<() => void>();
-  // Warn-once-per-root-segment (D4/§9 review checklist): a scene author
-  // typo'ing a component name in a binding should be loud exactly once, not
-  // on every `get()` (a bound node re-reads its path every render).
-  const warnedRoots = new Set<string>();
-
-  const notify = (): void => {
-    for (const listener of listeners) listener();
-  };
-
-  /** Resolves a root segment to its live component instance, or undefined. */
-  const resolveInstance = (root: string): GameComponent | undefined => {
-    const Klass: GameComponentClass | undefined = registry[root];
-    if (!Klass) {
-      if (!warnedRoots.has(root)) {
-        warnedRoots.add(root);
-        console.warn(
-          `scene-ui: data binding root "${root}" is not a registered component name — ` +
-            'check the binding source against src/scripts/registry.ts.',
-        );
-      }
-      return undefined;
-    }
-    // Registered but zero live instances (e.g. not spawned yet this scene) is
-    // an ordinary, expected transient state — stays undefined, no warning.
-    return game.queryByComponent(Klass)[0];
-  };
-
-  // ONE subscription to the frame-versioned state bridge for this data
-  // source's whole lifetime, fanning out to however many external
-  // subscribers this scene-UI mount has.
-  game.state.subscribe(() => {
-    version++;
-    notify();
-  });
-
-  return {
-    get(path: string): unknown {
-      const [root, rest] = splitRoot(path);
-      const inst = resolveInstance(root);
-      return inst === undefined ? undefined : readRest(inst, rest);
-    },
-    set(path: string, value: unknown): void {
-      const [root, rest] = splitRoot(path);
-      const inst = resolveInstance(root);
-      if (inst === undefined || !rest) return;
-      const keys = rest.split('.');
-      let cur: Record<string, unknown> = inst as unknown as Record<string, unknown>;
-      for (let i = 0; i < keys.length - 1; i++) {
-        const key = keys[i] as string;
-        const next = cur[key];
-        if (next == null || typeof next !== 'object') return; // don't invent nested fields on a live instance
-        cur = next as Record<string, unknown>;
-      }
-      cur[keys[keys.length - 1] as string] = value;
-      // Two-way writes echo immediately, not on the next frame (D4).
-      version++;
-      notify();
-    },
-    subscribe(listener: () => void): () => void {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    version(): number {
-      return version;
-    },
-  };
-}