@vgai/engine 0.2.0

package/src/animation/blend-node.ts

@@ -0,0 +1,119 @@
+import type { BlendTreeDef } from './anim-graph-types';
+
+/**
+ * Evaluates a blend tree and returns weights for each child clip.
+ *
+ * 1D blend: interpolates between sorted blend points based on a single parameter.
+ *   Example: speed=3 with children at [walk:1, run:5] → weights [0.5, 0.5]
+ *
+ * 2D blend: uses two parameters (e.g., strafe locomotion). Weights are computed by
+ *   inverse-distance weighting (IDW): each child's weight is proportional to
+ *   1/distance from the (parameter, parameterY) sample point to that child's
+ *   (threshold, thresholdY) position, then normalized so all weights sum to 1.
+ *   A sample landing exactly on a child gives that child ~full weight. This is a
+ *   smooth approximation, not a Delaunay/barycentric blend (so non-adjacent
+ *   children still receive a small share); it is intentionally kept simple.
+ *
+ * Direct: each child has an explicit weight.
+ */
+export function evaluateBlendTree(
+  def: BlendTreeDef,
+  parameters: Map<string, number | boolean>,
+): { clip: string; weight: number }[] {
+  switch (def.type) {
+    case '1D':
+      return evaluate1D(def, parameters);
+    case '2D':
+      return evaluate2D(def, parameters);
+    case 'direct':
+      return evaluateDirect(def);
+    default:
+      return def.children.map((c) => ({ clip: c.clip, weight: 1 / def.children.length }));
+  }
+}
+
+function evaluate1D(
+  def: BlendTreeDef,
+  parameters: Map<string, number | boolean>,
+): { clip: string; weight: number }[] {
+  const paramValue = Number(parameters.get(def.parameter) ?? 0);
+  const children = [...def.children].sort((a, b) => a.threshold - b.threshold);
+  const results = children.map((c) => ({ clip: c.clip, weight: 0 }));
+
+  if (children.length === 0) return results;
+  if (children.length === 1) {
+    results[0]!.weight = 1;
+    return results;
+  }
+
+  // Below first threshold
+  if (paramValue <= children[0]!.threshold) {
+    results[0]!.weight = 1;
+    return results;
+  }
+
+  // Above last threshold
+  if (paramValue >= children[children.length - 1]!.threshold) {
+    results[results.length - 1]!.weight = 1;
+    return results;
+  }
+
+  // Between two thresholds — linear interpolation
+  for (let i = 0; i < children.length - 1; i++) {
+    const lo = children[i]!;
+    const hi = children[i + 1]!;
+    if (paramValue >= lo.threshold && paramValue <= hi.threshold) {
+      const range = hi.threshold - lo.threshold;
+      const t = range > 0 ? (paramValue - lo.threshold) / range : 0;
+      results[i]!.weight = 1 - t;
+      results[i + 1]!.weight = t;
+      return results;
+    }
+  }
+
+  return results;
+}
+
+function evaluate2D(
+  def: BlendTreeDef,
+  parameters: Map<string, number | boolean>,
+): { clip: string; weight: number }[] {
+  const px = Number(parameters.get(def.parameter) ?? 0);
+  const py = Number(parameters.get(def.parameterY ?? '') ?? 0);
+
+  // Inverse-distance weighting: weight each child by 1/distance to its 2D point,
+  // then normalize below so the returned weights sum to 1.
+  const children = def.children;
+  const results = children.map((c) => ({ clip: c.clip, weight: 0 }));
+
+  let totalInvDist = 0;
+  const invDists: number[] = [];
+
+  for (const child of children) {
+    const dx = px - child.threshold;
+    const dy = py - (child.thresholdY ?? 0);
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    const invDist = dist < 0.001 ? 1000 : 1 / dist;
+    invDists.push(invDist);
+    totalInvDist += invDist;
+  }
+
+  if (totalInvDist > 0) {
+    for (let i = 0; i < results.length; i++) {
+      results[i]!.weight = invDists[i]! / totalInvDist;
+    }
+  }
+
+  return results;
+}
+
+function evaluateDirect(def: BlendTreeDef): { clip: string; weight: number }[] {
+  const results = def.children.map((c) => ({ clip: c.clip, weight: c.weight ?? 0 }));
+  // Normalize so weights sum to exactly 1.0 — otherwise the leftover weight
+  // bleeds in the bind pose / T-pose (the actions add up to <1 or >1).
+  const total = results.reduce((sum, r) => sum + r.weight, 0);
+  if (total > 0) {
+    for (const r of results) r.weight /= total;
+  }
+  return results;
+}

