@vworlds/vecs-physics 1.0.25 → 1.0.27

package/adapter/{state.d.ts → engine.d.ts}

@@ -1,5 +1,6 @@
-import { ArrayMap, type EID, type Entity, type World } from "@vworlds/vecs";
+import { ArrayMap, type EID, type World } from "@vworlds/vecs";
 import { type WarnSink, WarnDedupe } from "../util/warn.js";
+import { type PhysicsQueries } from "./queries.js";
 import { type Box2DModule } from "./runtime.js";
 export type EntityId = EID;
 export type b2WorldId = ReturnType<Box2DModule["b2CreateWorld"]>;
@@ -7,6 +8,11 @@ export type b2BodyId = ReturnType<Box2DModule["b2CreateBody"]>;
 export type b2ShapeId = ReturnType<Box2DModule["b2CreateCircleShape"]>;
 export type b2ChainId = ReturnType<Box2DModule["b2CreateChain"]>;
 export type b2Vec2 = ReturnType<Box2DModule["b2Body_GetPosition"]>;
+export type b2QueryFilter = Parameters<Box2DModule["b2World_OverlapAABB"]>[2];
+export type b2AABB = Parameters<Box2DModule["b2World_OverlapAABB"]>[1];
+/** The transient result object passed to a `b2World_CastRay` collector callback
+ * (the binding types the callback parameter as `any`). */
+export type b2RayCallbackResult = InstanceType<Box2DModule["b2RayCallbackResult"]>;
 /** Fully-resolved engine configuration: every `PhysicsOptions` field with its
  * default applied. Built by `PhysicsModule`; the source of truth for tunables
  * the engine reads at runtime. */
