@vworlds/vecs-physics 1.0.16

package/components/material.d.ts

@@ -0,0 +1,18 @@
+/** Physical surface material for a shape (bundles density + surface props). */
+export declare class Material {
+    density: number;
+    friction: number;
+    restitution: number;
+    rollingResistance: number;
+    tangentSpeed: number;
+    userMaterialId: number;
+}
+/** Collision category/mask/group. Missing means category 1, collides with all. */
+export declare class CollisionFilter {
+    categoryBits: number;
+    maskBits: number;
+    groupIndex: number;
+}
+/** Marks a shape as an overlap-only sensor (no collision response). */
+export declare class Sensor {
+}

package/components/material.js

@@ -0,0 +1,32 @@
+// Material, collision filtering, and the sensor marker. Defaults match
+// `b2DefaultShapeDef()` / `b2DefaultSurfaceMaterial()` / `b2DefaultFilter()`
+// (see `box2d/src/types.c`). Public API — see `docs/components.md`.
+//
+// Divergence from Box2D: `categoryBits`/`maskBits` are 32-bit and stored as
+// plain `number`, not Box2D's `uint64_t`. 32 categories is plenty, and JS
+// bitwise ops (`&`, `|`) are native 32-bit, so filtering — `(catA & maskB) !==
+// 0` — stays fast and bigint-free. `userMaterialId` is an opaque id (not a
+// bitfield), also a `number`. See PLAN → Settled Decisions.
+/** Physical surface material for a shape (bundles density + surface props). */
+export class Material {
+    constructor() {
+        this.density = 1;
+        this.friction = 0.6;
+        this.restitution = 0;
+        this.rollingResistance = 0;
+        this.tangentSpeed = 0;
+        this.userMaterialId = 0;
+    }
+}
+/** Collision category/mask/group. Missing means category 1, collides with all. */
+export class CollisionFilter {
+    constructor() {
+        this.categoryBits = 1;
+        this.maskBits = 0xffffffff;
+        this.groupIndex = 0;
+    }
+}
+/** Marks a shape as an overlap-only sensor (no collision response). */
+export class Sensor {
+}
+//# sourceMappingURL=material.js.map

package/components/material.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"material.js","sourceRoot":"","sources":["../../../../src/components/material.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,6EAA6E;AAC7E,oEAAoE;AACpE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,+EAA+E;AAC/E,2EAA2E;AAC3E,4DAA4D;AAE5D,+EAA+E;AAC/E,MAAM,OAAO,QAAQ;IAArB;QACE,YAAO,GAAG,CAAC,CAAC;QACZ,aAAQ,GAAG,GAAG,CAAC;QACf,gBAAW,GAAG,CAAC,CAAC;QAChB,sBAAiB,GAAG,CAAC,CAAC;QACtB,iBAAY,GAAG,CAAC,CAAC;QACjB,mBAAc,GAAG,CAAC,CAAC;IACrB,CAAC;CAAA;AAED,kFAAkF;AAClF,MAAM,OAAO,eAAe;IAA5B;QACE,iBAAY,GAAG,CAAC,CAAC;QACjB,aAAQ,GAAG,UAAU,CAAC;QACtB,eAAU,GAAG,CAAC,CAAC;IACjB,CAAC;CAAA;AAED,uEAAuE;AACvE,MAAM,OAAO,MAAM;CAAG"}

package/components/shape_pose.d.ts

@@ -0,0 +1,9 @@
+/** Local shape offset from the parent body origin. */
+export declare class ShapePosition {
+    x: number;
+    y: number;
+}
+/** Local shape rotation in radians. */
+export declare class ShapeRotation {
+    angle: number;
+}

package/components/shape_pose.js

@@ -0,0 +1,16 @@
+// Shape-local pose components, relative to the immediate parent body. Optional:
+// missing means the identity offset. Public API — see `docs/components.md`.
+/** Local shape offset from the parent body origin. */
+export class ShapePosition {
+    constructor() {
+        this.x = 0;
+        this.y = 0;
+    }
+}
+/** Local shape rotation in radians. */
+export class ShapeRotation {
+    constructor() {
+        this.angle = 0;
+    }
+}
+//# sourceMappingURL=shape_pose.js.map

