@vgai/engine 0.5.5 → 0.5.7

package/dist/physics/collider-dimensions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared world-scale collider dimension math (T1.2).
+ *
+ * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
+ * shape is defined in absolute world units at creation time. Three.js meshes,
+ * by contrast, scale visually for free via the normal Object3D hierarchy. To
+ * keep the physical collider matching what's on screen, the LOADER must bake
+ * the entity's composed WORLD scale (self × every transformed ancestor — see
+ * T1.1's world-transform composition) into the collider's dimensions at
+ * creation time.
+ *
+ * This is the ONE place that does that math, so both the runtime loader
+ * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
+ * (gizmo-registry.ts) agree on exactly the same numbers — previously the
+ * editor gizmo only rendered the entity's own live Object3D scale (via normal
+ * Three.js parenting) while the Rapier body ignored scale entirely, so the
+ * two silently agreed by coincidence for uniform scale and disagreed for
+ * everything else.
+ *
+ * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
+ * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
+ * round collider's round axes throws a loud error naming the entity, rather
+ * than silently simulating (or rendering) the wrong shape.
+ */
+import type { ColliderDescriptor } from '../asset-formats/collider';
+export interface ColliderWorldDimensions {
+    /** cuboid only: per-axis half-extents, world scale applied. */
+    halfExtents?: [number, number, number];
+    /** ball/capsule only: radius, world scale applied (uniform axes required). */
+    radius?: number;
+    /** capsule only: half-height along the capsule's axis, world scale applied. */
+    halfHeight?: number;
+}
+/**
+ * Compute a collider's WORLD-space dimensions given the entity's composed
+ * world scale (self × ancestors, per-axis, in the entity's own local frame —
+ * X/Y/Z order matches `SceneEntity.transform.scale`).
+ *
+ * @param collider - the entity's authored (unscaled) collider definition.
+ * @param worldScale - composed world scale `[x, y, z]`.
+ * @param entityLabel - human-readable entity identifier, used only in thrown
+ *   error messages (loud-failure naming, never silently wrong).
+ * @throws if a ball/capsule collider's round cross-section axes have a
+ *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
+ */
+export declare function computeColliderWorldDimensions(collider: ColliderDescriptor, worldScale: readonly [number, number, number], entityLabel: string): ColliderWorldDimensions;
+/**
+ * Compute a collider's WORLD-scaled translation offset (sibling to
+ * {@link computeColliderWorldDimensions}, same input contract).
+ *
+ * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
+ * notion of a parent Object3D's scale — like dimensions, an authored `offset`
+ * (in the entity's own local units) must be scaled per-axis by the entity's
+ * composed world scale before being handed to Rapier, or the collider's center
+ * silently drifts away from its visual anchor point under any non-1 scale.
+ * Applies to every collider type (including trimesh, which is otherwise not
+ * handled by {@link computeColliderWorldDimensions}).
+ *
+ * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
+ * guard call sites already use.
+ */
+export declare function computeColliderWorldOffset(offset: readonly [number, number, number] | undefined, worldScale: readonly [number, number, number]): [number, number, number] | undefined;
+//# sourceMappingURL=collider-dimensions.d.ts.map

package/dist/physics/collider-dimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collider-dimensions.d.ts","sourceRoot":"","sources":["../../src/physics/collider-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAMpE,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,uBAAuB,CA4CzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACrD,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAItC"}

package/dist/physics/collider-dimensions.js

