@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,351 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-import * as THREE from 'three';
-import type { Actor, AnyActor, AnyStateMachine } from 'xstate';
-import type { createSystemRunner } from '../core/system-runner';
-import { type AnimationBoneMask } from './xstate-animation-meta';
-/** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
-export declare class AnimationBindingError extends Error {
-    readonly stateId?: string | undefined;
-    constructor(message: string, stateId?: string | undefined);
-}
-export interface XStateAnimationBindingOptions {
-    /** Select live numeric/boolean blend-tree parameters from actor context. */
-    selectParameters?: (context: unknown) => Record<string, number | boolean>;
-    /** Root whose named Bone/Object3D hierarchy is used by `boneMask`. Defaults to mixer root. */
-    root?: THREE.Object3D;
-    /** Entity that exposes this binding to editor/runtime inspection. Defaults to `root`. */
-    owner?: THREE.Object3D;
-    /**
-     * Engine runner used to register `tick` in the canonical animation phase.
-     * Pass `ctx.systems`; disposal removes the callback automatically. When
-     * omitted, the caller owns ticking (useful for standalone Three tests).
-     */
-    systems?: Pick<ReturnType<typeof createSystemRunner>, 'add' | 'remove'>;
-}
-export interface XStateAnimationLayerState {
-    readonly layer: string;
-    readonly stateId: string;
-    readonly clips: readonly string[];
-    readonly weight: number;
-    readonly blendMode: 'override' | 'additive';
-    readonly boneMask?: AnimationBoneMask;
-}
-export interface XStateAnimationBinding {
-    /** Advance native actions/mixer. Register this in the engine animation phase. */
-    tick: (dt: number) => void;
-    readonly actor: AnyActor;
-    /** Current native composition, useful to the editor and game diagnostics. */
-    getActiveLayers: () => readonly XStateAnimationLayerState[];
-    /** Unsubscribe, stop/uncache actions, and remove owner inspection data. Idempotent. */
-    dispose: () => void;
-}
-/** React/useSyncExternalStore-compatible lifecycle signal for live editor inspection. */
-export declare function subscribeXStateAnimationBindings(listener: () => void): () => void;
-/** Monotonic snapshot changed whenever a binding is attached or disposed. */
-export declare function getXStateAnimationBindingsVersion(): number;
-/**
- * Bind a native XState actor to native Three actions.
- *
- * One active animated state is allowed per named layer. Parallel XState
- * regions therefore compose lower-body locomotion, upper-body weapon states,
- * facial animation, and other independent layers without introducing a
- * second transition language. Bone masks clone/filter native clip tracks;
- * additive layers use `AnimationUtils.makeClipAdditive` and Three's additive
- * blend mode. Single unlayered machines retain the original clip/action path.
- */
-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

@@ -1 +0,0 @@
-{"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;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,EACL,KAAK,iBAAiB,EAOvB,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,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,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC1E,8FAA8F;IAC9F,IAAI,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACtB,yFAAyF;IACzF,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,SAAS,yBAAyB,EAAE,CAAC;IAC5D,uFAAuF;IACvF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAKD,yFAAyF;AACzF,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGjF;AAED,6EAA6E;AAC7E,wBAAgB,iCAAiC,IAAI,MAAM,CAE1D;AAqGD;;;;;;;;;GASG;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,CAsPxB"}