package/components/shape_pose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape_pose.js","sourceRoot":"","sources":["../../../../src/components/shape_pose.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAE5E,sDAAsD;AACtD,MAAM,OAAO,aAAa;IAA1B;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;IACR,CAAC;CAAA;AAED,uCAAuC;AACvC,MAAM,OAAO,aAAa;IAA1B;QACE,UAAK,GAAG,CAAC,CAAC;IACZ,CAAC;CAAA"}

package/components/target.d.ts

@@ -0,0 +1,13 @@
+/** Target world-space position for a kinematic body. */
+export declare class KinematicTargetPosition {
+    x: number;
+    y: number;
+    tolerance: number;
+    wake: boolean;
+}
+/** Target world-space rotation (radians) for a kinematic body. */
+export declare class KinematicTargetRotation {
+    angle: number;
+    tolerance: number;
+    wake: boolean;
+}

package/components/target.js

@@ -0,0 +1,21 @@
+// Kinematic target components. Drive a kinematic body toward a target pose; once
+// within `tolerance` physics leaves the component in place and stops driving.
+// Public API — see `docs/components.md`.
+/** Target world-space position for a kinematic body. */
+export class KinematicTargetPosition {
+    constructor() {
+        this.x = 0;
+        this.y = 0;
+        this.tolerance = 0.001;
+        this.wake = true;
+    }
+}
+/** Target world-space rotation (radians) for a kinematic body. */
+export class KinematicTargetRotation {
+    constructor() {
+        this.angle = 0;
+        this.tolerance = 0.001;
+        this.wake = true;
+    }
+}
+//# sourceMappingURL=target.js.map

package/components/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../../../src/components/target.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,8EAA8E;AAC9E,yCAAyC;AAEzC,wDAAwD;AACxD,MAAM,OAAO,uBAAuB;IAApC;QACE,MAAC,GAAG,CAAC,CAAC;QACN,MAAC,GAAG,CAAC,CAAC;QACN,cAAS,GAAG,KAAK,CAAC;QAClB,SAAI,GAAG,IAAI,CAAC;IACd,CAAC;CAAA;AAED,kEAAkE;AAClE,MAAM,OAAO,uBAAuB;IAApC;QACE,UAAK,GAAG,CAAC,CAAC;QACV,cAAS,GAAG,KAAK,CAAC;QAClB,SAAI,GAAG,IAAI,CAAC;IACd,CAAC;CAAA"}

package/index.d.ts

@@ -0,0 +1,10 @@
+export { installPhysics, type PhysicsOptions } from "./install.js";
+export { preloadPhysics } from "./adapter/runtime.js";
+export { Body, BodyType, Position, Rotation, LinearVelocity, AngularVelocity, } from "./components/body.js";
+export { Damping, GravityScale, MotionLocks, Sleep } from "./components/body_tuning.js";
+export { ShapePosition, ShapeRotation } from "./components/shape_pose.js";
+export { Box, Circle, Capsule, Segment, Polygon, Chain, type Vec2 } from "./components/geometry.js";
+export { Material, CollisionFilter, Sensor } from "./components/material.js";
+export { Force, Torque, Impulse, AngularImpulse } from "./components/force.js";
+export { KinematicTargetPosition, KinematicTargetRotation } from "./components/target.js";
+export { ContactEvents, type ContactEvent, SensorEvents, type SensorEvent, HitEvents, type HitEvent, } from "./components/events.js";

package/index.js