@@ -0,0 +1,98 @@
+/**
+ * Shared world-scale collider dimension math (T1.2).
+ *
+ * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
+ * shape is defined in absolute world units at creation time. Three.js meshes,
+ * by contrast, scale visually for free via the normal Object3D hierarchy. To
+ * keep the physical collider matching what's on screen, the LOADER must bake
+ * the entity's composed WORLD scale (self × every transformed ancestor — see
+ * T1.1's world-transform composition) into the collider's dimensions at
+ * creation time.
+ *
+ * This is the ONE place that does that math, so both the runtime loader
+ * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
+ * (gizmo-registry.ts) agree on exactly the same numbers — previously the
+ * editor gizmo only rendered the entity's own live Object3D scale (via normal
+ * Three.js parenting) while the Rapier body ignored scale entirely, so the
+ * two silently agreed by coincidence for uniform scale and disagreed for
+ * everything else.
+ *
+ * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
+ * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
+ * round collider's round axes throws a loud error naming the entity, rather
+ * than silently simulating (or rendering) the wrong shape.
+ */
+import { DEFAULTS } from '../defaults';
+/** Axes are considered "uniform enough" within this tolerance (float error only). */
+const UNIFORM_SCALE_EPSILON = 1e-4;
+/**
+ * Compute a collider's WORLD-space dimensions given the entity's composed
+ * world scale (self × ancestors, per-axis, in the entity's own local frame —
+ * X/Y/Z order matches `SceneEntity.transform.scale`).
+ *
+ * @param collider - the entity's authored (unscaled) collider definition.
+ * @param worldScale - composed world scale `[x, y, z]`.
+ * @param entityLabel - human-readable entity identifier, used only in thrown
+ *   error messages (loud-failure naming, never silently wrong).
+ * @throws if a ball/capsule collider's round cross-section axes have a
+ *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
+ */
+export function computeColliderWorldDimensions(collider, worldScale, entityLabel) {
+    const [sx, sy, sz] = worldScale;
+    switch (collider.type) {
+        case 'cuboid': {
+            const he = collider.halfExtents ?? DEFAULTS.collider.cuboid.halfExtents;
+            return { halfExtents: [he[0] * sx, he[1] * sy, he[2] * sz] };
+        }
+        case 'ball': {
+            if (Math.abs(sx - sy) > UNIFORM_SCALE_EPSILON ||
+                Math.abs(sy - sz) > UNIFORM_SCALE_EPSILON ||
+                Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
+                throw new Error(`Entity "${entityLabel}" has a "ball" collider under a non-uniform world scale ` +
+                    `[${sx}, ${sy}, ${sz}]. Rapier ball colliders are always perfect spheres — a ` +
+                    `non-uniform scale cannot be represented and would silently simulate the wrong ` +
+                    `shape. Use a uniform scale on this entity (and every transformed ancestor), or ` +
+                    `switch to a "cuboid" collider.`);
+            }
+            const radius = collider.radius ?? DEFAULTS.collider.ball.radius;
+            return { radius: radius * sx };
+        }
+        case 'capsule': {
+            // Rapier capsules run their half-height along the local Y axis, with a
+            // circular cross-section in the XZ plane — so only X/Z need to match.
+            if (Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
+                throw new Error(`Entity "${entityLabel}" has a "capsule" collider whose X/Z world scale differs ` +
+                    `(x=${sx}, z=${sz}). Rapier capsule colliders have a circular cross-section — a ` +
+                    `non-uniform X/Z scale cannot be represented and would silently simulate the ` +
+                    `wrong shape. Use a uniform X/Z scale on this entity (and every transformed ` +
+                    `ancestor), or switch to a "cuboid" collider.`);
+            }
+            const radius = collider.radius ?? DEFAULTS.collider.capsule.radius;
+            const halfHeight = collider.halfHeight ?? DEFAULTS.collider.capsule.halfHeight;
+            return { radius: radius * sx, halfHeight: halfHeight * sy };
+        }
+        default:
+            return {};
+    }
+}
+/**
+ * Compute a collider's WORLD-scaled translation offset (sibling to
+ * {@link computeColliderWorldDimensions}, same input contract).
+ *
+ * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
+ * notion of a parent Object3D's scale — like dimensions, an authored `offset`
+ * (in the entity's own local units) must be scaled per-axis by the entity's
+ * composed world scale before being handed to Rapier, or the collider's center
+ * silently drifts away from its visual anchor point under any non-1 scale.
+ * Applies to every collider type (including trimesh, which is otherwise not
+ * handled by {@link computeColliderWorldDimensions}).
+ *
+ * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
+ * guard call sites already use.
+ */
+export function computeColliderWorldOffset(offset, worldScale) {
+    if (!offset)
+        return undefined;
+    const [sx, sy, sz] = worldScale;
+    return [offset[0] * sx, offset[1] * sy, offset[2] * sz];
+}

package/dist/physics/collision-system.d.ts