package/src/animation/property-track.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 },
+        );
+      });
+    }
+  }
+}

package/src/animation/schema.ts

@@ -0,0 +1,204 @@
+// T4.6 — the `.animgraph.json` schema.
+//
+// Was TS-types-only (`anim-graph-types.ts`) until T4.6 authored this Zod
+// schema — see docs/BACKBONE-TASKS.md T4.6. `asset-loaders.ts`'s
+// `loadAnimGraphData` is this schema's runtime reader: it parses via this
+// schema before handing the data to `AnimGraph`/`LayerRuntime` (anim-graph.ts).
+//
+// Every field has a `.describe()` (repo policy — powers
+// `scripts/generate-schema.ts` and the T4.1/T4.6 schema-walk coverage test).
+// No runtime dependency beyond `zod`, matching the `scene/schema/` and
+// `manifest/schema.ts` precedent.
+//
+// T4.1 inheritance + one NEW finding (T4.6 audit, same pattern as `ui.locked`/
+// `ui.tags` being found beyond BACKBONE-TASKS.md's originally-named three):
+// `LayerRuntime`'s constructor (anim-graph.ts) only ever destructures
+// `layerDef.states`/`.transitions`/`.defaultState` — `blendMode` and
+// `boneMask` are confirmed dead (named in T4.1/docs/BACKBONE-TASKS.md), and
+// `weight` (an optional per-layer field, presumably meant for compositing
+// multiple layers) is ALSO never read anywhere — there is no cross-layer
+// weight combination in `AnimGraph.update()`, each layer's actions are
+// weighted independently. All three are REJECTED at parse, mirroring the
+// `scene/schema/ui.ts` dead-field mechanism (a `.superRefine` that throws
+// naming the field). `packages/editor/src/components/asset-viewers/
+// AnimGraphViewer.tsx` echoes `layer.blendMode` back verbatim in a read-only
+// raw-JSON asset preview — that is not a behavioral reader (it fetches raw
+// JSON directly, bypassing this schema, and merely echoes whatever value is
+// present with no downstream effect), so it does not change the verdict —
+// same distinction `schema-consumption-map.ts` draws for `ui.locked`.
+//
+// `layers[].name` is REQUIRED (not optional) and has no reader either — but
+// the T4.1 "throw when authored" mechanism only fits OPTIONAL fields (you
+// cannot reject a value that must always be present). It's structural
+// identity metadata (distinguishing layers when there is more than one, and
+// the natural key a future multi-layer inspector/editor would use), the same
+// role the file-format `version` field plays — so it is RESERVED, not dead,
+// matching the `2d.version`/`2d.surface` convention in
+// `schema-consumption-map.ts`.
+
+import { z } from 'zod';
+import type {
+  AnimGraphFile,
+  AnimLayer,
+  AnimParameter,
+  AnimState,
+  AnimTransition,
+  BlendChild,
+  BlendTreeDef,
+  TransitionCondition,
+} from './anim-graph-types';
+
+export const AnimParameterSchema: z.ZodType<AnimParameter> = z.object({
+  type: z
+    .enum(['float', 'int', 'bool', 'trigger'])
+    .describe('Parameter kind — drives which inspector widget/comparison semantics apply'),
+  default: z
+    .union([z.number(), z.boolean()])
+    .describe('Initial value (AnimGraph constructor seeds `this.parameters` with this)'),
+});
+
+// NOTE: the `as z.ZodType<X>` casts below (mirroring `UIRootSchema`'s pattern
+// in `scene/schema/ui.ts`) are needed because the hand-written TS interfaces
+// in `anim-graph-types.ts` declare optional fields as `foo?: T` rather than
+// `foo?: T | undefined` — under this repo's `exactOptionalPropertyTypes`,
+// Zod's `.optional()` output (`T | undefined`) isn't structurally assignable
+// to that without the cast, even though the two are semantically identical
+// (an omittable field). The runtime schema is unaffected; this is purely a
+// pure tsc-strictness accommodation.
+
+const TransitionConditionSchema: z.ZodType<TransitionCondition> = z.object({
+  param: z.string().describe('Parameter (or trigger) name this condition tests'),
+  op: z
+    .enum(['>', '<', '>=', '<=', '==', '!=', 'trigger'])
+    .describe('Comparison operator, or "trigger" to test a fired-trigger flag'),
+  value: z
+    .union([z.number(), z.boolean()])
+    .optional()
+    .describe('Value to compare against (unused when op is "trigger")'),
+}) as z.ZodType<TransitionCondition>;
+
+const AnimTransitionSchema: z.ZodType<AnimTransition> = z.object({
+  from: z.string().describe('Source state name, or "*" to match any current state'),
+  to: z.string().describe('Destination state name'),
+  conditions: z
+    .array(TransitionConditionSchema)
+    .optional()
+    .describe('All conditions must hold for this transition to fire'),
+  duration: z.number().describe('Crossfade duration in seconds'),
+  exitTime: z
+    .number()
+    .optional()
+    .describe(
+      'Normalized time (0-1) into the source state before this transition is eligible to fire',
+    ),
+}) as z.ZodType<AnimTransition>;
+
+const BlendChildSchema: z.ZodType<BlendChild> = z.object({
+  clip: z.string().describe('Animation clip name this child plays'),
+  threshold: z.number().describe('1D/2D blend position on the primary parameter axis'),
+  thresholdY: z.number().optional().describe('2D blend position on the secondary parameter axis'),
+  weight: z.number().optional().describe('Explicit weight for "direct" blend trees'),
+}) as z.ZodType<BlendChild>;
+
+const BlendTreeDefSchema: z.ZodType<BlendTreeDef> = z.object({
+  type: z.enum(['1D', '2D', 'direct']).describe('Blend tree evaluation mode'),
+  parameter: z.string().describe('Primary parameter driving the blend'),
+  parameterY: z.string().optional().describe('Secondary parameter driving a 2D blend'),
+  children: z.array(BlendChildSchema).describe('Clips (and their blend positions/weights)'),
+}) as z.ZodType<BlendTreeDef>;
+
+const AnimStateSchema: z.ZodType<AnimState> = z.object({
+  clip: z
+    .string()
+    .optional()
+    .describe('Single clip to play in this state (mutually exclusive with blendTree in practice)'),
+  loop: z.boolean().optional().describe('Loop the clip (default true)'),
+  speed: z.number().optional().describe('Playback speed multiplier (default 1)'),
+  blendTree: BlendTreeDefSchema.optional().describe(
+    'Blend tree to evaluate instead of a single clip',
+  ),
+}) as z.ZodType<AnimState>;
+
+const AnimLayerSchema: z.ZodType<AnimLayer> = z
+  .object({
+    name: z
+      .string()
+      .describe(
+        'Layer identifier (RESERVED — no reader today; structural identity metadata, same role ' +
+          'as the file-format `version` field. See the file doc comment.)',
+      ),
+    blendMode: z
+      .enum(['override', 'additive'])
+      .optional()
+      .describe(
+        'How this layer composites with others. REJECTED at parse (T4.1): declared but has no ' +
+          "runtime reader — LayerRuntime never reads it, each layer's actions are weighted " +
+          'independently. Authoring this field throws. Do not author.',
+      ),
+    weight: z
+      .number()
+      .optional()
+      .describe(
+        'Overall layer weight (for compositing multiple layers). REJECTED at parse (T4.6 audit, ' +
+          'new finding): declared but has no runtime reader — AnimGraph.update() never combines ' +
+          'per-layer weights. Authoring this field throws. Do not author.',
+      ),
+    boneMask: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Bone names this layer is restricted to. REJECTED at parse (T4.1): declared but has no ' +
+          'runtime reader anywhere. Authoring this field throws. Do not author.',
+      ),
+    defaultState: z.string().describe('State name entered on graph creation'),
+    states: z.record(z.string(), AnimStateSchema).describe('Named states this layer can be in'),
+    transitions: z.array(AnimTransitionSchema).describe('State-machine transitions for this layer'),
+  })
+  .superRefine((layer, ctx) => {
+    if (layer.blendMode !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          '`blendMode` is authored but not implemented — LayerRuntime (anim-graph.ts) never reads ' +
+          "it; each layer's actions are weighted independently with no cross-layer compositing " +
+          'mode. See T4.1/T4.6.',
+        path: ['blendMode'],
+      });
+    }
+    if (layer.weight !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          '`weight` is authored but not implemented — no reader combines per-layer weights ' +
+          '(AnimGraph.update() ticks each layer independently). See T4.6.',
+        path: ['weight'],
+      });
+    }
+    if (layer.boneMask !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          '`boneMask` is authored but not implemented — no reader restricts a layer to a bone ' +
+          'subset anywhere. See T4.1/T4.6.',
+        path: ['boneMask'],
+      });
+    }
+  }) as z.ZodType<AnimLayer>;
+
+/**
+ * The `.animgraph.json` file format (`asset-loaders.ts`'s `loadAnimGraphData`
+ * + `AnimGraph`'s constructor).
+ *
+ * `version` is RESERVED (no range-check reader exists yet for this format —
+ * same convention `2d.version`/`InputMapFile.version` use; see
+ * `schema-consumption-map.ts`).
+ */
+export const AnimGraphFileSchema: z.ZodType<AnimGraphFile> = z.object({
+  version: z.number().describe('Anim graph file format version (RESERVED — no range check yet)'),
+  parameters: z
+    .record(z.string(), AnimParameterSchema)
+    .describe('Named parameters and their defaults (AnimGraph constructor)'),
+  layers: z
+    .array(AnimLayerSchema)
+    .describe('Independent animation layers, each its own state machine'),
+}) as z.ZodType<AnimGraphFile>;