@@ -0,0 +1,23 @@
+// Public API surface for @vworlds/vecs-physics. Only re-exports — no logic.
+// The stable contract is documented in docs/ and architecture/PLAN.md →
+// Public API Contract.
+// Entry point
+export { installPhysics } from "./install.js";
+export { preloadPhysics } from "./adapter/runtime.js";
+// Body
+export { Body, BodyType, Position, Rotation, LinearVelocity, AngularVelocity, } from "./components/body.js";
+// Body tunables
+export { Damping, GravityScale, MotionLocks, Sleep } from "./components/body_tuning.js";
+// Shape pose
+export { ShapePosition, ShapeRotation } from "./components/shape_pose.js";
+// Geometry
+export { Box, Circle, Capsule, Segment, Polygon, Chain } from "./components/geometry.js";
+// Material / filter / sensor
+export { Material, CollisionFilter, Sensor } from "./components/material.js";
+// Forces & impulses
+export { Force, Torque, Impulse, AngularImpulse } from "./components/force.js";
+// Kinematic targets
+export { KinematicTargetPosition, KinematicTargetRotation } from "./components/target.js";
+// Events
+export { ContactEvents, SensorEvents, HitEvents, } from "./components/events.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wEAAwE;AACxE,uBAAuB;AAEvB,cAAc;AACd,OAAO,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO;AACP,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,gBAAgB;AAChB,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAExF,aAAa;AACb,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE1E,WAAW;AACX,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAa,MAAM,0BAA0B,CAAC;AAEpG,6BAA6B;AAC7B,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAE7E,oBAAoB;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/E,oBAAoB;AACpB,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,SAAS;AACT,OAAO,EACL,aAAa,EAEb,YAAY,EAEZ,SAAS,GAEV,MAAM,wBAAwB,CAAC"}

package/install.d.ts

@@ -0,0 +1,30 @@
+import { type IPhase, type World } from "@vworlds/vecs";
+/** Options for {@link installPhysics}. Every field is optional; omitted fields
+ * fall back to Box2D-aligned defaults. */
+export type PhysicsOptions = {
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    fixedTimeStep?: number;
+    subSteps?: number;
+    debug?: boolean;
+    /** Override the warning sink used by `PhysicsDebugValidation` when
+     * `debug: true`. Accepts any `(message: string) => void` callback.
+     * Primarily for tests; defaults to `console.warn`. */
+    debugSink?: (message: string) => void;
+    preStepPhase?: IPhase | string;
+    stepPhase?: IPhase | string;
+    postStepPhase?: IPhase | string;
+    restitutionThreshold?: number;
+    hitEventThreshold?: number;
+    contactHertz?: number;
+    contactDampingRatio?: number;
+    contactSpeed?: number;
+    maximumLinearSpeed?: number;
+    enableSleep?: boolean;
+    enableContinuous?: boolean;
+};
+/** Wire the physics engine into `world`. Must be called before `world.start()`
+ * and at most once per world. */
+export declare function installPhysics(world: World, opts?: PhysicsOptions): void;

package/install.js