@@ -0,0 +1,41 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+/**
+ * Collision event handler.
+ * Called with the two collider handles and whether contact started or stopped.
+ */
+export type CollisionHandler = (handleA: number, handleB: number, started: boolean) => void;
+/**
+ * Drains the Rapier event queue each frame and dispatches collision events.
+ *
+ * Usage:
+ *   const collisions = createCollisionSystem(rapierWorld, eventQueue);
+ *   collisions.onCollision((a, b, started) => { ... });
+ *   // In physics phase: rapierWorld.step(eventQueue);
+ *   // In postPhysics: collisions.drain();
+ */
+export declare function createCollisionSystem(rapierWorld: RAPIER.World, eventQueue: RAPIER.EventQueue): {
+    /** Register a collision handler. */
+    onCollision(handler: CollisionHandler): void;
+    /** Remove a collision handler. */
+    offCollision(handler: CollisionHandler): void;
+    /**
+     * Drain the event queue and dispatch collision events.
+     * Call this in POST_PHYSICS phase, after rapierWorld.step(eventQueue).
+     *
+     * Events are buffered first, then handlers run *after* the drain callback
+     * returns. This is required: a handler that calls back into the Rapier world
+     * (e.g. trigger dispatch resolving a collider, or an `onTriggerEnter` that
+     * spawns/removes a body) would otherwise re-enter Rapier while it is still
+     * borrowed by `drainCollisionEvents`, throwing "recursive use of an object
+     * ... unsafe aliasing in rust".
+     */
+    drain(): void;
+    /**
+     * Look up the rigid body handle that owns a collider handle.
+     * To resolve a collider directly to its Object3D entity, use the physics
+     * registry's `getByColliderHandle` reverse index instead.
+     */
+    getBodyHandleFromCollider(colliderHandle: number): number | undefined;
+};
+export type CollisionSystem = ReturnType<typeof createCollisionSystem>;
+//# sourceMappingURL=collision-system.d.ts.map

package/dist/physics/collision-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-system.d.ts","sourceRoot":"","sources":["../../src/physics/collision-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5F;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU;IAI1F,oCAAoC;yBACf,gBAAgB;IAIrC,kCAAkC;0BACZ,gBAAgB;IAKtC;;;;;;;;;;OAUG;;IAkBH;;;;OAIG;8CACuC,MAAM,GAAG,MAAM,GAAG,SAAS;EAQxE;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/physics/collision-system.js

@@ -0,0 +1,64 @@
+/**
+ * Drains the Rapier event queue each frame and dispatches collision events.
+ *
+ * Usage:
+ *   const collisions = createCollisionSystem(rapierWorld, eventQueue);
+ *   collisions.onCollision((a, b, started) => { ... });
+ *   // In physics phase: rapierWorld.step(eventQueue);
+ *   // In postPhysics: collisions.drain();
+ */
+export function createCollisionSystem(rapierWorld, eventQueue) {
+    const handlers = [];
+    return {
+        /** Register a collision handler. */
+        onCollision(handler) {
+            handlers.push(handler);
+        },
+        /** Remove a collision handler. */
+        offCollision(handler) {
+            const idx = handlers.indexOf(handler);
+            if (idx !== -1)
+                handlers.splice(idx, 1);
+        },
+        /**
+         * Drain the event queue and dispatch collision events.
+         * Call this in POST_PHYSICS phase, after rapierWorld.step(eventQueue).
+         *
+         * Events are buffered first, then handlers run *after* the drain callback
+         * returns. This is required: a handler that calls back into the Rapier world
+         * (e.g. trigger dispatch resolving a collider, or an `onTriggerEnter` that
+         * spawns/removes a body) would otherwise re-enter Rapier while it is still
+         * borrowed by `drainCollisionEvents`, throwing "recursive use of an object
+         * ... unsafe aliasing in rust".
+         */
+        drain() {
+            const events = [];
+            eventQueue.drainCollisionEvents((handle1, handle2, started) => {
+                events.push([handle1, handle2, started]);
+            });
+            eventQueue.drainContactForceEvents((_event) => {
+                // Contact force events available for advanced use.
+                // Game code can subscribe to these by extending this system.
+            });
+            for (const [handle1, handle2, started] of events) {
+                for (let i = 0; i < handlers.length; i++) {
+                    handlers[i](handle1, handle2, started);
+                }
+            }
+        },
+        /**
+         * Look up the rigid body handle that owns a collider handle.
+         * To resolve a collider directly to its Object3D entity, use the physics
+         * registry's `getByColliderHandle` reverse index instead.
+         */
+        getBodyHandleFromCollider(colliderHandle) {
+            const collider = rapierWorld.getCollider(colliderHandle);
+            if (!collider)
+                return undefined;
+            const body = collider.parent();
+            if (!body)
+                return undefined;
+            return body.handle;
+        },
+    };
+}