@@ -33,10 +39,10 @@ export interface ResolvedPhysicsOptions {
 export declare class PhysicsSystemTag {
 }
 export declare function registerInternalComponents(world: World): void;
-export declare function attachPhysics(world: World, state: PhysicsState): void;
-export declare function getPhysics(world: World): PhysicsState;
-export declare function hasPhysics(world: World): boolean;
-export declare class PhysicsState {
+export declare function attachPhysicsEngine(world: World, engine: PhysicsEngine): void;
+export declare function getPhysicsEngine(world: World): PhysicsEngine;
+export declare function hasPhysicsEngine(world: World): boolean;
+export declare class PhysicsEngine {
     worldId: b2WorldId;
     readonly box2d: Box2DModule;
     readonly gravityX: number;
@@ -53,12 +59,8 @@ export declare class PhysicsState {
     readonly maximumLinearSpeed: number;
     readonly enableSleep: boolean;
     readonly enableContinuous: boolean;
-    readonly bodyByEntityWasm: Map<number, import("node_modules/box2d3-wasm/build/dist/es/deluxe/Box2D.deluxe.js").b2BodyId>;
     readonly entityByBodyIndex: ArrayMap<number>;
-    readonly shapeByEntityWasm: Map<number, import("node_modules/box2d3-wasm/build/dist/es/deluxe/Box2D.deluxe.js").b2ShapeId>;
     readonly entityByShapeIndex: ArrayMap<number>;
-    readonly chainByEntity: Map<number, import("node_modules/box2d3-wasm/build/dist/es/deluxe/Box2D.deluxe.js").b2ChainId>;
-    readonly shapeEntityByEid: Map<number, Entity>;
     readonly dirtyMassBodies: Set<number>;
     readonly prevTouchedContact: Set<number>;
     readonly prevTouchedSensor: Set<number>;
@@ -73,6 +75,7 @@ export declare class PhysicsState {
         value: number;
         wake: boolean;
     }>;
-    readonly scratchVec2: b2Vec2;
+    queries?: PhysicsQueries;
+    constructor();
     constructor(box2d: Box2DModule, options: ResolvedPhysicsOptions, warnSink?: WarnSink);
 }

package/adapter/{state.js → engine.js}

@@ -8,48 +8,41 @@ import { WarnDedupe } from "../util/warn.js";
 export class PhysicsSystemTag {
 }
 export function registerInternalComponents(world) {
-    world.component(PhysicsRoot);
+    world.component(PhysicsEngine);
     world.component(PhysicsSystemTag);
 }
-export function attachPhysics(world, state) {
-    world.component(PhysicsRoot).add(Singleton);
-    world.set(PhysicsRoot, { state });
+export function attachPhysicsEngine(world, engine) {
+    world.component(PhysicsEngine).add(Singleton);
+    world.component(PhysicsEngine).attach(PhysicsEngine, engine);
 }
-export function getPhysics(world) {
-    const root = world.get(PhysicsRoot);
-    if (!root) {
-        throw new Error("world.module(PhysicsModule) must be called before reading physics state");
+export function getPhysicsEngine(world) {
+    const engine = world.get(PhysicsEngine);
+    if (!engine) {
+        throw new Error("world.module(PhysicsModule) must be called before reading physics engine");
     }
-    return root.state;
+    return engine;
 }
-export function hasPhysics(world) {
-    if (!world._classRegistry.has(PhysicsRoot)) {
+export function hasPhysicsEngine(world) {
+    if (!world._classRegistry.has(PhysicsEngine)) {
         return false;
     }
-    const root = world.get(PhysicsRoot);
-    return root?.state !== undefined;
+    return world.get(PhysicsEngine) !== undefined;
 }
-export class PhysicsState {
+export class PhysicsEngine {
     constructor(box2d, options, warnSink) {
-        // Entity → WASM body/shape IDs plus index-keyed reverse ArrayMaps.
+        // Forward handles live on components: Body._bodyId, SingleShape._shapeId, and Chain._chainId.
+        // Index-keyed reverse ArrayMaps resolve Box2D event IDs back to entities.
         // Emscripten returns fresh wrapper objects for b2*Id fields on events, so
         // Map<b2*Id, EntityId> misses by object identity. Public index1 slot 0 is
         // unused/null-aligned by Box2D, so ArrayMap slot 0 stays empty too. We do not
         // check id generations in hot lookups: correctness comes from clearing each
         // slot on Box2D destruction before Box2D can reuse that index1.
-        this.bodyByEntityWasm = new Map();
         this.entityByBodyIndex = new ArrayMap();
-        this.shapeByEntityWasm = new Map();
         this.entityByShapeIndex = new ArrayMap();
-        this.chainByEntity = new Map();
-        // Shape entity object map: shape eid → Entity object.
-        // Used by events.ts to resolve entities for teardown events even after
-        // the entity has been removed from the world lookup table.
-        this.shapeEntityByEid = new Map();
         // Bodies whose mass needs recomputing this step (populated by shape lifecycle).
         this.dirtyMassBodies = new Set();
         // Per-step event tracking sets for PhysicsEvents (M7-8 should-fix: moved from
-        // closure-local to state so they survive future pause/resume cycles).
+        // closure-local to engine so they survive future pause/resume cycles).
         // Populated by PhysicsEvents at the end of each step; persist into the next
         // step to detect which entities stopped receiving events.
         this.prevTouchedContact = new Set();
@@ -60,10 +53,14 @@ export class PhysicsState {
         // Cleared by PhysicsImpulseZero at the end of each post phase.
         this.impulseEntitiesThisStep = new Set();
         // Pending impulses remain wrapper-keyed by invariant: hooks resolve bodyId
-        // from bodyByEntityWasm, then get/set with that same stored wrapper, and the
-        // pre-step drain iterates stored keys instead of looking up event wrappers.
+        // off the `Body` component via resolveBodyId, then get/set with that same
+        // stored wrapper, and the pre-step drain iterates stored keys instead of
+        // looking up event wrappers.
         this.pendingLinearImpulse = new Map();
         this.pendingAngularImpulse = new Map();
+        if (box2d === undefined || options === undefined) {
+            return;
+        }
         this.box2d = box2d;
         this.gravityX = options.gravityX;
         this.gravityY = options.gravityY;
@@ -79,10 +76,6 @@ export class PhysicsState {
         this.maximumLinearSpeed = options.maximumLinearSpeed;
         this.enableSleep = options.enableSleep;
         this.enableContinuous = options.enableContinuous;
-        this.scratchVec2 = new box2d.b2Vec2();
     }
 }
-// Internal singleton state holder. Never exported from the package public API.
-class PhysicsRoot {
-}
-//# sourceMappingURL=state.js.map
+//# sourceMappingURL=engine.js.map

package/adapter/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../../src/adapter/engine.ts"],"names":[],"mappings":"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"}

package/adapter/queries.d.ts

@@ -0,0 +1,68 @@
+import { type Entity, type World } from "@vworlds/vecs";
+import { type Vec2 } from "../components/geometry.js";
+/** Category/mask filter applied to a query. Unlike a shape's own filter
+ * (default `categoryBits = 1`), a query's default `categoryBits` is
+ * `0xffffffff` so the query is not itself filtered out. */
+export interface QueryFilter {
+    /** Bits this query "is". Default `0xffffffff` (matches every category). */
+    categoryBits?: number;
+    /** Bits this query "sees". Default `0xffffffff` (sees every category). */
+    maskBits?: number;
+}
+/** A single ray-cast hit, resolved to a Vecs shape entity with plain-data
+ * geometry — never a Box2D handle. */
+export interface RayHit {
+    /** The shape entity that was hit. */
+    entity: Entity;
+    /** World-space hit point. */
+    point: Vec2;
+    /** World-space unit surface normal at the hit point. */
+    normal: Vec2;
+    /** Fraction along `from` → `to`, in `[0, 1]`. */
+    fraction: number;
+}
+/**
+ * Stable, world-scoped facade for synchronous read-only physics queries: ray
+ * casts and spatial overlaps. Obtained via {@link physics}. Never mutates the
+ * world, never creates or destroys entities, and never wakes bodies.
+ */
+export interface PhysicsQueries {
+    /** Casts a ray from `from` to `to` and returns the closest hit, or `undefined`
+     * if the ray hits nothing (or only hits shapes whose entity has since been
+     * destroyed / removed). */
+    rayCastClosest(query: {
+        from: Vec2;
+        to: Vec2;
+        filter?: QueryFilter;
+    }): RayHit | undefined;
+    /** Casts a ray from `from` to `to` and returns every hit along the way. */
+    rayCastAll(query: {
+        from: Vec2;
+        to: Vec2;
+        filter?: QueryFilter;
+    }): RayHit[];
+    /** Returns every shape entity whose fat AABB overlaps `[min, max]`. This is
+     * a broad-phase query: it can over-report relative to exact shape
+     * overlap. */
+    overlapAABB(query: {
+        min: Vec2;
+        max: Vec2;
+        filter?: QueryFilter;
+    }): Entity[];
+    /** Returns every shape entity that precisely overlaps a circle centered at
+     * `center` with the given `radius`. */
+    overlapCircle(query: {
+        center: Vec2;
+        radius: number;
+        filter?: QueryFilter;
+    }): Entity[];
+}
+/**
+ * Returns the {@link PhysicsQueries} facade for `world`.
+ *
+ * Throws if `world.module(PhysicsModule)` has not been called (the error
+ * message comes from `getPhysicsEngine`). The returned facade is stable: repeated
+ * calls for the same world return the same instance, so it never
+ * re-allocates.
+ */
+export declare function physics(world: World): PhysicsQueries;

package/adapter/queries.js

@@ -0,0 +1,145 @@
+// M8-3 — Query foundation: `physics(world)` accessor + `PhysicsQueries` facade.
+//
+// The ONE narrow imperative entry point vecs-physics exposes: world-scoped,
+// read-only queries against the live Box2D world. Results are always Vecs
+// entities (shape entities) and plain data — never Box2D handles.
+//
+// box2d3-wasm imports are confined to `src/adapter/`; this file is part of
+// that boundary. Scratch allocations (b2Vec2, b2QueryFilter, b2AABB) reuse
+// global pools allocated at module load. Transient allocations like b2RayResult
+// are freed via explicit `finally { .delete() }`.
+import { scr_b2AABB, scr_b2QueryFilter, scr_b2Vec2 } from "./runtime.js";
+import { getPhysicsEngine, } from "./engine.js";
+/**
+ * Returns the {@link PhysicsQueries} facade for `world`.
+ *
+ * Throws if `world.module(PhysicsModule)` has not been called (the error
+ * message comes from `getPhysicsEngine`). The returned facade is stable: repeated
+ * calls for the same world return the same instance, so it never
+ * re-allocates.
+ */
+export function physics(world) {
+    const engine = getPhysicsEngine(world);
+    return (engine.queries ?? (engine.queries = new PhysicsQueriesImpl(world, engine)));
+}
+class PhysicsQueriesImpl {
+    constructor(world, engine) {
+        this.world = world;
+        this.engine = engine;
+    }
+    rayCastClosest(query) {
+        const { box2d, worldId } = this.engine;
+        const origin = scr_b2Vec2[0];
+        origin.Set(query.from.x, query.from.y);
+        const translation = scr_b2Vec2[1];
+        translation.Set(query.to.x - query.from.x, query.to.y - query.from.y);
+        const result = box2d.b2World_CastRayClosest(worldId, origin, translation, to_b2QueryFilter(query.filter));
+        try {
+            if (!result.hit) {
+                return undefined;
+            }
+            const entity = resolveShapeEntity(this.engine, this.world, result.shapeId);
+            if (entity === undefined) {
+                return undefined;
+            }
+            return {
+                entity,
+                point: { x: result.point.x, y: result.point.y },
+                normal: { x: result.normal.x, y: result.normal.y },
+                fraction: result.fraction,
+            };
+        }
+        finally {
+            result.delete();
+        }
+    }
+    rayCastAll(query) {
+        const { box2d, worldId } = this.engine;
+        const origin = scr_b2Vec2[0];
+        origin.Set(query.from.x, query.from.y);
+        const translation = scr_b2Vec2[1];
+        translation.Set(query.to.x - query.from.x, query.to.y - query.from.y);
+        const hits = [];
+        box2d.b2World_CastRay(worldId, origin, translation, to_b2QueryFilter(query.filter), (result) => {
+            const entity = resolveShapeEntity(this.engine, this.world, result.shapeId);
+            if (entity !== undefined) {
+                hits.push({
+                    entity,
+                    point: { x: result.point.x, y: result.point.y },
+                    normal: { x: result.normal.x, y: result.normal.y },
+                    fraction: result.fraction,
+                });
+            }
+            return 1;
+        });
+        return hits;
+    }
+    overlapAABB(query) {
+        const { box2d, worldId } = this.engine;
+        const aabb = scr_b2AABB;
+        aabb.lowerBound.Set(query.min.x, query.min.y);
+        aabb.upperBound.Set(query.max.x, query.max.y);
+        const entities = [];
+        const seen = new Set();
+        box2d.b2World_OverlapAABB(worldId, aabb, to_b2QueryFilter(query.filter), (result) => {
+            const entity = resolveShapeEntity(this.engine, this.world, result.shapeId);
+            if (entity !== undefined && !seen.has(entity.eid)) {
+                seen.add(entity.eid);
+                entities.push(entity);
+            }
+            return true;
+        });
+        return entities;
+    }
+    overlapCircle(query) {
+        const { box2d, worldId } = this.engine;
+        const centerVec = scr_b2Vec2[0];
+        centerVec.Set(query.center.x, query.center.y);
+        const proxy = box2d.b2MakeProxy(centerVec, 1, query.radius);
+        try {
+            const entities = [];
+            const seen = new Set();
+            box2d.b2World_OverlapShape(worldId, proxy, to_b2QueryFilter(query.filter), (result) => {
+                const entity = resolveShapeEntity(this.engine, this.world, result.shapeId);
+                if (entity !== undefined && !seen.has(entity.eid)) {
+                    seen.add(entity.eid);
+                    entities.push(entity);
+                }
+                return true;
+            });
+            return entities;
+        }
+        finally {
+            proxy.delete();
+        }
+    }
+}
+/** Maps a {@link QueryFilter} (default `0xffffffff`/`0xffffffff` — "sees and
+ * is seen by everything") and returns a scratch `b2QueryFilter`. `b2QueryFilter` is not
+ * `b2DefaultQueryFilter` here: the default-constructed filter is all zeros,
+ * which would match nothing.
+ * to_b2QueryFilter cannot be called again until the returned b2QueryFilter is no longer in use
+ * */
+function to_b2QueryFilter(filter) {
+    const target = scr_b2QueryFilter[0];
+    target.categoryBits = filter?.categoryBits ?? 0xffffffff;
+    target.maskBits = filter?.maskBits ?? 0xffffffff;
+    return target;
+}
+/** Resolves a Box2D shape hit back to its Vecs shape entity, mirroring the
+ * `PhysicsEvents` shape→entity resolution (`src/systems/events.ts`):
+ * `entityByShapeIndex.get(shapeId.index1)` → `EID` → live `Entity`. Returns
+ * `undefined` (drop silently) if the slot is empty or the entity has been
+ * destroyed — the same rule as `PhysicsEvents`. */
+function resolveShapeEntity(engine, world, shapeId) {
+    const eid = engine.entityByShapeIndex.get(shapeId.index1);
+    if (eid === undefined) {
+        return undefined;
+    }
+    const entity = world.getEntity(eid);
+    if (entity === undefined || entity.destroyed) {
+        return undefined;
+    }
+    return entity;
+}
+//# sourceMappingURL=queries.js.map

package/adapter/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../../../src/adapter/queries.ts"],"names":[],"mappings":"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"}

package/adapter/runtime.d.ts

@@ -1,4 +1,8 @@
 import Box2DFactory from "box2d3-wasm";
+import type { b2AABB, b2QueryFilter, b2Vec2 } from "./engine.js";
 export type Box2DModule = Awaited<ReturnType<typeof Box2DFactory>>;
+export declare const scr_b2Vec2: b2Vec2[];
+export declare const scr_b2QueryFilter: b2QueryFilter[];
+export declare let scr_b2AABB: b2AABB | null;
 export declare function preloadPhysics(): Promise<void>;
 export declare function getBox2D(): Box2DModule;

package/adapter/runtime.js

@@ -2,6 +2,11 @@ import { cpus } from "node:os";
 import Box2DFactory from "box2d3-wasm";
 let modulePromise = null;
 let module = null;
+// Global scratch pools for common Box2D structs. Allocated once at module load,
+// reused across queries and other non-reentrant operations.
+export const scr_b2Vec2 = [];
+export const scr_b2QueryFilter = [];
+export let scr_b2AABB = null;
 export async function preloadPhysics() {
     var _a;
     if (modulePromise) {
@@ -14,10 +19,25 @@ export async function preloadPhysics() {
     (_a = global.navigator).hardwareConcurrency ?? (_a.hardwareConcurrency = cpus().length);
     modulePromise = Box2DFactory().then((loadedModule) => {
         module = loadedModule;
+        initializeScratchPools(loadedModule);
         return loadedModule;
     });
     await modulePromise;
 }
+function initializeScratchPools(box2d) {
+    // b2Vec2: ray casts need 2 simultaneous (origin + translation), polygon/chain creation
+    // can reuse serially. Allocate 3 for safety margin.
+    for (let i = 0; i < 3; i++) {
+        scr_b2Vec2.push(new box2d.b2Vec2());
+    }
+    // b2QueryFilter: queries and material_filter_sync each need at most 1 simultaneously.
+    // Allocate 2 for safety.
+    for (let i = 0; i < 2; i++) {
+        scr_b2QueryFilter.push(new box2d.b2QueryFilter());
+    }
+    // b2AABB: overlapAABB needs exactly 1.
+    scr_b2AABB = new box2d.b2AABB();
+}
 export function getBox2D() {
     if (!module) {
         throw new Error("Box2D module not loaded. Call `await preloadPhysics()` before `world.module(PhysicsModule)`.");

package/adapter/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../../src/adapter/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,YAAY,MAAM,aAAa,CAAC;AAIvC,IAAI,aAAa,GAAgC,IAAI,CAAC;AACtD,IAAI,MAAM,GAAuB,IAAI,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,cAAc;;IAClC,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,aAAa,CAAC;QACpB,OAAO;IACT,CAAC;IAED,8EAA8E;IAC9E,MAAM,MAAM,GAAG,UAA2D,CAAC;IAC3E,MAAM,CAAC,SAAS,KAAhB,MAAM,CAAC,SAAS,GAAK,EAAE,EAAC;IACxB,MAAC,MAAM,CAAC,SAA8C,EAAC,mBAAmB,QAAnB,mBAAmB,GAAK,IAAI,EAAE,CAAC,MAAM,EAAC;IAE7F,aAAa,GAAG,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,EAAE;QACnD,MAAM,GAAG,YAAY,CAAC;QACtB,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC,CAAC;IACH,MAAM,aAAa,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../../src/adapter/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,YAAY,MAAM,aAAa,CAAC;AAMvC,IAAI,aAAa,GAAgC,IAAI,CAAC;AACtD,IAAI,MAAM,GAAuB,IAAI,CAAC;AAEtC,gFAAgF;AAChF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAa,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAoB,EAAE,CAAC;AACrD,MAAM,CAAC,IAAI,UAAU,GAAkB,IAAI,CAAC;AAE5C,MAAM,CAAC,KAAK,UAAU,cAAc;;IAClC,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,aAAa,CAAC;QACpB,OAAO;IACT,CAAC;IAED,8EAA8E;IAC9E,MAAM,MAAM,GAAG,UAA2D,CAAC;IAC3E,MAAM,CAAC,SAAS,KAAhB,MAAM,CAAC,SAAS,GAAK,EAAE,EAAC;IACxB,MAAC,MAAM,CAAC,SAA8C,EAAC,mBAAmB,QAAnB,mBAAmB,GAAK,IAAI,EAAE,CAAC,MAAM,EAAC;IAE7F,aAAa,GAAG,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,EAAE;QACnD,MAAM,GAAG,YAAY,CAAC;QACtB,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC,CAAC;IACH,MAAM,aAAa,CAAC;AACtB,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAkB;IAChD,uFAAuF;IACvF,oDAAoD;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,sFAAsF;IACtF,yBAAyB;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,iBAAiB,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,uCAAuC;IACvC,UAAU,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/components/body.js

@@ -1,10 +1,11 @@
 // Body-level components: the entity-marking `Body` plus the canonical pose and
-// velocity state. Defaults match Box2D's `b2DefaultBodyDef()` (see
+// velocity data. Defaults match Box2D's `b2DefaultBodyDef()` (see
 // `box2d/src/types.c`). Public API — see `docs/components.md`.
 //
 // These are plain data classes: every field is initialised on the class body so
 // `new C()` yields a valid, default-shaped instance (the Vecs zero-arg
-// contract). No imports from systems/ or adapter/ — components are pure data.
+// contract). No imports from systems/ or adapter/ beyond type-only `b2*Id`
+// handle types — components are pure data.
 /** Simulation behaviour of a {@link Body}. */
 export var BodyType;
 (function (BodyType) {
@@ -22,6 +23,8 @@ export class Body {
         this.bullet = false;
         this.enabled = true;
         this.allowFastRotation = false;
+        /** @internal Engine-owned box2d handle; set by the lifecycle system, undefined until then. */
+        this._bodyId = undefined;
     }
 }
 /** Canonical world-space body position. Teleports when written by user code. */

package/components/body.js.map

@@ -1 +1 @@
-{"version":3,"file":"body.js","sourceRoot":"","sources":["../../../../src/components/body.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,+DAA+D;AAC/D,EAAE;AACF,gFAAgF;AAChF,uEAAuE;AACvE,8EAA8E;AAE9E,8CAA8C;AAC9C,MAAM,CAAN,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,gCAAgC;IAChC,6BAAiB,CAAA;IACjB,2EAA2E;IAC3E,mCAAuB,CAAA;IACvB,2DAA2D;IAC3D,+BAAmB,CAAA;AACrB,CAAC,EAPW,QAAQ,KAAR,QAAQ,QAOnB;AAED,kFAAkF;AAClF,MAAM,OAAO,IAAI;IAAjB;QACE,SAAI,GAAG,QAAQ,CAAC,MAAM,CAAC;QACvB,WAAM,GAAG,KAAK,CAAC;QACf,YAAO,GAAG,IAAI,CAAC;QACf,sBAAiB,GAAG,KAAK,CAAC;IAC5B,CAAC;CAAA;AAED,gFAAgF;AAChF,MAAM,OAAO,QAAQ;IAArB;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;IACR,CAAC;CAAA;AAED,8EAA8E;AAC9E,MAAM,OAAO,QAAQ;IAArB;QACE,UAAK,GAAG,CAAC,CAAC;IACZ,CAAC;CAAA;AAED,gFAAgF;AAChF,MAAM,OAAO,cAAc;IAA3B;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;IACR,CAAC;CAAA;AAED,mDAAmD;AACnD,MAAM,OAAO,eAAe;IAA5B;QACE,UAAK,GAAG,CAAC,CAAC;IACZ,CAAC;CAAA"}
+{"version":3,"file":"body.js","sourceRoot":"","sources":["../../../../src/components/body.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kEAAkE;AAClE,+DAA+D;AAC/D,EAAE;AACF,gFAAgF;AAChF,uEAAuE;AACvE,2EAA2E;AAC3E,2CAA2C;AAI3C,8CAA8C;AAC9C,MAAM,CAAN,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,gCAAgC;IAChC,6BAAiB,CAAA;IACjB,2EAA2E;IAC3E,mCAAuB,CAAA;IACvB,2DAA2D;IAC3D,+BAAmB,CAAA;AACrB,CAAC,EAPW,QAAQ,KAAR,QAAQ,QAOnB;AAED,kFAAkF;AAClF,MAAM,OAAO,IAAI;IAAjB;QACE,SAAI,GAAG,QAAQ,CAAC,MAAM,CAAC;QACvB,WAAM,GAAG,KAAK,CAAC;QACf,YAAO,GAAG,IAAI,CAAC;QACf,sBAAiB,GAAG,KAAK,CAAC;QAC1B,8FAA8F;QAC9F,YAAO,GAAyB,SAAS,CAAC;IAC5C,CAAC;CAAA;AAED,gFAAgF;AAChF,MAAM,OAAO,QAAQ;IAArB;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;IACR,CAAC;CAAA;AAED,8EAA8E;AAC9E,MAAM,OAAO,QAAQ;IAArB;QACE,UAAK,GAAG,CAAC,CAAC;IACZ,CAAC;CAAA;AAED,gFAAgF;AAChF,MAAM,OAAO,cAAc;IAA3B;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;IACR,CAAC;CAAA;AAED,mDAAmD;AACnD,MAAM,OAAO,eAAe;IAA5B;QACE,UAAK,GAAG,CAAC,CAAC;IACZ,CAAC;CAAA"}

package/components/geometry.d.ts

@@ -3,6 +3,21 @@ export type Vec2 = {
     x: number;
     y: number;
 };
+/**
+ * Empty umbrella marker for the six geometry components. Every shape entity carries
+ * exactly one concrete geometry (`Box`, `Circle`, `Capsule`, `Segment`,
+ * `Polygon`, or `Chain`); each implements `Shape` so queries and systems can
+ * match any geometry without enumerating every concrete type.
+ */
+export declare abstract class Shape {
+}
+/**
+ * Internal marker for geometries backed by one Box2D `b2ShapeId`. Chains are
+ * intentionally excluded because Box2D creates them through `b2ChainId` and
+ * exposes their collision segments separately.
+ */
+export declare abstract class SingleShape extends Shape {
+}
 /**
  * Axis-aligned box in local shape space, stored as half extents (`hx`/`hy`) to
  * match Box2D's internal representation. The `width`/`height` accessors are
@@ -12,7 +27,7 @@ export type Vec2 = {
  * still go through `entity.set(Box, …)` or `entity.modified(Box)` for physics
  * to notice. See PLAN → Box accessors.
  */
-export declare class Box {
+export declare class Box extends SingleShape {
     hx: number;
     hy: number;
     get width(): number;
@@ -21,11 +36,11 @@ export declare class Box {
     set height(value: number);
 }
 /** Circle geometry. */
-export declare class Circle {
+export declare class Circle extends SingleShape {
     radius: number;
 }
 /** Capsule geometry: two local endpoints joined by a radius. */
-export declare class Capsule {
+export declare class Capsule extends SingleShape {
     x1: number;
     y1: number;
     x2: number;
@@ -33,7 +48,7 @@ export declare class Capsule {
     radius: number;
 }
 /** Line-segment geometry. */
-export declare class Segment {
+export declare class Segment extends SingleShape {
     x1: number;
     y1: number;
     x2: number;
@@ -44,12 +59,12 @@ export declare class Segment {
  * Convexity and vertex count are validated on shape creation, not on every
  * update. See PLAN → Vec2 in Polygon / Chain.
  */
-export declare class Polygon {
+export declare class Polygon extends SingleShape {
     vertices: Vec2[];
     radius: number;
 }
 /** Chain geometry for static terrain. Needs at least four points. */
-export declare class Chain {
+export declare class Chain extends Shape {
     points: Vec2[];
     loop: boolean;
 }

package/components/geometry.js

@@ -1,6 +1,34 @@
-// Geometry components. Exactly one per shape entity; `PhysicsModule` marks them
-// mutually exclusive so adding one removes any previous geometry. Defaults match
-// the documented shapes. Public API — see `docs/components.md`.
+// Geometry components. Exactly one per shape entity; every concrete geometry
+// implements the `Shape` umbrella so `PhysicsModule` enforces mutual exclusivity
+// (setting one evicts any previous geometry). Single Box2D shapes also implement
+// the internal `SingleShape` tier; `Chain` is separate because Box2D exposes it
+// through `b2ChainId` plus underlying segment shapes.
+// Public API — see `docs/components.md`.
+//
+// These are plain data classes: every field is initialised on the class body so
+// `new C()` yields a valid, default-shaped instance (the Vecs zero-arg
+// contract). No imports from systems/ or adapter/ beyond type-only `b2*Id`
+// handle types — components are pure data.
+/**
+ * Empty umbrella marker for the six geometry components. Every shape entity carries
+ * exactly one concrete geometry (`Box`, `Circle`, `Capsule`, `Segment`,
+ * `Polygon`, or `Chain`); each implements `Shape` so queries and systems can
+ * match any geometry without enumerating every concrete type.
+ */
+export class Shape {
+}
+/**
+ * Internal marker for geometries backed by one Box2D `b2ShapeId`. Chains are
+ * intentionally excluded because Box2D creates them through `b2ChainId` and
+ * exposes their collision segments separately.
+ */
+export class SingleShape extends Shape {
+    constructor() {
+        super(...arguments);
+        /** @internal Engine-owned Box2D shape handle. Set by the single-shape lifecycle system. */
+        this._shapeId = undefined;
+    }
+}
 /**
  * Axis-aligned box in local shape space, stored as half extents (`hx`/`hy`) to
  * match Box2D's internal representation. The `width`/`height` accessors are
@@ -10,8 +38,9 @@
  * still go through `entity.set(Box, …)` or `entity.modified(Box)` for physics
  * to notice. See PLAN → Box accessors.
  */
-export class Box {
+export class Box extends SingleShape {
     constructor() {
+        super(...arguments);
         this.hx = 0.5;
         this.hy = 0.5;
     }
@@ -29,14 +58,16 @@ export class Box {
     }
 }
 /** Circle geometry. */
-export class Circle {
+export class Circle extends SingleShape {
     constructor() {
+        super(...arguments);
         this.radius = 0.5;
     }
 }
 /** Capsule geometry: two local endpoints joined by a radius. */
-export class Capsule {
+export class Capsule extends SingleShape {
     constructor() {
+        super(...arguments);
         this.x1 = -0.5;
         this.y1 = 0;
         this.x2 = 0.5;
@@ -45,8 +76,9 @@ export class Capsule {
     }
 }
 /** Line-segment geometry. */
-export class Segment {
+export class Segment extends SingleShape {
     constructor() {
+        super(...arguments);
         this.x1 = -0.5;
         this.y1 = 0;
         this.x2 = 0.5;
@@ -58,15 +90,21 @@ export class Segment {
  * Convexity and vertex count are validated on shape creation, not on every
  * update. See PLAN → Vec2 in Polygon / Chain.
  */
-export class Polygon {
+export class Polygon extends SingleShape {
     constructor() {
+        super(...arguments);
         this.vertices = [];
         this.radius = 0;
     }
 }
 /** Chain geometry for static terrain. Needs at least four points. */
-export class Chain {
+export class Chain extends Shape {
     constructor() {
+        super(...arguments);
+        /** @internal Engine-owned Box2D chain handle. Set by the chain lifecycle system. */
+        this._chainId = undefined;
+        /** @internal Public shape indices of the chain's generated segment shapes. */
+        this._segmentIndices = [];
         this.points = [];
         this.loop = false;
     }

package/components/geometry.js.map

@@ -1 +1 @@
-{"version":3,"file":"geometry.js","sourceRoot":"","sources":["../../../../src/components/geometry.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,iFAAiF;AACjF,gEAAgE;AAKhE;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAG;IAAhB;QACE,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,GAAG,CAAC;IAiBX,CAAC;IAfC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,KAAK,CAAC,KAAa;QACrB,IAAI,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,MAAM,CAAC,KAAa;QACtB,IAAI,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IACtB,CAAC;CACF;AAED,uBAAuB;AACvB,MAAM,OAAO,MAAM;IAAnB;QACE,WAAM,GAAG,GAAG,CAAC;IACf,CAAC;CAAA;AAED,gEAAgE;AAChE,MAAM,OAAO,OAAO;IAApB;QACE,OAAE,GAAG,CAAC,GAAG,CAAC;QACV,OAAE,GAAG,CAAC,CAAC;QACP,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,CAAC,CAAC;QACP,WAAM,GAAG,IAAI,CAAC;IAChB,CAAC;CAAA;AAED,6BAA6B;AAC7B,MAAM,OAAO,OAAO;IAApB;QACE,OAAE,GAAG,CAAC,GAAG,CAAC;QACV,OAAE,GAAG,CAAC,CAAC;QACP,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,CAAC,CAAC;IACT,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,OAAO,OAAO;IAApB;QACE,aAAQ,GAAW,EAAE,CAAC;QACtB,WAAM,GAAG,CAAC,CAAC;IACb,CAAC;CAAA;AAED,qEAAqE;AACrE,MAAM,OAAO,KAAK;IAAlB;QACE,WAAM,GAAW,EAAE,CAAC;QACpB,SAAI,GAAG,KAAK,CAAC;IACf,CAAC;CAAA"}
+{"version":3,"file":"geometry.js","sourceRoot":"","sources":["../../../../src/components/geometry.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,sDAAsD;AACtD,yCAAyC;AACzC,EAAE;AACF,gFAAgF;AAChF,uEAAuE;AACvE,2EAA2E;AAC3E,2CAA2C;AAO3C;;;;;GAKG;AACH,MAAM,OAAgB,KAAK;CAAG;AAE9B;;;;GAIG;AACH,MAAM,OAAgB,WAAY,SAAQ,KAAK;IAA/C;;QACE,2FAA2F;QAC3F,aAAQ,GAA0B,SAAS,CAAC;IAC9C,CAAC;CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAI,SAAQ,WAAW;IAApC;;QACE,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,GAAG,CAAC;IAiBX,CAAC;IAfC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,KAAK,CAAC,KAAa;QACrB,IAAI,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,MAAM,CAAC,KAAa;QACtB,IAAI,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IACtB,CAAC;CACF;AAED,uBAAuB;AACvB,MAAM,OAAO,MAAO,SAAQ,WAAW;IAAvC;;QACE,WAAM,GAAG,GAAG,CAAC;IACf,CAAC;CAAA;AAED,gEAAgE;AAChE,MAAM,OAAO,OAAQ,SAAQ,WAAW;IAAxC;;QACE,OAAE,GAAG,CAAC,GAAG,CAAC;QACV,OAAE,GAAG,CAAC,CAAC;QACP,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,CAAC,CAAC;QACP,WAAM,GAAG,IAAI,CAAC;IAChB,CAAC;CAAA;AAED,6BAA6B;AAC7B,MAAM,OAAO,OAAQ,SAAQ,WAAW;IAAxC;;QACE,OAAE,GAAG,CAAC,GAAG,CAAC;QACV,OAAE,GAAG,CAAC,CAAC;QACP,OAAE,GAAG,GAAG,CAAC;QACT,OAAE,GAAG,CAAC,CAAC;IACT,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,OAAO,OAAQ,SAAQ,WAAW;IAAxC;;QACE,aAAQ,GAAW,EAAE,CAAC;QACtB,WAAM,GAAG,CAAC,CAAC;IACb,CAAC;CAAA;AAED,qEAAqE;AACrE,MAAM,OAAO,KAAM,SAAQ,KAAK;IAAhC;;QACE,oFAAoF;QACpF,aAAQ,GAA0B,SAAS,CAAC;QAC5C,8EAA8E;QAC9E,oBAAe,GAAa,EAAE,CAAC;QAC/B,WAAM,GAAW,EAAE,CAAC;QACpB,SAAI,GAAG,KAAK,CAAC;IACf,CAAC;CAAA"}