@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/animation/anim-graph.ts

@@ -1,406 +0,0 @@
-import * as THREE from 'three';
-import type {
-  AnimGraphFile,
-  AnimLayer,
-  AnimState,
-  AnimTransition,
-  TransitionCondition,
-} from './anim-graph-types';
-import { evaluateBlendTree } from './blend-node';
-
-/**
- * Runtime animation graph for a single entity.
- *
- * This is the core custom code that Three.js doesn't provide.
- * Three.js AnimationMixer handles clip playback and crossfading.
- * This adds: state machines, parameter-driven transitions, blend trees.
- *
- * Weight management: all AnimationActions are pre-played at creation with
- * weight 0. Weights are set explicitly every frame — we never use Three.js's
- * fadeIn/fadeOut, which can cause total weight to dip below 1.0 and flash
- * the bind pose (T-pose).
- *
- * Usage:
- *   const graph = new AnimGraph(mixer, graphData, clips);
- *   graph.setParameter('speed', 5.0);
- *   graph.update(dt); // call each frame
- */
-export class AnimGraph {
-  private mixer: THREE.AnimationMixer;
-  private layers: LayerRuntime[] = [];
-  private parameters = new Map<string, number | boolean>();
-  private triggers = new Set<string>();
-
-  constructor(
-    mixer: THREE.AnimationMixer,
-    data: AnimGraphFile,
-    clips: Map<string, THREE.AnimationClip>,
-  ) {
-    this.mixer = mixer;
-
-    // Initialize parameters with defaults
-    for (const [name, param] of Object.entries(data.parameters)) {
-      this.parameters.set(name, param.default);
-    }
-
-    // Create runtime for each layer
-    for (const layerDef of data.layers) {
-      this.layers.push(new LayerRuntime(mixer, layerDef, clips));
-    }
-  }
-
-  /** The names of all declared parameters (for the AnimationAdapter to enumerate). */
-  parameterNames(): string[] {
-    return [...this.parameters.keys()];
-  }
-
-  /** Set a float/int/bool parameter */
-  setParameter(name: string, value: number | boolean) {
-    this.parameters.set(name, value);
-  }
-
-  /** Get a parameter value */
-  getParameter(name: string): number | boolean | undefined {
-    return this.parameters.get(name);
-  }
-
-  /** Fire a trigger (auto-resets after consumed by a transition) */
-  trigger(name: string) {
-    this.triggers.add(name);
-  }
-
-  /** Get the current state name for a layer (default: first layer) */
-  getCurrentState(layerIndex = 0): string {
-    return this.layers[layerIndex]?.currentState ?? '';
-  }
-
-  /** Update the animation graph. Call once per frame. */
-  update(dt: number) {
-    // Triggers persist until a transition actually consumes them — we do NOT
-    // clear every frame. A trigger fired mid-crossfade (when no transition can
-    // fire) survives until the layer is ready to act on it.
-    const consumed = new Set<string>();
-    for (const layer of this.layers) {
-      layer.update(dt, this.parameters, this.triggers, consumed);
-    }
-
-    // Clear only triggers that were consumed by a transition this frame.
-    for (const name of consumed) {
-      this.triggers.delete(name);
-    }
-
-    // Advance the mixer
-    this.mixer.update(dt);
-  }
-}
-
-/**
- * Runtime state for a single animation layer.
- */
-class LayerRuntime {
-  private mixer: THREE.AnimationMixer;
-  private states: Map<string, AnimState>;
-  private transitions: AnimTransition[];
-  private actionMap = new Map<string, THREE.AnimationAction>();
-  currentState: string;
-  private previousState = '';
-  private stateTime = 0;
-  private stateDuration = 0;
-  private transitioning = false;
-  private transitionElapsed = 0;
-  private transitionDuration = 0;
-
-  constructor(
-    mixer: THREE.AnimationMixer,
-    layerDef: AnimLayer,
-    clips: Map<string, THREE.AnimationClip>,
-  ) {
-    this.mixer = mixer;
-    this.states = new Map(Object.entries(layerDef.states));
-    this.transitions = layerDef.transitions;
-    this.currentState = layerDef.defaultState;
-
-    // Collect the (loop, speed) config each clip name is played with. A clip
-    // name is a key into a single shared THREE.AnimationAction (ensureAction
-    // dedupes by name), so two states — or a state and a blend-tree child —
-    // that reference the same clip with different loop/speed would silently
-    // let whichever state was processed first win, and the other's config
-    // would be dropped with no signal. Per-state clip config is deferred
-    // (no real need for it yet) — the correct behavior for now is a loud
-    // error at graph load, not silent last-write-wins.
-    const clipConfigs = new Map<string, { loop: boolean; speed: number; state: string }>();
-    for (const [stateName, state] of this.states) {
-      if (state.clip) {
-        this.registerClipConfig(
-          clipConfigs,
-          state.clip,
-          state.loop ?? true,
-          state.speed ?? 1,
-          stateName,
-        );
-      }
-      if (state.blendTree) {
-        for (const child of state.blendTree.children) {
-          this.registerClipConfig(clipConfigs, child.clip, true, 1, stateName);
-        }
-      }
-    }
-
-    // Create AnimationActions for all referenced clips.
-    // All actions are played immediately at weight 0 — they stay active in the
-    // mixer but contribute nothing visually until we raise their weight.
-    for (const [clipName, config] of clipConfigs) {
-      this.ensureAction(clipName, clips, config.loop, config.speed);
-    }
-
-    // Start default state
-    this.enterState(this.currentState, new Map());
-  }
-
-  /** Record a clip's (loop, speed) config, throwing if a prior state disagrees. */
-  private registerClipConfig(
-    configs: Map<string, { loop: boolean; speed: number; state: string }>,
-    clipName: string,
-    loop: boolean,
-    speed: number,
-    stateName: string,
-  ) {
-    const existing = configs.get(clipName);
-    if (existing && (existing.loop !== loop || existing.speed !== speed)) {
-      throw new Error(
-        `AnimGraph: clip "${clipName}" is configured inconsistently across states — ` +
-          `state "${existing.state}" uses loop=${existing.loop}/speed=${existing.speed}, ` +
-          `but state "${stateName}" uses loop=${loop}/speed=${speed}. ` +
-          `Per-state clip config is not supported: every state (and blend-tree child) that ` +
-          `plays a given clip must agree on its loop/speed.`,
-      );
-    }
-    if (!existing) configs.set(clipName, { loop, speed, state: stateName });
-  }
-
-  private ensureAction(
-    clipName: string,
-    clips: Map<string, THREE.AnimationClip>,
-    loop: boolean,
-    speed: number,
-  ) {
-    if (this.actionMap.has(clipName)) return;
-    const clip = clips.get(clipName);
-    if (!clip) return;
-
-    const action = this.mixer.clipAction(clip);
-    action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
-    action.clampWhenFinished = !loop;
-    action.timeScale = speed;
-    action.setEffectiveWeight(0);
-    action.play();
-    this.actionMap.set(clipName, action);
-  }
-
-  private enterState(stateName: string, parameters: Map<string, number | boolean>) {
-    const state = this.states.get(stateName);
-    if (!state) return;
-
-    this.currentState = stateName;
-    this.stateTime = 0;
-    this.transitioning = false;
-
-    // Zero all, then set the entering state to full weight
-    this.zeroAllWeights();
-
-    if (state.clip) {
-      const action = this.actionMap.get(state.clip);
-      if (action) {
-        action.reset();
-        action.setEffectiveWeight(1);
-        action.play();
-        this.stateDuration = action.getClip().duration;
-      }
-    }
-
-    if (state.blendTree) {
-      const weights = evaluateBlendTree(state.blendTree, parameters);
-      this.setWeights(weights, 1);
-      const heaviest = weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
-      const action = this.actionMap.get(heaviest.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    }
-  }
-
-  /** Zero all action weights. */
-  private zeroAllWeights() {
-    for (const action of this.actionMap.values()) {
-      action.setEffectiveWeight(0);
-    }
-  }
-
-  /** Set weights for a list of clip/weight pairs, multiplied by a scale factor. */
-  private setWeights(weights: { clip: string; weight: number }[], scale: number) {
-    for (const { clip, weight } of weights) {
-      const action = this.actionMap.get(clip);
-      if (action) {
-        action.setEffectiveWeight(weight * scale);
-      }
-    }
-  }
-
-  /** Get the weight list for a state (single clip at weight 1, or blend tree evaluated). */
-  private getStateWeights(
-    stateName: string,
-    parameters: Map<string, number | boolean>,
-  ): { clip: string; weight: number }[] {
-    const state = this.states.get(stateName);
-    if (!state) return [];
-    if (state.clip) return [{ clip: state.clip, weight: 1 }];
-    if (state.blendTree) return evaluateBlendTree(state.blendTree, parameters);
-    return [];
-  }
-
-  update(
-    dt: number,
-    parameters: Map<string, number | boolean>,
-    triggers: Set<string>,
-    consumed: Set<string>,
-  ) {
-    this.stateTime += dt;
-    const normalizedTime = this.stateDuration > 0 ? this.stateTime / this.stateDuration : 1;
-
-    // Zero all weights, then set them based on current (and previous) state.
-    // This guarantees total weight = 1.0 every frame — no bind-pose bleed.
-    this.zeroAllWeights();
-
-    if (this.transitioning) {
-      this.transitionElapsed += dt;
-      const alpha = Math.min(this.transitionElapsed / this.transitionDuration, 1);
-
-      // Crossfade: outgoing * (1 - alpha) + incoming * alpha — sums to exactly 1.0
-      this.setWeights(this.getStateWeights(this.previousState, parameters), 1 - alpha);
-      this.setWeights(this.getStateWeights(this.currentState, parameters), alpha);
-
-      if (alpha >= 1) {
-        this.transitioning = false;
-      }
-      return;
-    }
-
-    // Not transitioning — current state at full weight
-    this.setWeights(this.getStateWeights(this.currentState, parameters), 1);
-
-    // Check transitions
-    for (const transition of this.transitions) {
-      // Match: exact state or wildcard
-      if (transition.from !== '*' && transition.from !== this.currentState) continue;
-      // A wildcard transition must never re-enter the state we're already in —
-      // otherwise a wildcard whose condition stays true fires every single
-      // frame (performTransition resets the action to time 0 each time), so
-      // the state is "entered" over and over and its animation never advances
-      // past frame 0. An explicit from:X→to:X self-transition is a deliberate
-      // restart and is allowed to fire.
-      if (transition.from === '*' && transition.to === this.currentState) continue;
-
-      // Check exit time
-      if (transition.exitTime !== undefined && normalizedTime < transition.exitTime) continue;
-
-      // Check conditions
-      if (
-        transition.conditions &&
-        !this.checkConditions(transition.conditions, parameters, triggers)
-      ) {
-        continue;
-      }
-
-      // Transition! Mark any trigger conditions as consumed so the graph
-      // clears them after all layers have had a chance to react this frame.
-      if (transition.conditions) {
-        for (const cond of transition.conditions) {
-          if (cond.op === 'trigger') consumed.add(cond.param);
-        }
-      }
-      this.performTransition(transition, parameters);
-      return;
-    }
-  }
-
-  private checkConditions(
-    conditions: TransitionCondition[],
-    parameters: Map<string, number | boolean>,
-    triggers: Set<string>,
-  ): boolean {
-    for (const cond of conditions) {
-      if (cond.op === 'trigger') {
-        if (!triggers.has(cond.param)) return false;
-        continue;
-      }
-
-      const paramVal = parameters.get(cond.param);
-      if (paramVal === undefined) return false;
-
-      const a = Number(paramVal);
-      const b = Number(cond.value ?? 0);
-
-      switch (cond.op) {
-        case '>':
-          if (!(a > b)) return false;
-          break;
-        case '<':
-          if (!(a < b)) return false;
-          break;
-        case '>=':
-          if (!(a >= b)) return false;
-          break;
-        case '<=':
-          if (!(a <= b)) return false;
-          break;
-        case '==':
-          if (paramVal !== cond.value && a !== b) return false;
-          break;
-        case '!=':
-          if (paramVal === cond.value || a === b) return false;
-          break;
-      }
-    }
-    return true;
-  }
-
-  private performTransition(transition: AnimTransition, parameters: Map<string, number | boolean>) {
-    const toState = this.states.get(transition.to);
-    if (!toState) return;
-
-    this.previousState = this.currentState;
-    this.currentState = transition.to;
-    this.stateTime = 0;
-    this.transitioning = true;
-    this.transitionElapsed = 0;
-    this.transitionDuration = transition.duration;
-
-    // Reset incoming actions to time=0 so they start fresh.
-    // No fadeIn/fadeOut — weights are managed explicitly in update().
-    if (toState.clip) {
-      const action = this.actionMap.get(toState.clip);
-      if (action) {
-        action.reset();
-        action.play();
-      }
-    }
-    if (toState.blendTree) {
-      for (const child of toState.blendTree.children) {
-        const action = this.actionMap.get(child.clip);
-        if (action) {
-          action.reset();
-          action.play();
-        }
-      }
-    }
-
-    // Estimate state duration for exitTime calculations
-    if (toState.clip) {
-      const action = this.actionMap.get(toState.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    } else if (toState.blendTree) {
-      const weights = evaluateBlendTree(toState.blendTree, parameters);
-      const heaviest = weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
-      const action = this.actionMap.get(heaviest.clip);
-      this.stateDuration = action?.getClip().duration ?? 1;
-    }
-  }
-}

package/src/animation/anim-system.ts

@@ -1,28 +0,0 @@
-import type * as THREE from 'three';
-import type { AnimGraph } from './anim-graph';
-
-/**
- * Registry of active animation graphs, keyed by Object3D (the entity).
- *
- * AnimGraph wraps a THREE.AnimationMixer (a class instance), so it can't live in
- * a flat data store — we keep a simple Map<Object3D, AnimGraph> and update each
- * one every frame. Each runtime owns its own map (see createGameRuntime) so that
- * multiple concurrent runtimes never cross-contaminate each other's graphs.
- *
- * Usage:
- *   const animGraphs: AnimGraphMap = new Map();
- *   animGraphs.set(playerObject3D, new AnimGraph(mixer, data, clips));
- *   // In system runner:
- *   systems.add('animation', (dt) => animationSystem(animGraphs, dt));
- */
-export type AnimGraphMap = Map<THREE.Object3D, AnimGraph>;
-
-/**
- * Updates all active animation graphs.
- * Call this in the ANIMATION phase.
- */
-export function animationSystem(graphs: AnimGraphMap, dt: number) {
-  for (const graph of graphs.values()) {
-    graph.update(dt);
-  }
-}

package/src/animation/property-track.ts

@@ -1,178 +0,0 @@
-/**
- * F5 — Declarative property tracks (deterministic timeline).
- * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md
- *
- * A property track is DATA: a pure function of time (keyframes + named
- * easing), never behavior. `samplePropertyTrack` is the pure sampler (time →
- * value) the unit test asserts determinism against directly.
- * `PropertyTrackRunner` is a thin stateful shell that accumulates elapsed
- * time from the fixed-step `dt` already threaded through the scene tick (the
- * SAME `dt` the AnimationMixers get — see scene-loader.ts's `tickFns`) and
- * writes the sampled value onto the target Object3D property each frame. It
- * introduces NO new clock: a paused frame passes `dt = 0`, and time simply
- * does not advance — pause/timeScale are honored for free.
- *
- * Anything state-dependent ("move WHEN the player steps on it") stays a
- * GameComponent, which may start/stop/seek a track. This module only adds the
- * time→value data + a deterministic evaluator (G1 — data, not behavior).
- */
-import type * as THREE from 'three';
-import { log } from '../dev/logger';
-import type { PropertyTrack, PropertyTrackKeyframe } from '../scene/schema/animation';
-import type { UIEasing } from '../scene/schema/ui';
-
-// ---------------------------------------------------------------------------
-// Easing — mirrors packages/scene-ui/src/animation.ts's `ease` (same enum,
-// same semantics). NOT imported from there: scene-ui depends on the engine,
-// so importing it back here would be circular. A ~10-line parallel
-// implementation over the shared UIEasingSchema enum is the correct fix.
-// ---------------------------------------------------------------------------
-
-function ease(t: number, kind: UIEasing | undefined): number {
-  const x = Math.max(0, Math.min(1, t));
-  switch (kind) {
-    case 'ease-in':
-      return x * x;
-    case 'ease-out':
-      return 1 - (1 - x) * (1 - x);
-    case 'ease-in-out':
-      return x < 0.5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2;
-    case 'step':
-      return x < 1 ? 0 : 1; // hold the previous value until the next keyframe
-    default:
-      return x; // linear
-  }
-}
-
-/**
- * Sample a track at `time` seconds from track start. `time` is assumed
- * already wrapped/clamped by the caller (see {@link PropertyTrackRunner});
- * this function is a pure, side-effect-free keyframe interpolation and is
- * safe to call directly from tests.
- */
-export function samplePropertyTrack(track: PropertyTrack, time: number): number {
-  const kfs = track.keyframes;
-  if (kfs.length === 0) return 0;
-  const first = kfs[0] as PropertyTrackKeyframe;
-  if (time <= first.time) return first.value;
-  const last = kfs[kfs.length - 1] as PropertyTrackKeyframe;
-  if (time >= last.time) return last.value;
-  for (let i = 0; i < kfs.length - 1; i++) {
-    const k0 = kfs[i] as PropertyTrackKeyframe;
-    const k1 = kfs[i + 1] as PropertyTrackKeyframe;
-    if (time >= k0.time && time <= k1.time) {
-      const span = k1.time - k0.time || 1;
-      const raw = (time - k0.time) / span;
-      const t = ease(raw, k0.easing);
-      return k0.value + (k1.value - k0.value) * t;
-    }
-  }
-  return last.value;
-}
-
-/** Wrap/clamp elapsed time against a track's `duration`/`loop`. */
-function resolveTrackTime(track: PropertyTrack, elapsed: number): number {
-  if (track.duration <= 0) return elapsed;
-  if (track.loop) return elapsed % track.duration;
-  return Math.min(elapsed, track.duration);
-}
-
-type TargetSetter = (object3D: THREE.Object3D, value: number, warnOnce: () => void) => void;
-
-// Allowlisted target → setter. Keys are exactly PropertyTrackTargetSchema's
-// enum values — the allowlist IS the schema; no arbitrary path resolution.
-const TARGET_SETTERS: Record<string, TargetSetter> = {
-  'position.x': (o, v) => {
-    o.position.x = v;
-  },
-  'position.y': (o, v) => {
-    o.position.y = v;
-  },
-  'position.z': (o, v) => {
-    o.position.z = v;
-  },
-  'rotation.x': (o, v) => {
-    o.rotation.x = v;
-  },
-  'rotation.y': (o, v) => {
-    o.rotation.y = v;
-  },
-  'rotation.z': (o, v) => {
-    o.rotation.z = v;
-  },
-  'scale.x': (o, v) => {
-    o.scale.x = v;
-  },
-  'scale.y': (o, v) => {
-    o.scale.y = v;
-  },
-  'scale.z': (o, v) => {
-    o.scale.z = v;
-  },
-  'material.opacity': (o, v, warnOnce) => {
-    const mesh = o as THREE.Mesh;
-    const material = mesh.material as THREE.Material | THREE.Material[] | undefined;
-    if (!material) {
-      warnOnce();
-      return;
-    }
-    for (const mat of Array.isArray(material) ? material : [material]) {
-      mat.transparent = true;
-      mat.opacity = v;
-      mat.needsUpdate = true;
-    }
-  },
-  'light.intensity': (o, v, warnOnce) => {
-    const light = o as THREE.Light;
-    if (!light.isLight) {
-      warnOnce();
-      return;
-    }
-    light.intensity = v;
-  },
-};
-
-/**
- * Drives 1..N property tracks against a single Object3D. Constructed once per
- * entity that declares `animation.tracks`; `update(dt)` is registered in the
- * SAME tickFns list AnimationMixers use (scene-loader.ts), so it runs in the
- * animation phase on the same deterministic clock.
- */
-export class PropertyTrackRunner {
-  private readonly object3D: THREE.Object3D;
-  private readonly tracks: PropertyTrack[];
-  private elapsed: number[];
-  private readonly warned = new Set<string>();
-
-  constructor(object3D: THREE.Object3D, tracks: PropertyTrack[]) {
-    this.object3D = object3D;
-    this.tracks = tracks;
-    this.elapsed = tracks.map(() => 0);
-  }
-
-  /** Advance every track by `dt` seconds and write the sampled value. A paused
-   * frame (`dt = 0`) leaves every track's value unchanged — no wall-clock, no
-   * new clock; determinism follows directly from the caller's `dt`. */
-  update(dt: number): void {
-    for (let i = 0; i < this.tracks.length; i++) {
-      const track = this.tracks[i] as PropertyTrack;
-      this.elapsed[i] = (this.elapsed[i] ?? 0) + dt;
-      const time = resolveTrackTime(track, this.elapsed[i] ?? 0);
-      const value = samplePropertyTrack(track, time);
-      const setter = TARGET_SETTERS[track.target];
-      // Unreachable when `target` was parsed through PropertyTrackTargetSchema
-      // (the allowlist enum) — guarded defensively since TARGET_SETTERS is a
-      // separate table that must stay in sync with the schema.
-      if (!setter) continue;
-      setter(this.object3D, value, () => {
-        if (this.warned.has(track.target)) return;
-        this.warned.add(track.target);
-        log.scene.warn(
-          `Property track target "${track.target}" has no effect on entity "${this.object3D.name}" ` +
-            '(no material / not a light) — no-op.',
-          { entityName: this.object3D.name, target: track.target },
-        );
-      });
-    }
-  }
-}