package/dist/physics/physics-registry.d.ts

@@ -0,0 +1,45 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type * as THREE from 'three';
+/** The Rapier handles owned by a single Object3D entity. */
+export interface PhysicsRefs {
+    body: RAPIER.RigidBody;
+    collider: RAPIER.Collider;
+}
+/**
+ * Maps Three.js Object3Ds to their Rapier bodies/colliders, and Rapier collider
+ * handles back to Object3Ds.
+ *
+ * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
+ *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
+ *    game code/editor to reach an entity's physics.
+ *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
+ *    (Rapier collision events report collider handles).
+ */
+export declare function createPhysicsRegistry(): {
+    /** Register an Object3D's body + collider, indexing both directions. */
+    add(object3D: THREE.Object3D, body: RAPIER.RigidBody, collider: RAPIER.Collider): void;
+    /** Get the physics refs for an Object3D, if any. */
+    get(object3D: THREE.Object3D): PhysicsRefs | undefined;
+    /** Resolve a Rapier collider handle to the Object3D that owns it. */
+    getByColliderHandle(handle: number): THREE.Object3D | undefined;
+    /**
+     * Register a callback fired synchronously, just before an entry is torn
+     * down, for every `remove()` call (both indexes are still intact at call
+     * time). Used by trigger-dispatch (T1.12d) to flush any pending
+     * `onTriggerExit` for a sensor overlap involving this object before the
+     * collider handle becomes unresolvable — otherwise an entity despawned
+     * between the physical exit and the next `collisions.drain()` silently
+     * drops the exit callback on its still-live overlap partner.
+     */
+    onRemove(listener: (object3D: THREE.Object3D, refs: PhysicsRefs) => void): void;
+    /** Remove an Object3D's entry from both indexes. */
+    remove(object3D: THREE.Object3D): void;
+    /** Iterate every (Object3D, refs) pair — used by the transform writer. */
+    entries(): IterableIterator<[THREE.Object3D, PhysicsRefs]>;
+    /** Number of registered physics entities. */
+    readonly size: number;
+    /** Clear both indexes (does not free Rapier bodies). */
+    clear(): void;
+};
+export type PhysicsRegistry = ReturnType<typeof createPhysicsRegistry>;
+//# sourceMappingURL=physics-registry.d.ts.map

package/dist/physics/physics-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-registry.d.ts","sourceRoot":"","sources":["../../src/physics/physics-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB;IAMjC,wEAAwE;kBAC1D,KAAK,CAAC,QAAQ,QAAQ,MAAM,CAAC,SAAS,YAAY,MAAM,CAAC,QAAQ,GAAG,IAAI;IAKtF,oDAAoD;kBACtC,KAAK,CAAC,QAAQ,GAAG,WAAW,GAAG,SAAS;IAItD,qEAAqE;gCACzC,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IAI/D;;;;;;;;OAQG;uBACgB,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAI/E,oDAAoD;qBACnC,KAAK,CAAC,QAAQ,GAAG,IAAI;IAStC,0EAA0E;eAC/D,gBAAgB,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAI1D,6CAA6C;mBACjC,MAAM;IAIlB,wDAAwD;aAC/C,IAAI;EAKhB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/physics/physics-registry.js

