@vgai/engine 0.2.0 → 0.3.0

package/dist/animation/theatre-object-binding.js

@@ -0,0 +1,351 @@
+/**
+ * D3 — stable binding from a Theatre Sheet Object to a `THREE.Object3D`/
+ * camera (spec §10 D3, §5.3). This is the "thin integration code" the spec
+ * calls for: it reads a Theatre object's pull-based `.value` on every clock
+ * crossing and writes the (small, fixed) set of known sub-props straight
+ * onto the target's real Three.js properties. It is deliberately NOT a
+ * generic/arbitrary property-path evaluator — the only shapes understood are
+ * the ones declared below (`TransformProps`, `CameraLensProps`), matching
+ * "No arbitrary unsafe property-path evaluator is introduced" (D3 AC).
+ *
+ * Reads `sheetObject.value` rather than subscribing to Theatre's
+ * `onValuesChange` push channel — see `theatre-clock-binding.ts`'s module doc
+ * for why: `.value` is synchronously fresh immediately after
+ * `sequence.position` is set, while `onValuesChange` is batched on Theatre's
+ * own raf-driven ticker and is not delivered 1:1 with each synchronous clock
+ * seek (it may coalesce several writes into one notification, or — headless,
+ * no-raf — never fire at all).
+ *
+ * Object identity: a Theatre Sheet Object always carries both its stable,
+ * readable Theatre name (`sheetObject.address.objectKey`) and, since the
+ * caller supplies the bound `THREE.Object3D` directly, that object's own
+ * engine identity (`Object3D.uuid`/`.name`/`userData['entityId']`) — both are
+ * inspectable from the object references the binding already holds; nothing
+ * further to thread through.
+ *
+ * ## Remaining D3 channels: quaternion/material/light/post-processing/UI/Pixi
+ *
+ * The rest of the D3 AC's channel list (spec §10 D3: "Position,
+ * rotation/quaternion, scale, camera lens, material/light, post-processing,
+ * and selected UI properties have tested bindings") is implemented below,
+ * each as its own small, explicit, TYPED helper — never a generic
+ * property-path evaluator:
+ *
+ *  - `bindObject3DQuaternion` — `Object3D.quaternion`, authored as a plain
+ *    `{x,y,z,w}` compound (see `QuaternionProps`'s doc for the interpolation
+ *    caveat and why the binding always normalizes).
+ *  - `bindMaterialProperties` — `color`/`opacity`/`emissiveIntensity`/
+ *    `roughness`/`metalness` on a real `THREE.Material`, feature-detecting
+ *    which sub-props the concrete material subtype actually has.
+ *  - `bindLightProperties` — `intensity`/`color` on a real `THREE.Light`.
+ *  - `bindBloomEffect` / `bindVignetteEffect` — `intensity`/`opacity` and
+ *    `offset`/`darkness` on real `postprocessing` `BloomEffect`/
+ *    `VignetteEffect` instances (the SAME package `setup-renderer.ts` already
+ *    wires into the engine's composer — no new post-processing stack).
+ *  - `bindDomElementStyle` — `opacity`/`translateX`/`translateY` on a
+ *    DOM-style-writable target (`DomStyleTarget`, a narrow structural
+ *    interface a real `HTMLElement` satisfies with no adapter).
+ *  - `bindPixiContainerTransform` — `x`/`y`/`rotation`/`scaleX`/`scaleY`/
+ *    `alpha` on a real `PIXI.Container`/`PIXI.Sprite`.
+ *
+ * All of the above are proven against REAL target objects in
+ * `theatre-object-binding-d3.test.ts` — `BloomEffect`/`VignetteEffect`/
+ * `PIXI.Container`/`PIXI.Sprite` all construct and expose plain,
+ * synchronously-settable properties with no WebGL/canvas/renderer required,
+ * so nothing here is a mock of the underlying library. The one channel that
+ * genuinely cannot construct real headlessly in THIS repo's `environment:
+ * 'node'` vitest lane (`vitest.config.ts` — no DOM) is a real `HTMLElement`;
+ * `bindDomElementStyle` is typed against the narrow `DomStyleTarget`
+ * structural interface instead of full `HTMLElement`, and its test exercises
+ * a plain object literal shaped like one — the exact same binding code path
+ * a real `HTMLElement`/React-overlay ref runs through in a browser or a
+ * jsdom-backed test. Nothing here is deferred.
+ */
+/** Thrown when a binding is constructed with a missing/falsy target. */
+export class TheatreBindingError extends Error {
+    objectKey;
+    constructor(message, objectKey) {
+        super(message);
+        this.objectKey = objectKey;
+        this.name = 'TheatreBindingError';
+    }
+}
+/**
+ * Shared disposer wiring for every binding below (same one-shot-dispose
+ * shape `bindObject3DTransform`/`bindCameraLens` each inline above) — pulled
+ * into one helper only because six more binding functions follow, to avoid
+ * repeating the identical five lines six more times. Behavior is identical
+ * to the inline version: idempotent `dispose()`, no further writes after.
+ */
+function toBinding(handle) {
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+        },
+    };
+}
+/**
+ * Bind a Theatre Sheet Object's `position`/`rotation`/`scale` sub-props (any
+ * subset) to a `THREE.Object3D`. Whichever of the three keys are present on
+ * `sheetObject.value` are applied; missing keys are left untouched on the
+ * target.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindObject3DTransform(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindObject3DTransform] missing target Object3D for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (value.position) {
+            target.position.set(value.position.x, value.position.y, value.position.z);
+        }
+        if (value.rotation) {
+            target.rotation.set(value.rotation.x, value.rotation.y, value.rotation.z);
+        }
+        if (value.scale) {
+            target.scale.set(value.scale.x, value.scale.y, value.scale.z);
+        }
+    });
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+        },
+    };
+}
+/**
+ * Bind a Theatre Sheet Object's `fov`/`near`/`far` sub-props (any subset) to
+ * a `THREE.PerspectiveCamera`'s lens, calling `updateProjectionMatrix()`
+ * whenever any of them change.
+ *
+ * @throws {TheatreBindingError} if `camera` is null/undefined at bind time.
+ */
+export function bindCameraLens(clock, sheetObject, camera, options = {}) {
+    if (!camera) {
+        throw new TheatreBindingError(`[bindCameraLens] missing target PerspectiveCamera for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        let changed = false;
+        if (typeof value.fov === 'number' && camera.fov !== value.fov) {
+            camera.fov = value.fov;
+            changed = true;
+        }
+        if (typeof value.near === 'number' && camera.near !== value.near) {
+            camera.near = value.near;
+            changed = true;
+        }
+        if (typeof value.far === 'number' && camera.far !== value.far) {
+            camera.far = value.far;
+            changed = true;
+        }
+        if (changed)
+            camera.updateProjectionMatrix();
+    });
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+        },
+    };
+}
+/**
+ * Bind a Theatre Sheet Object's `quaternion` sub-prop to a `THREE.Object3D`'s
+ * `.quaternion`. See `QuaternionProps`'s doc for the authored shape and its
+ * interpolation caveat.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindObject3DQuaternion(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindObject3DQuaternion] missing target Object3D for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (value.quaternion) {
+            const { x, y, z, w } = value.quaternion;
+            target.quaternion.set(x, y, z, w);
+            target.quaternion.normalize();
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `color`/`opacity`/`emissiveIntensity`/
+ * `roughness`/`metalness` sub-props (any subset the target material
+ * supports) to a `THREE.Material`.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindMaterialProperties(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindMaterialProperties] missing target Material for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const material = target;
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (value.color && material.color) {
+            material.color.setRGB(value.color.r, value.color.g, value.color.b);
+        }
+        if (typeof value.opacity === 'number') {
+            material.opacity = value.opacity;
+        }
+        if (typeof value.emissiveIntensity === 'number' && 'emissiveIntensity' in material) {
+            material.emissiveIntensity = value.emissiveIntensity;
+        }
+        if (typeof value.roughness === 'number' && 'roughness' in material) {
+            material.roughness = value.roughness;
+        }
+        if (typeof value.metalness === 'number' && 'metalness' in material) {
+            material.metalness = value.metalness;
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `intensity`/`color` sub-props (any subset)
+ * to a `THREE.Light`.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindLightProperties(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindLightProperties] missing target Light for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (typeof value.intensity === 'number') {
+            target.intensity = value.intensity;
+        }
+        if (value.color) {
+            target.color.setRGB(value.color.r, value.color.g, value.color.b);
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `intensity`/`opacity` sub-props (any subset)
+ * to a real `postprocessing` `BloomEffect` — the SAME `postprocessing` npm
+ * package the engine's own composer pipeline already uses directly
+ * (`setup-renderer.ts`), not a new post-processing stack.
+ *
+ * @throws {TheatreBindingError} if `effect` is null/undefined at bind time.
+ */
+export function bindBloomEffect(clock, sheetObject, effect, options = {}) {
+    if (!effect) {
+        throw new TheatreBindingError(`[bindBloomEffect] missing target BloomEffect for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (typeof value.intensity === 'number') {
+            effect.intensity = value.intensity;
+        }
+        if (typeof value.opacity === 'number') {
+            effect.blendMode.opacity.value = value.opacity;
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `offset`/`darkness` sub-props (any subset) to
+ * a real `postprocessing` `VignetteEffect` — same package/no-wrapper note as
+ * `bindBloomEffect` above.
+ *
+ * @throws {TheatreBindingError} if `effect` is null/undefined at bind time.
+ */
+export function bindVignetteEffect(clock, sheetObject, effect, options = {}) {
+    if (!effect) {
+        throw new TheatreBindingError(`[bindVignetteEffect] missing target VignetteEffect for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (typeof value.offset === 'number') {
+            effect.offset = value.offset;
+        }
+        if (typeof value.darkness === 'number') {
+            effect.darkness = value.darkness;
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `opacity`/`translateX`/`translateY`
+ * sub-props (any subset) to a DOM-style-writable target's inline style. See
+ * `DomStyleTarget`'s doc for how this is proven without a real browser DOM.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindDomElementStyle(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindDomElementStyle] missing target DOM element for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    let lastTranslateX = 0;
+    let lastTranslateY = 0;
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (typeof value.opacity === 'number') {
+            target.style.opacity = String(value.opacity);
+        }
+        if (typeof value.translateX === 'number')
+            lastTranslateX = value.translateX;
+        if (typeof value.translateY === 'number')
+            lastTranslateY = value.translateY;
+        if (typeof value.translateX === 'number' || typeof value.translateY === 'number') {
+            target.style.transform = `translate(${lastTranslateX}px, ${lastTranslateY}px)`;
+        }
+    });
+    return toBinding(handle);
+}
+/**
+ * Bind a Theatre Sheet Object's `x`/`y`/`rotation`/`scaleX`/`scaleY`/`alpha`
+ * sub-props (any subset) to a real `PIXI.Container`/`PIXI.Sprite` (reusing
+ * the world2d stack's own `pixi.js` dependency — see this module's
+ * type-only `pixi.js` import above and its doc note on why the engine core
+ * never value-imports it). Plain `Container`/`Sprite` construction needs no
+ * canvas/WebGL context, so this is proven against a REAL Pixi object in
+ * `theatre-object-binding-d3.test.ts`, not a stand-in.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindPixiContainerTransform(clock, sheetObject, target, options = {}) {
+    if (!target) {
+        throw new TheatreBindingError(`[bindPixiContainerTransform] missing target PIXI.Container for Theatre object "${sheetObject.address.objectKey}"`, sheetObject.address.objectKey);
+    }
+    const phase = options.phase ?? 'preRender';
+    const handle = clock.subscribe(phase, () => {
+        const value = sheetObject.value;
+        if (typeof value.x === 'number')
+            target.x = value.x;
+        if (typeof value.y === 'number')
+            target.y = value.y;
+        if (typeof value.rotation === 'number')
+            target.rotation = value.rotation;
+        if (typeof value.scaleX === 'number')
+            target.scale.x = value.scaleX;
+        if (typeof value.scaleY === 'number')
+            target.scale.y = value.scaleY;
+        if (typeof value.alpha === 'number')
+            target.alpha = value.alpha;
+    });
+    return toBinding(handle);
+}

package/dist/animation/xstate-animation-binding.d.ts

@@ -0,0 +1,111 @@
+import * as THREE from 'three';
+import type { Actor, AnyActor, AnyStateMachine } from 'xstate';
+/**
+ * E2 — bind a native XState actor to a native `THREE.AnimationMixer` (spec
+ * §11 E2, §5.6, §3.3).
+ *
+ * A native XState actor drives native `THREE.AnimationAction`s: entering a
+ * state activates its `meta.animation` clip(s); leaving it deactivates them.
+ * There is no VGAI-specific trigger vocabulary — callers drive the machine
+ * with ordinary `actor.send(event)` (or the actor is externally owned and
+ * this binding merely observes it); XState alone decides which state is
+ * active.
+ *
+ * ## How enter/exit crossfades use NATIVE Three primitives (not a
+ * hand-rolled weight scheduler)
+ *
+ * The former `AnimGraph` runtime (removed by E5) pre-played every action at
+ * weight 0 and re-set every action's weight explicitly every frame,
+ * BYPASSING `AnimationAction.fadeIn`/`fadeOut`/`crossFadeTo` (to dodge
+ * multi-layer weight-summing bugs it hit historically).
+ * E2 deliberately does the opposite, per the spec AC ("use
+ * AnimationAction.crossFadeTo / fadeIn / fadeOut per the metadata"): the
+ * ENTER/EXIT edge of an XState state transition is represented by one real
+ * Three fade call, and `mixer.update(dt)` — the same call that advances clip
+ * time — is what advances the fade too. No parallel elapsed-time clock
+ * drives "is the fade done" for a plain (non-blend-tree) state; Three's own
+ * scheduler is authoritative end to end.
+ *
+ * A **blend-tree** state is, at the instant of entry, represented by ONE
+ * clip — its heaviest-weighted child at that instant (the same "representative"
+ * duration/action heuristic the removed `AnimGraph.LayerRuntime` used) — which
+ * receives the native crossFadeTo/fadeIn. Sibling
+ * children stay silent (weight 0) until the crossfade window elapses, at
+ * which point the FULL live blend-tree distribution (`evaluateBlendTree`,
+ * reused verbatim from `blend-node.ts` — no reimplementation) takes over via
+ * `setEffectiveWeight` every tick, recomputed from the actor's live
+ * context/selector value. This is a documented simplification (Three's
+ * `crossFadeTo` is strictly 1-to-1; there is no native N-ary blend-tree
+ * crossfade), the same spirit as `blend-node.ts`'s own documented 2D
+ * "smooth approximation, not Delaunay/barycentric" caveat. The crossfade
+ * window itself is tracked as a small elapsed-seconds counter, decremented
+ * by the SAME `dt` passed to `mixer.update(dt)` — it never drifts from
+ * Three's own fade schedule because both are driven by the identical `dt`
+ * stream, so it is bookkeeping for "when to hand off from native fade to
+ * live blend", not a second competing scheduler.
+ *
+ * ## Mixer advancement uses the canonical engine ANIMATION phase
+ *
+ * `tick(dt)` has exactly the engine's `SystemFn` shape (`core/types.ts`:
+ * `(dt: number) => void`) — a caller registers this binding on the engine's
+ * one real fixed-step scheduler at the ANIMATION phase, exactly as any other
+ * per-frame system: `ctx.systems.add(SystemPhase.ANIMATION, binding.tick)`
+ * (or, when the binding is owned by a `GameComponent` that also owns the
+ * actor — the §5.6 pattern the examples use — the component simply calls
+ * `binding.tick(dt)` from its own `update(dt)`). Either way mixer advancement
+ * rides that one scheduler; no second scheduler is invented here. (This is
+ * the same ANIMATION-phase slot the removed `AnimGraph` runtime's global
+ * `animationSystem` occupied before E5 — see
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5. The D1
+ * `AnimationClock` — `animation-clock.ts` — is a distinct, sibling concern: a
+ * per-cinematic/Theatre-timeline seek clock for scrubbing/export, not wired
+ * into ordinary gameplay ticking today.)
+ */
+/** Thrown for a binding-time problem: a missing clip, or a target-less bind. */
+export declare class AnimationBindingError extends Error {
+    readonly stateId?: string | undefined;
+    constructor(message: string, stateId?: string | undefined);
+}
+export interface XStateAnimationBindingOptions {
+    /**
+     * Reads the blend-tree parameter map from the actor's live context.
+     * Defaults to treating `context` itself as `Record<string, number | boolean>`
+     * (matches the §5.6 example: `context: { speed: number; grounded: boolean }`
+     * fed straight into a blend tree keyed by `parameter: 'speed'`). Override
+     * when a machine's blend-tree parameters need deriving from context via a
+     * selector rather than reading top-level fields directly.
+     */
+    selectParameters?: (context: unknown) => Record<string, number | boolean>;
+}
+export interface XStateAnimationBinding {
+    /**
+     * Advance the bound mixer (and any live blend-tree weights) by `dt`
+     * seconds. Register on the engine's `'animation'` phase — see the module
+     * doc above. A no-op after `dispose()`.
+     */
+    tick: (dt: number) => void;
+    /** The bound actor, for convenience (`binding.actor.send({...})`). */
+    readonly actor: AnyActor;
+    /**
+     * Stops observing the actor (does NOT stop the actor itself — the actor's
+     * lifecycle is the caller's, this binding only ever subscribed to it) and
+     * uncaches every `AnimationAction` this binding created from the mixer, so
+     * a dispose+rebind cycle (e.g. hot-reload, despawn/respawn) does not leak
+     * mixer-cached actions. Idempotent; `tick()` is a no-op after this.
+     */
+    dispose: () => void;
+}
+/**
+ * Bind an XState actor to a `THREE.AnimationMixer`.
+ *
+ * Validates EVERY state's `meta.animation` (via `collectMachineAnimationMeta`,
+ * E1) and resolves every referenced clip name against `clips` up front, at
+ * bind time — before the actor enters any of those states — so an agent
+ * authoring a machine with a typo'd clip name gets an actionable error
+ * immediately, not only once gameplay happens to reach that state.
+ *
+ * @throws {AnimationBindingError} if a state's meta references a clip name
+ *   not present in `clips`, naming both the state and the clip.
+ */
+export declare function bindXStateAnimation(actor: Actor<AnyStateMachine>, mixer: THREE.AnimationMixer, clips: Map<string, THREE.AnimationClip>, options?: XStateAnimationBindingOptions): XStateAnimationBinding;
+//# sourceMappingURL=xstate-animation-binding.d.ts.map

package/dist/animation/xstate-animation-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xstate-animation-binding.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAY/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,gFAAgF;AAChF,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM;gBADzB,OAAO,EAAE,MAAM,EACN,OAAO,CAAC,EAAE,MAAM,YAAA;CAK5B;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAgCD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,EAC7B,KAAK,EAAE,KAAK,CAAC,cAAc,EAC3B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,EACvC,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CA8MxB"}