package/src/assets.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
+ *
+ * Inspired by Unity's Resources.Load / Godot's load():
+ *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
+ *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
+ *
+ * GLTF files (.glb/.gltf) resolve to GLTFResult.
+ * JSON files resolve to the parsed object (caller provides type via generic).
+ *
+ * Cache lives for the app lifetime — no dispose needed.
+ */
+
+import type * as THREE from 'three';
+import { gltfLoader, resolveUrl } from './loader';
+
+/** Result of loading a .glb/.gltf file. */
+export interface GLTFResult {
+  scene: THREE.Group;
+  animations: THREE.AnimationClip[];
+}
+
+export interface AssetCache {
+  /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
+  load<T = unknown>(url: string): Promise<T>;
+
+  /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
+  get<T = unknown>(url: string): T;
+}
+
+export function createAssetCache(): AssetCache {
+  const cache = new Map<string, Promise<unknown>>();
+  const resolved = new Map<string, unknown>();
+  // Use the shared, DRACO-wired GLTFLoader (A2 / CB2) — no second loader instance.
+  // This cache keeps the parsed source GLTFResult (load/get semantics for gameplay
+  // code); it does NOT clone. Callers that need disposal-safe clones use
+  // scene/asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
+
+  function load<T = unknown>(url: string): Promise<T> {
+    const existing = cache.get(url);
+    if (existing) return existing as Promise<T>;
+
+    let promise: Promise<unknown>;
+
+    if (url.endsWith('.glb') || url.endsWith('.gltf')) {
+      promise = new Promise<GLTFResult>((resolve, reject) => {
+        gltfLoader.load(
+          url,
+          (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
+          undefined,
+          reject,
+        );
+      });
+    } else if (url.endsWith('.json')) {
+      promise = fetch(resolveUrl(url)).then((r) => {
+        if (!r.ok) throw new Error(`Failed to fetch ${url}: ${r.status}`);
+        return r.json();
+      });
+    } else {
+      throw new Error(`AssetCache: unsupported file type for "${url}"`);
+    }
+
+    const tracked = promise.then((value) => {
+      resolved.set(url, value);
+      return value;
+    });
+
+    cache.set(url, tracked);
+    return tracked as Promise<T>;
+  }
+
+  function get<T = unknown>(url: string): T {
+    if (!resolved.has(url)) {
+      throw new Error(`AssetCache: "${url}" not loaded. Call load() first and await it.`);
+    }
+    return resolved.get(url) as T;
+  }
+
+  return { load, get };
+}