@vgai/engine 0.2.0 → 0.3.0

package/dist/manifest/schema.js

@@ -0,0 +1,302 @@
+// T3.1 slice 1 — the game manifest schema (`vgai.game.json`).
+//
+// This is the serialized form of the Game's world list
+// (docs/GAME-ROOT-DESIGN.md §1, D6) — see docs/GAME-MANIFEST-DESIGN.md §3 for
+// the adjudicated field list this file implements exactly. `load.ts` is this
+// schema's runtime reader (T4.1 policy): it parses via this schema, then
+// layers the cross-field checks and default resolution §3/§5 describe. Every
+// field below has a `.describe()` (repo policy — powers
+// `scripts/generate-schema.ts` and the T4.1 schema-walk coverage test).
+//
+// Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
+// (inferred type) convention used throughout `scene/schema/` — the design
+// doc's §3 sketch names the bare consts (`Tier`, `IngestStrategy`,
+// `WorldEntry`) without the `Schema` suffix; that sketch is explicitly a
+// "Zod sketch" the doc tells implementers to adapt to real code style
+// ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
+// schema consts here are suffixed and the bare names are reserved for the
+// inferred types, matching every other schema file in the repo.
+//
+// World `kind` intentionally mirrors `WorldKind` in
+// `packages/engine/src/runtime/game.ts` (`'threejs' | 'pixijs' | 'react'`)
+// by value, not by import — this schema module has no runtime dependency
+// beyond `zod` (kept parseable/bundlable in any context), matching the
+// `scene/schema/` precedent.
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Ingest capture strategy (world2d today; the general vocabulary D6/§4 names)
+// ---------------------------------------------------------------------------
+export const IngestStrategySchema = z.enum([
+    'shared', // game imports host-served ESM three — full in-realm capture
+    'deduped', // game source built by OUR pipeline, bundler dedupe — full capture
+    'iframe-reachable', // prebuilt bundle in iframe, three reachable — cross-realm capture
+    'opaque-embed', // prebuilt bundle, nothing reachable — host lifecycle only
+]);
+// ---------------------------------------------------------------------------
+// Capability tier — one ordered enum, declared per delivery context (§4)
+// ---------------------------------------------------------------------------
+export const TierSchema = z.enum([
+    'first-party', // vgai-native world: full editor, full loop control
+    'shared', // = IngestStrategy 'shared' rung
+    'deduped', // = IngestStrategy 'deduped' rung
+    'iframe-reachable', // = IngestStrategy 'iframe-reachable' rung
+    'opaque-embed', // = IngestStrategy 'opaque-embed' rung
+    'unsupported', // this world does not function in this delivery context
+]);
+// ---------------------------------------------------------------------------
+// World adapter identity — "make invalid states unrepresentable" (§2): a
+// world names its `kind` once, and its `adapter` is either resolved BY kind
+// (D6's default-*), a custom module, or an ingest strategy. There is no field
+// that lets a world spell out a kind/adapter combination that cannot exist.
+// ---------------------------------------------------------------------------
+export const WorldAdapterSchema = z
+    .union([
+    z.literal('default'),
+    z.object({
+        module: z
+            .string()
+            .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
+    }),
+    z.object({
+        ingest: z
+            .object({
+            strategy: IngestStrategySchema.describe('Capture mechanics rung this ingested world uses (§4) — also the world`s natural local capability tier'),
+            entryHtml: z
+                .string()
+                .optional()
+                .describe('Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, ' +
+                'docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through ' +
+                'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
+                'introspection), for both pixijs and threejs worlds. Legal but NOT wired to a ' +
+                'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
+                'instead, the wired reachable route).'),
+            assets: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)'),
+            domStubs: z
+                .array(z.string())
+                .optional()
+                .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
+            captureTimeoutMs: z
+                .number()
+                .optional()
+                .describe('Max time to wait for in-realm/cross-realm capture before failing loudly'),
+            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — the six
+            // iframe-reachable-multi mount fields (`ingest-iframe-2d.ts`'s
+            // `IframeReachableMultiOpts`), legal ONLY when `strategy` is
+            // 'iframe-reachable' (enforced by the `.superRefine` below).
+            bundleUrl: z
+                .string()
+                .optional()
+                .describe('Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
+                'mount route (iframe-reachable only), for BOTH pixijs (Track P, ' +
+                "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, " +
+                'docs/WAVE4-FTUE-HARDENING-DESIGN.md, ' +
+                "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
+                'PRECONDITION: the bundle must externalize its world`s own runtime as a bare, ' +
+                'un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` ' +
+                'does this for you) so it resolves through the iframe importmap to the HOST ' +
+                'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
+                'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
+                'entryHtml is required when strategy is iframe-reachable.'),
+            baseHref: z
+                .string()
+                .optional()
+                .describe("Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only)."),
+            assetBaseUrl: z
+                .string()
+                .optional()
+                .describe("Host-side basePath forced onto the trapped runtime's own asset resolution — " +
+                "pixi's `Assets.init` for a pixijs world, three's " +
+                '`DefaultLoadingManager.setURLModifier` for a threejs world (D-W1) — absolute, or ' +
+                "root-relative (resolved against the editor page's own origin at mount time, " +
+                'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
+                '(iframe-reachable only — a document.write iframe keeps the parent window.location).'),
+            extraDeps: z
+                .array(z.string())
+                .optional()
+                .describe("Bare specifiers of this world's externalized deps beyond its own runtime " +
+                "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
+                'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
+                'carries data, not code); an unregistered specifier falls back to the open ' +
+                "project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served " +
+                'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
+                '(iframe-reachable only).'),
+            pixiModuleUrl: z
+                .string()
+                .optional()
+                .describe('PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
+                "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
+                'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
+                'version skew) (iframe-reachable only). Declaring this on a `kind: "threejs"` ' +
+                'world is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
+                'not-supported error at resolve — three has no version-skew mount this wave (D-W7, ' +
+                'docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly ' +
+                'parked, no consumer exists).'),
+            bodyHtml: z
+                .string()
+                .optional()
+                .describe('HTML injected into the iframe body before the game script boots (e.g. a ' +
+                '`<div id="game-root">` the game expects to find) (iframe-reachable only).'),
+        })
+            .describe('Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
+            'own external folder)')
+            .superRefine((ingest, ctx) => {
+            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the six
+            // iframe-reachable-multi fields only make sense for the
+            // iframe-reachable-multi mount — reject them under any other
+            // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
+            const iframeOnlyFields = [
+                ['bundleUrl', ingest.bundleUrl !== undefined],
+                ['baseHref', ingest.baseHref !== undefined],
+                ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
+                ['extraDeps', ingest.extraDeps !== undefined],
+                ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
+                ['bodyHtml', ingest.bodyHtml !== undefined],
+            ];
+            if (ingest.strategy !== 'iframe-reachable') {
+                for (const [key, present] of iframeOnlyFields) {
+                    if (present) {
+                        ctx.addIssue({
+                            code: z.ZodIssueCode.custom,
+                            message: `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
+                                `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
+                                "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
+                                '(pixijs: ingest-iframe-2d.ts IframeReachableMultiOpts; threejs, D-W1: ' +
+                                'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
+                                'meaning under any other strategy.',
+                            path: [key],
+                        });
+                    }
+                }
+                return;
+            }
+            const hasBundleUrl = ingest.bundleUrl !== undefined;
+            const hasEntryHtml = ingest.entryHtml !== undefined;
+            if (hasBundleUrl === hasEntryHtml) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
+                        'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
+                        `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
+                    path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
+                });
+            }
+        }),
+    }),
+])
+    .describe("World adapter identity: 'default' (resolved by world kind to the built-in default " +
+    'adapter), a custom { module } adapter, or an { ingest } strategy for an unmodified ' +
+    'game (a repo-vendored game or your own external folder)');
+// ---------------------------------------------------------------------------
+// World entry
+// ---------------------------------------------------------------------------
+export const WorldEntrySchema = z.object({
+    id: z
+        .string()
+        .describe('Unique id for this world within the manifest (enforced-unique, D-V6 — GameManifestSchema.worlds rejects duplicates)'),
+    kind: z
+        .enum(['threejs', 'pixijs', 'react'])
+        .describe('World render substrate kind (mirrors runtime/game.ts WorldKind)'),
+    description: z
+        .string()
+        .optional()
+        .describe("Optional one-line description of this world's game/content (e.g. an ingested game's " +
+        "blurb — the manifest-native replacement for a registry entry's description field)"),
+    adapter: WorldAdapterSchema.default('default').describe("This world's adapter — see WorldAdapterSchema; defaults to 'default' (resolved by kind)"),
+    scene: z
+        .string()
+        .optional()
+        .describe('.vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)'),
+    entry: z
+        .string()
+        .optional()
+        .describe("Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)"),
+    zOrder: z
+        .number()
+        .int()
+        .default(0)
+        .describe('Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order'),
+    pausable: z
+        .boolean()
+        .default(true)
+        .describe('Whether play-mode pause/step applies to this world'),
+    loop: z
+        .enum(['gated', 'self-driven'])
+        .default('gated')
+        .describe('gated: host-driven loop (default). self-driven: this world drives its own loop ' +
+        '(the "composited, unsynchronized" tier) — an axis independent of capability tier'),
+    capabilities: z
+        .object({
+        local: TierSchema.optional().describe('Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)'),
+        hosted: TierSchema.optional().describe('Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)'),
+    })
+        .optional()
+        .describe("Per-delivery-context capability tier declarations (§4). Declaring above the adapter's " +
+        'ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.'),
+});
+// ---------------------------------------------------------------------------
+// Game manifest (vgai.game.json)
+// ---------------------------------------------------------------------------
+export const GameManifestSchema = z
+    .object({
+    manifestVersion: z.literal(1).describe('Manifest file format version (currently always 1)'),
+    name: z.string().describe('Game display name'),
+    version: z.string().describe("The game's own version (used for orphan detection)"),
+    engine: z
+        .object({
+        version: z
+            .string()
+            .describe('Exact @vgai/engine semver this game was scaffolded/last upgraded against — an ' +
+            'identity pin, not a range'),
+    })
+        .describe('Engine version pin'),
+    worlds: z
+        .array(WorldEntrySchema)
+        .min(1)
+        .superRefine((worlds, ctx) => {
+        // D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md §1G debt,
+        // docs/MULTI-WORLD-DESIGN.md §1G): world ids are described as unique
+        // above but that was describe-only at the SCHEMA level — only
+        // load.ts's loader-level cross-field check caught a collision, so
+        // any OTHER consumer of this schema (the generated JSON Schema,
+        // editor tooling) saw duplicate ids as legal. Enforced HERE instead,
+        // naming every colliding id (not just the first found) — overlay
+        // files are keyed by world id (`.vgai/overlays/<id>.json`), so a
+        // silently-permitted duplicate would have two worlds silently share
+        // one overlay.
+        const counts = new Map();
+        for (const world of worlds)
+            counts.set(world.id, (counts.get(world.id) ?? 0) + 1);
+        const duplicates = [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
+        if (duplicates.length === 0)
+            return;
+        const idsText = duplicates.map((id) => `"${id}"`).join(', ');
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: duplicates.length === 1
+                ? `Game manifest: duplicate world id ${idsText} — world ids must be unique across the manifest (enforced-unique).`
+                : `Game manifest: duplicate world ids: ${idsText} — world ids must be unique across the manifest (enforced-unique).`,
+        });
+    })
+        .describe("The Game's world list — this manifest is its serialized form"),
+    server: z
+        .object({
+        room: z.string().describe('Colyseus room name'),
+        module: z
+            .string()
+            .optional()
+            .describe('Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap'),
+    })
+        .optional()
+        .describe('Multiplayer server config (Colyseus), if this game registers a room'),
+    resolution: z
+        .object({
+        width: z.number().describe('Canvas width in pixels'),
+        height: z.number().describe('Canvas height in pixels'),
+    })
+        .optional()
+        .describe("Canvas resolution (subsumed from today's project.json)"),
+})
+    .describe('Game manifest (vgai.game.json) — the serialized form of the Game world list');

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
+ *    GameComponents/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
+ *    GameComponents/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/physics/trigger-dispatch.d.ts

@@ -0,0 +1,24 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameContext } from '../runtime/types';
+import type { CollisionHandler } from './collision-system';
+import type { PhysicsRegistry } from './physics-registry';
+/**
+ * Build a {@link CollisionHandler} that turns Rapier sensor overlaps into
+ * `onTriggerEnter` / `onTriggerExit` callbacks on the GameComponents of the two
+ * involved Object3Ds.
+ *
+ * Rapier collision events report collider *handles*; we resolve each to its
+ * Object3D via the physics registry's reverse index, then notify each side's
+ * components with the *other* Object3D. Only sensor-involved collisions dispatch
+ * triggers (a solid-vs-solid contact is a regular collision, not a trigger).
+ *
+ * Tracks currently-active trigger partners so that if one side is unregistered
+ * (despawned) from the physics registry before Rapier's own exit event is
+ * drained, the still-live side still gets its `onTriggerExit` (T1.12d) — see
+ * `physics.onRemove` below.
+ *
+ * Register with `collisions.onCollision(createTriggerDispatch(...))`.
+ */
+export declare function createTriggerDispatch(physics: PhysicsRegistry, components: ComponentManager, rapierWorld: RAPIER.World, ctx: GameContext): CollisionHandler;
+//# sourceMappingURL=trigger-dispatch.d.ts.map

package/dist/physics/trigger-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-dispatch.d.ts","sourceRoot":"","sources":["../../src/physics/trigger-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,CAAC,KAAK,EACzB,GAAG,EAAE,WAAW,GACf,gBAAgB,CAsDlB"}