@@ -0,0 +1,65 @@
+/**
+ * Maps Three.js Object3Ds to their Rapier bodies/colliders, and Rapier collider
+ * handles back to Object3Ds.
+ *
+ * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
+ *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
+ *    game code/editor to reach an entity's physics.
+ *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
+ *    (Rapier collision events report collider handles).
+ */
+export function createPhysicsRegistry() {
+    const byObject = new Map();
+    const byColliderHandle = new Map();
+    const removeListeners = [];
+    return {
+        /** Register an Object3D's body + collider, indexing both directions. */
+        add(object3D, body, collider) {
+            byObject.set(object3D, { body, collider });
+            byColliderHandle.set(collider.handle, object3D);
+        },
+        /** Get the physics refs for an Object3D, if any. */
+        get(object3D) {
+            return byObject.get(object3D);
+        },
+        /** Resolve a Rapier collider handle to the Object3D that owns it. */
+        getByColliderHandle(handle) {
+            return byColliderHandle.get(handle);
+        },
+        /**
+         * Register a callback fired synchronously, just before an entry is torn
+         * down, for every `remove()` call (both indexes are still intact at call
+         * time). Used by trigger-dispatch (T1.12d) to flush any pending
+         * `onTriggerExit` for a sensor overlap involving this object before the
+         * collider handle becomes unresolvable — otherwise an entity despawned
+         * between the physical exit and the next `collisions.drain()` silently
+         * drops the exit callback on its still-live overlap partner.
+         */
+        onRemove(listener) {
+            removeListeners.push(listener);
+        },
+        /** Remove an Object3D's entry from both indexes. */
+        remove(object3D) {
+            const refs = byObject.get(object3D);
+            if (refs) {
+                for (const listener of removeListeners)
+                    listener(object3D, refs);
+                byColliderHandle.delete(refs.collider.handle);
+            }
+            byObject.delete(object3D);
+        },
+        /** Iterate every (Object3D, refs) pair — used by the transform writer. */
+        entries() {
+            return byObject.entries();
+        },
+        /** Number of registered physics entities. */
+        get size() {
+            return byObject.size;
+        },
+        /** Clear both indexes (does not free Rapier bodies). */
+        clear() {
+            byObject.clear();
+            byColliderHandle.clear();
+        },
+    };
+}

package/dist/physics/transform-writer.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from 'three';
+import type { PhysicsRegistry } from './physics-registry';
+/**
+ * Build the single postPhysics transform writer.
+ *
+ * Replaces the old three-step path (physicsSyncSystem → ECS Position/Rotation →
+ * vnode-manager.syncTransforms). Rapier always reports world-space transforms, so
+ * for objects parented under something other than the scene root we convert the
+ * body's world position/rotation into the parent's local space (P1.5) — the old
+ * vnode path wrote world transforms as local and mis-placed parented children.
+ *
+ * Scale is left untouched: Rapier carries no scale, so the Object3D keeps its
+ * authored local scale.
+ */
+export declare function createTransformWriter(physics: PhysicsRegistry, sceneRoot: THREE.Object3D): () => void;
+//# sourceMappingURL=transform-writer.d.ts.map

package/dist/physics/transform-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-writer.d.ts","sourceRoot":"","sources":["../../src/physics/transform-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM1D;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,SACpD,IAAI,CAoBxC"}

package/dist/physics/transform-writer.js

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+const _quat = new THREE.Quaternion();
+const _parentInv = new THREE.Matrix4();
+const _parentQuat = new THREE.Quaternion();
+/**
+ * Build the single postPhysics transform writer.
+ *
+ * Replaces the old three-step path (physicsSyncSystem → ECS Position/Rotation →
+ * vnode-manager.syncTransforms). Rapier always reports world-space transforms, so
+ * for objects parented under something other than the scene root we convert the
+ * body's world position/rotation into the parent's local space (P1.5) — the old
+ * vnode path wrote world transforms as local and mis-placed parented children.
+ *
+ * Scale is left untouched: Rapier carries no scale, so the Object3D keeps its
+ * authored local scale.
+ */
+export function createTransformWriter(physics, sceneRoot) {
+    return function writeTransforms() {
+        for (const [object3D, { body }] of physics.entries()) {
+            const t = body.translation();
+            const r = body.rotation();
+            const parent = object3D.parent;
+            if (parent && parent !== sceneRoot) {
+                // World → local: position through the inverse parent world matrix,
+                // rotation through the inverse parent world quaternion.
+                parent.updateWorldMatrix(true, false);
+                _parentInv.copy(parent.matrixWorld).invert();
+                object3D.position.set(t.x, t.y, t.z).applyMatrix4(_parentInv);
+                parent.getWorldQuaternion(_parentQuat).invert();
+                object3D.quaternion.copy(_parentQuat.multiply(_quat.set(r.x, r.y, r.z, r.w)));
+            }
+            else {
+                object3D.position.set(t.x, t.y, t.z);
+                object3D.quaternion.set(r.x, r.y, r.z, r.w);
+            }
+        }
+    };
+}