@@ -0,0 +1,139 @@
+// `installPhysics` — the single entry point that wires the physics engine into a
+// Vecs world. It registers every public component, declares geometry
+// exclusivity, ensures the three physics phases exist, and attaches the private
+// `PhysicsState`. See PLAN.md → _installPhysics Signature_ and
+// _Component registration order_.
+//
+// VP-4 is wiring only: no systems are installed and the engine is a no-op. The
+// physics systems (and the `PhysicsSystemTag` marker they carry) land in VP-6.
+// Registration order still matters — Vecs assigns component type ids in
+// registration order, so keeping the order stable keeps ids deterministic.
+import { AngularVelocity, Body, LinearVelocity, Position, Rotation } from "./components/body.js";
+import { Damping, GravityScale, MotionLocks, Sleep } from "./components/body_tuning.js";
+import { Box, Capsule, Chain, Circle, Polygon, Segment } from "./components/geometry.js";
+import { AngularImpulse, Force, Impulse, Torque } from "./components/force.js";
+import { CollisionFilter, Material, Sensor } from "./components/material.js";
+import { ContactEvents, HitEvents, SensorEvents } from "./components/events.js";
+import { KinematicTargetPosition, KinematicTargetRotation } from "./components/target.js";
+import { ShapePosition, ShapeRotation } from "./components/shape_pose.js";
+import { getBox2D } from "./adapter/runtime.js";
+import { withAllocated } from "./adapter/disposal.js";
+import { attachPhysics, hasPhysics, PhysicsState, registerInternalComponents, } from "./adapter/state.js";
+import { registerImpulseHooks } from "./systems/impulse_accumulate.js";
+import { installPhysicsSystems } from "./systems/index.js";
+const DEFAULT_PRE_STEP_PHASE = "physics-pre";
+const DEFAULT_STEP_PHASE = "physics-step";
+const DEFAULT_POST_STEP_PHASE = "physics-post";
+/** Wire the physics engine into `world`. Must be called before `world.start()`
+ * and at most once per world. */
+export function installPhysics(world, opts = {}) {
+    if (isWorldStarted(world)) {
+        throw new Error("installPhysics must be called before world.start()");
+    }
+    if (hasPhysics(world)) {
+        throw new Error("installPhysics has already been called on this world");
+    }
+    // 1. Register every public component, in a stable order (see file header).
+    //    `ChildOf` is built into Vecs — referenced, never registered.
+    world.component(Position);
+    world.component(Rotation);
+    world.component(LinearVelocity);
+    world.component(AngularVelocity);
+    world.component(Body);
+    world.component(Damping);
+    world.component(GravityScale);
+    world.component(MotionLocks);
+    world.component(Sleep);
+    world.component(ShapePosition);
+    world.component(ShapeRotation);
+    world.component(Box);
+    world.component(Circle);
+    world.component(Capsule);
+    world.component(Segment);
+    world.component(Polygon);
+    world.component(Chain);
+    world.component(Material);
+    world.component(CollisionFilter);
+    world.component(Sensor);
+    world.component(Force);
+    world.component(Torque);
+    world.component(Impulse);
+    world.component(AngularImpulse);
+    world.component(KinematicTargetPosition);
+    world.component(KinematicTargetRotation);
+    world.component(ContactEvents);
+    world.component(SensorEvents);
+    world.component(HitEvents);
+    // 2. Internal, non-exported components (`PhysicsRoot`, `PhysicsSystemTag`),
+    //    registered in their documented order for deterministic type ids.
+    registerInternalComponents(world);
+    // 3. Geometry components are mutually exclusive: an entity holds at most one.
+    world.setExclusiveComponents(Box, Circle, Capsule, Segment, Polygon, Chain);
+    // 4. Ensure the three physics phases exist (created if missing).
+    const preStep = resolvePhase(world, opts.preStepPhase, DEFAULT_PRE_STEP_PHASE);
+    const step = resolvePhase(world, opts.stepPhase, DEFAULT_STEP_PHASE);
+    const postStep = resolvePhase(world, opts.postStepPhase, DEFAULT_POST_STEP_PHASE);
+    // 5. Allocate WASM state, create the Box2D world, install the systems (bound
+    //    to it), then attach it.
+    const box2d = getBox2D();
+    const options = resolveOptions(opts);
+    const state = new PhysicsState(box2d, options, opts.debugSink);
+    state.worldId = createWorldId(state, options);
+    registerImpulseHooks(world, state);
+    installPhysicsSystems(world, state, { preStep, step, postStep }, {
+        debug: opts.debug ?? false,
+    });
+    attachPhysics(world, state);
+}
+function createWorldId(state, options) {
+    const box2d = state.box2d;
+    return withAllocated(box2d.b2DefaultWorldDef, (def) => {
+        def.gravity.x = options.gravityX;
+        def.gravity.y = options.gravityY;
+        def.restitutionThreshold = options.restitutionThreshold;
+        def.hitEventThreshold = options.hitEventThreshold;
+        def.contactHertz = options.contactHertz;
+        def.contactDampingRatio = options.contactDampingRatio;
+        def.maximumLinearSpeed = options.maximumLinearSpeed;
+        def.enableSleep = options.enableSleep;
+        def.enableContinuous = options.enableContinuous;
+        const worldId = box2d.b2CreateWorld(def);
+        box2d.b2World_SetContactTuning(worldId, options.contactHertz, options.contactDampingRatio, options.contactSpeed);
+        return worldId;
+    });
+}
+/** Resolve a phase placement option to a concrete phase. An `IPhase` is used
+ * as-is; a name (or the default name) is looked up and created if missing. */
+function resolvePhase(world, given, defaultName) {
+    if (given !== undefined && typeof given !== "string") {
+        return given;
+    }
+    const name = given ?? defaultName;
+    return world._pipeline.get(name) ?? world.addPhase(name);
+}
+/** Apply Box2D-aligned defaults to `opts`. */
+function resolveOptions(opts) {
+    return {
+        gravityX: opts.gravity?.x ?? 0,
+        gravityY: opts.gravity?.y ?? -10,
+        fixedTimeStep: opts.fixedTimeStep ?? 1 / 60,
+        subSteps: opts.subSteps ?? 4,
+        debug: opts.debug ?? false,
+        restitutionThreshold: opts.restitutionThreshold ?? 1.0,
+        // box2d b2DefaultWorldDef: def.hitEventThreshold = 1.0f * lengthUnits (types.c:16).
+        hitEventThreshold: opts.hitEventThreshold ?? 1.0,
+        contactHertz: opts.contactHertz ?? 30,
+        contactDampingRatio: opts.contactDampingRatio ?? 10,
+        // box2d b2DefaultWorldDef: def.contactSpeed = 3.0f * lengthUnits (types.c:18).
+        contactSpeed: opts.contactSpeed ?? 3.0,
+        maximumLinearSpeed: opts.maximumLinearSpeed ?? 400,
+        enableSleep: opts.enableSleep ?? true,
+        enableContinuous: opts.enableContinuous ?? true,
+    };
+}
+/** Whether `world.start()` has already run. Reads the world's internal started
+ * flag; there is no public accessor. */
+function isWorldStarted(world) {
+    return world._started === true;
+}
+//# sourceMappingURL=install.js.map