package/dist/pixi/authoring.d.ts

@@ -0,0 +1,93 @@
+import type { Container } from 'pixi.js';
+/**
+ * AuthoringAdapter-2D — the Pixi analog of the editor AuthoringAdapter /
+ * LiveThreeAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
+ * (no fabricated document — the anti-shim rule). Used by the editor to
+ * inspect + edit Pixi display-tree entities (first-party OR an ingested unmodified game),
+ * with stable structural-path ids so edits re-bind after the tree rebuilds.
+ */
+export interface EditorNode2D {
+    id: string;
+    label: string;
+    kind: 'sprite' | 'animatedsprite' | 'text' | 'container' | string;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface Transform2DValue {
+    position: [number, number];
+    rotation: number;
+    scale: [number, number];
+}
+export interface Property2D {
+    path: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'vec2' | 'color';
+    value: unknown;
+}
+/** An in-memory edit overlay keyed by structural-path id (2D). */
+export interface Override2D {
+    label?: string;
+    alpha?: number;
+    position?: [number, number];
+    rotation?: number;
+    scale?: [number, number];
+    tint?: number;
+    visible?: boolean;
+}
+export type Overlay2D = Record<string, Override2D>;
+export declare class AuthoringAdapter2D {
+    private readonly root;
+    private readonly byId;
+    private overlay;
+    private dirty;
+    constructor(root: Container, opts?: {
+        overlay?: Overlay2D;
+    });
+    /**
+     * Walk the live tree assigning deterministic structural-path ids.
+     *
+     * Separate from {@link refresh} because the two are wanted at different rates: the ids have to be
+     * current whenever the tree is READ (a world that mounts its content asynchronously — a
+     * translated port waiting on its resources, anything behind Suspense — commits real nodes after
+     * the adapter was handed its root, and an unindexed node is one the hierarchy cannot name), while
+     * re-applying the edit overlay is a WRITE and must happen only when something asked for it.
+     */
+    reindex(): {
+        count: number;
+        sprites: number;
+    };
+    /** {@link reindex}, then reapply every saved overlay edit to the live tree. */
+    refresh(): {
+        count: number;
+        sprites: number;
+    };
+    roots(): EditorNode2D[];
+    node(id: string): EditorNode2D | null;
+    displayObject(id: string): Container | null;
+    private toNode;
+    getTransform(id: string): Transform2DValue | null;
+    setTransform(id: string, t: Partial<Transform2DValue>): void;
+    properties(id: string): Property2D[];
+    set(id: string, path: string, value: unknown): void;
+    private applyOverride;
+    /**
+     * Re-apply a saved/external overlay onto the (already-walked) live tree, merging
+     * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
+     * and a later `refresh()` re-applies it again. Ids absent from the current tree
+     * are skipped (orphaned, not an error) — the 2D analog of
+     * `LiveThreeAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+     * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
+     * (re-apply a changed overlay file without a full remount).
+     */
+    applyOverlay(overlay: Overlay2D): {
+        applied: number;
+        orphaned: number;
+    };
+    isDirty(): boolean;
+    serializeOverlay(): Overlay2D;
+    /** Replace, rather than merge, overlay state after an exact history restore. */
+    replaceOverlay(overlay: Overlay2D): void;
+    /** Clear the dirty flag after a successful save (mirrors LiveThreeAuthoringAdapter). */
+    markClean(): void;
+}
+//# sourceMappingURL=authoring.d.ts.map

package/dist/pixi/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../../src/pixi/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAClE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AACD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAUnD,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,KAAK,CAAS;gBAGH,IAAI,EAAE,SAAS,EAChC,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,SAAS,CAAA;KAAO;IAMpC;;;;;;;;OAQG;IACH,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAoB7C,+EAA+E;IAC/E,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAM7C,KAAK,IAAI,YAAY,EAAE;IAIvB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAKrC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI3C,OAAO,CAAC,MAAM;IAYd,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAcjD,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAe5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAkBpC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAYnD,OAAO,CAAC,aAAa;IAYrB;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAevE,OAAO,IAAI,OAAO;IAGlB,gBAAgB,IAAI,SAAS;IAG7B,gFAAgF;IAChF,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;IAKxC,wFAAwF;IACxF,SAAS,IAAI,IAAI;CAGlB"}