package/install.js.map

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

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@vworlds/vecs-physics",
+  "version": "1.0.16",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vworlds/vecs.git"
+  },
+  "dependencies": {
+    "@vworlds/vecs": "1.0.16",
+    "box2d3-wasm": "^5.2.0"
+  },
+  "license": "MIT"
+}

package/systems/debug.d.ts

@@ -0,0 +1,5 @@
+import { type IPhase, type System, type World } from "@vworlds/vecs";
+import { type PhysicsState } from "../adapter/state.js";
+/** Create `PhysicsDebugValidation` on `world` in `phase`.
+ * Returns the system so the caller can tag its entity. */
+export declare function installDebugValidation(world: World, state: PhysicsState, phase: IPhase): System;

package/systems/debug.js

@@ -0,0 +1,266 @@
+// `PhysicsDebugValidation` — per-step structural validation with warn-once
+// semantics. Registered ONLY when `installPhysics` is called with
+// `{ debug: true }`. In normal mode this system is never installed, and no
+// validation overhead exists.
+//
+// Phase: `physics-pre`, AFTER all other physics-pre systems (last position).
+// This ensures the validator sees the world after lifecycle/sync have run, so
+// ephemeral intermediate states during entity construction are not flagged.
+//
+// Seven issue codes (docs/debug-validation.md):
+//   1. shape-without-parent-body     — geometry entity whose immediate parent
+//                                      lacks Body (or has no parent at all).
+//   2. dynamic-body-without-density  — dynamic Body with no valid shape child:
+//                                      either no children, or every child shape
+//                                      has Material.density === 0. Sensor shapes
+//                                      with positive density DO contribute mass
+//                                      (Box2D parity: skip only density === 0).
+//   3. chain-too-few-points          — Chain.points.length < 4.
+//   4. polygon-invalid               — Polygon.vertices fail validateHull.
+//   5. shape-position-on-body        — entity has Body AND ShapePosition or
+//                                      ShapeRotation.
+//   6. position-on-shape-entity      — entity has a geometry component AND
+//                                      Position.
+//   7. force-without-target          — force/impulse entity has no Body and no
+//                                      immediate Body parent.
+//
+// Re-arm semantics: when a (eid, code) pair that was previously warned becomes
+// valid for that code (issue cleared), we call rearm() so a future relapse can
+// warn again. The WarnDedupe key is `(eid, code)`, so each code is independent.
+//
+// Design points:
+//   - Uses world.filter() scans (non-reactive) — same pattern as ForceGather.
+//     An entity enters the relevant filter when it carries the matching
+//     component(s), and the validator re-checks it every step.
+//   - WarnDedupe instance is owned by PhysicsState (survives across systems).
+//   - The injectable WarnSink in WarnDedupe is the test hook; pass it via
+//     PhysicsOptions.debugSink.
+//   - Does NOT modify any engine state — read-only pass.
+//
+// Upstream docs: docs/debug-validation.md.
+// Re-uses: validateHull / computeHull from engine/geometry.ts.
+import { ChildOf, } from "@vworlds/vecs";
+import { Body, BodyType, Position } from "../components/body.js";
+import { AngularImpulse, Force, Impulse, Torque } from "../components/force.js";
+import { Box, Capsule, Chain, Circle, Polygon, Segment } from "../components/geometry.js";
+import { Material } from "../components/material.js";
+import { ShapePosition, ShapeRotation } from "../components/shape_pose.js";
+// ─── Issue codes ──────────────────────────────────────────────────────────────
+const CODE_SHAPE_WITHOUT_PARENT_BODY = "shape-without-parent-body";
+const CODE_DYNAMIC_BODY_WITHOUT_DENSITY = "dynamic-body-without-density";
+const CODE_CHAIN_TOO_FEW_POINTS = "chain-too-few-points";
+const CODE_POLYGON_INVALID = "polygon-invalid";
+const CODE_SHAPE_POSITION_ON_BODY = "shape-position-on-body";
+const CODE_POSITION_ON_SHAPE_ENTITY = "position-on-shape-entity";
+const CODE_FORCE_WITHOUT_TARGET = "force-without-target";
+// ─── System factory ───────────────────────────────────────────────────────────
+/** Create `PhysicsDebugValidation` on `world` in `phase`.
+ * Returns the system so the caller can tag its entity. */
+export function installDebugValidation(world, state, phase) {
+    // ── Filters (non-reactive; walked every step) ─────────────────────────────
+    // Geometry entities: any entity with at least one geometry component.
+    const geomFilter = world.filter({ any: [Box, Circle, Capsule, Segment, Polygon, Chain] });
+    // Body entities: any entity with Body.
+    const bodyFilter = world.filter(Body);
+    // Force-class entities: any entity with a force, torque, impulse, or angular impulse.
+    const forceFilter = world.filter({ any: [Force, Torque, Impulse, AngularImpulse] });
+    // Body entities that also carry ShapePosition or ShapeRotation.
+    const bodyPoseFilter = world.filter({
+        all: [Body, { any: [ShapePosition, ShapeRotation] }],
+    });
+    // Track body-pose entities seen in the previous step so we can rearm those
+    // that leave the filter (ShapePosition/ShapeRotation removed). Re-entry into
+    // the filter will then produce a fresh warning, completing the re-arm cycle.
+    const prevBodyPoseEids = new Set();
+    return world
+        .system("PhysicsDebugValidation")
+        .phase(phase)
+        .run(() => {
+        _validateGeomEntities(state, geomFilter, state.warn);
+        _validateBodyEntities(geomFilter, bodyFilter, state.warn);
+        _validateBodyShapePositionEntities(bodyPoseFilter, prevBodyPoseEids, state.warn);
+        _validateForceEntities(forceFilter, state.warn);
+    });
+}
+// ─── Geometry-entity validation ───────────────────────────────────────────────
+/** Walk every entity with a geometry component and check:
+ *   - shape-without-parent-body (code 1)
+ *   - chain-too-few-points      (code 3)
+ *   - polygon-invalid           (code 4)
+ *   - position-on-shape-entity  (code 6) */
+function _validateGeomEntities(state, geomFilter, dedupe) {
+    geomFilter.forEach((e) => {
+        const eid = e.eid;
+        // ── shape-without-parent-body (code 1) ───────────────────────────────────
+        const parent = e.parent(ChildOf);
+        const parentHasBody = parent !== undefined && parent.get(Body) !== undefined;
+        if (!parentHasBody) {
+            dedupe.warnOnce(eid, CODE_SHAPE_WITHOUT_PARENT_BODY, `Entity${eid} has geometry but its immediate parent does not have Body.`);
+        }
+        else {
+            dedupe.rearm(eid, CODE_SHAPE_WITHOUT_PARENT_BODY);
+        }
+        // ── chain-too-few-points (code 3) ────────────────────────────────────────
+        const chain = e.get(Chain);
+        if (chain !== undefined) {
+            if (chain.points.length < 4) {
+                dedupe.warnOnce(eid, CODE_CHAIN_TOO_FEW_POINTS, `Entity${eid} has Chain with ${chain.points.length} point(s); at least 4 are required.`);
+            }
+            else {
+                dedupe.rearm(eid, CODE_CHAIN_TOO_FEW_POINTS);
+            }
+        }
+        // ── polygon-invalid (code 4) ─────────────────────────────────────────────
+        const polygon = e.get(Polygon);
+        if (polygon !== undefined) {
+            const valid = isValidPolygon(state, polygon.vertices);
+            if (!valid) {
+                dedupe.warnOnce(eid, CODE_POLYGON_INVALID, `Entity${eid} has Polygon with invalid or non-convex vertices.`);
+            }
+            else {
+                dedupe.rearm(eid, CODE_POLYGON_INVALID);
+            }
+        }
+        // ── position-on-shape-entity (code 6) ────────────────────────────────────
+        const hasPosition = e.get(Position) !== undefined;
+        if (hasPosition) {
+            dedupe.warnOnce(eid, CODE_POSITION_ON_SHAPE_ENTITY, `Entity${eid} has a geometry component and Position; use ShapePosition for shape-local offsets.`);
+        }
+        else {
+            dedupe.rearm(eid, CODE_POSITION_ON_SHAPE_ENTITY);
+        }
+    });
+}
+// ─── Body-entity validation ───────────────────────────────────────────────────
+/** Walk every entity with a Body component and check:
+ *   - dynamic-body-without-density (code 2)
+ *
+ * A dynamic body must have at least one child shape with density > 0. Sensor
+ * shapes count — Box2D parity skips only density === 0, not isSensor shapes.
+ *
+ * To find child shapes without engine-state access, we build a map of
+ * body-eid → geometry child entities by walking the geometry filter and checking
+ * which have a direct Body parent. This is a read-only ECS walk with no
+ * dependency on PhysicsState internals. */
+function _validateBodyEntities(geomFilter, bodyFilter, dedupe) {
+    // Build a map: body-eid → list of geometry child entities (per this step).
+    const geomChildrenByBody = new Map();
+    geomFilter.forEach((e) => {
+        const parent = e.parent(ChildOf);
+        if (parent === undefined || parent.get(Body) === undefined) {
+            return;
+        }
+        const bodyEid = parent.eid;
+        let list = geomChildrenByBody.get(bodyEid);
+        if (list === undefined) {
+            list = [];
+            geomChildrenByBody.set(bodyEid, list);
+        }
+        list.push(e);
+    });
+    // Walk every body entity and check dynamic-body-without-density.
+    bodyFilter.forEach((e) => {
+        const eid = e.eid;
+        const body = e.get(Body);
+        if (body.type !== BodyType.Dynamic) {
+            return;
+        }
+        const children = geomChildrenByBody.get(eid);
+        // A dynamic body with no geometry children always warns.
+        if (children === undefined || children.length === 0) {
+            dedupe.warnOnce(eid, CODE_DYNAMIC_BODY_WITHOUT_DENSITY, `Entity${eid} is a dynamic body with no shape children; it will have zero mass.`);
+            return;
+        }
+        // Check if ANY child shape has density > 0.
+        // Sensor shapes with positive density DO contribute mass (Box2D parity:
+        // b2UpdateBodyMassData skips only density === 0, not isSensor shapes).
+        // Missing Material means default density = 1 (fine).
+        let hasValidDensity = false;
+        for (const child of children) {
+            const mat = child.get(Material);
+            const density = mat !== undefined ? mat.density : 1; // default density is 1
+            if (density > 0) {
+                hasValidDensity = true;
+                break;
+            }
+        }
+        if (!hasValidDensity) {
+            dedupe.warnOnce(eid, CODE_DYNAMIC_BODY_WITHOUT_DENSITY, `Entity${eid} is a dynamic body whose shapes all have density 0; it will have zero mass.`);
+        }
+    });
+}
+// ─── Body-with-shape-pose validation ─────────────────────────────────────────
+/** Walk entities that have Body AND ShapePosition or ShapeRotation (code 5).
+ *
+ * Re-arm mechanism: entities that leave this filter (ShapePosition/ShapeRotation
+ * removed) are detected via `prevBodyPoseEids`. They are rearmed so re-entry
+ * into the filter produces a fresh warning if the issue recurs. */
+function _validateBodyShapePositionEntities(bodyPoseFilter, prevBodyPoseEids, dedupe) {
+    const currentEids = new Set();
+    bodyPoseFilter.forEach((e) => {
+        const eid = e.eid;
+        currentEids.add(eid);
+        const hasShapePos = e.get(ShapePosition) !== undefined;
+        const hasShapeRot = e.get(ShapeRotation) !== undefined;
+        const component = hasShapePos && hasShapeRot
+            ? "ShapePosition and ShapeRotation"
+            : hasShapePos
+                ? "ShapePosition"
+                : "ShapeRotation";
+        dedupe.warnOnce(eid, CODE_SHAPE_POSITION_ON_BODY, `Entity${eid} has Body and ${component}; move ${component} to a child shape entity.`);
+    });
+    // Rearm any entities that left the filter this step (ShapePosition/ShapeRotation
+    // was removed). If they re-enter in a future step, a fresh warning can fire.
+    for (const eid of prevBodyPoseEids) {
+        if (!currentEids.has(eid)) {
+            dedupe.rearm(eid, CODE_SHAPE_POSITION_ON_BODY);
+        }
+    }
+    // Update the previous-seen set for next step.
+    prevBodyPoseEids.clear();
+    for (const eid of currentEids) {
+        prevBodyPoseEids.add(eid);
+    }
+}
+// ─── Polygon hull validation ──────────────────────────────────────────────────
+/**
+ * Returns true if `vertices` forms a valid convex polygon according to Box2D.
+ * Delegates to `b2ComputeHull` (WASM); a hull with count >= 3 is valid. Allocates
+ * and frees temporary b2Vec2 objects via the WASM heap.
+ */
+function isValidPolygon(state, vertices) {
+    if (vertices.length < 3) {
+        return false;
+    }
+    const box2d = state.box2d;
+    const points = vertices.map((v) => new box2d.b2Vec2(v.x, v.y));
+    try {
+        const hull = box2d.b2ComputeHull(points);
+        try {
+            return hull.count >= 3;
+        }
+        finally {
+            hull.delete();
+        }
+    }
+    finally {
+        for (const p of points) {
+            p.delete();
+        }
+    }
+}
+// ─── Force-target validation ─────────────────────────────────────────────────
+function _validateForceEntities(forceFilter, dedupe) {
+    forceFilter.forEach((e) => {
+        const eid = e.eid;
+        const parent = e.parent(ChildOf);
+        const hasTarget = e.get(Body) !== undefined || (parent !== undefined && parent.get(Body) !== undefined);
+        if (!hasTarget) {
+            dedupe.warnOnce(eid, CODE_FORCE_WITHOUT_TARGET, `Entity${eid} has Force/Torque/Impulse/AngularImpulse but no Body or immediate Body parent.`);
+        }
+        else {
+            dedupe.rearm(eid, CODE_FORCE_WITHOUT_TARGET);
+        }
+    });
+}
+//# sourceMappingURL=debug.js.map