@woosh/meep-engine 2.145.0 → 2.146.0

package/src/engine/physics/body/BodyStorage.d.ts

@@ -61,6 +61,7 @@ export class BodyStorage {
     __awake_count: number;
     __free_heap: Uint32Array;
     __free_count: number;
+    __entity_to_index: Map<any, any>;
     /**
      * Currently allocated body count (live, regardless of awake/sleeping).
      * @returns {number}
@@ -109,6 +110,14 @@ export class BodyStorage {
      * @returns {number} entity for the body, or -1 if the slot is free.
      */
     entity_at(index: number): number;
+    /**
+     * Body index for `entity`, or {@link BODY_INDEX_ABSENT} if no live body owns
+     * it. O(1) reverse of {@link entity_at} — the lookup callers use on the
+     * link / attach / joint paths instead of scanning the slot table.
+     * @param {number} entity
+     * @returns {number}
+     */
+    index_of_entity(entity: number): number;
     /**
      * @param {number} index
      * @returns {number}

package/src/engine/physics/body/BodyStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BodyStorage.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/body/BodyStorage.js"],"names":[],"mappings":"AA2BA;;;;;;GAMG;AACH,oCAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAlCD;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AA+BpC;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;OAGG;IACH,+BAFW,MAAM,EA+BhB;IAxBG,mBAAqB;IAGrB,gBAAgB;IAEhB,uBAAqC;IACrC,0BAAwC;IACxC,oBAAkC;IAClC,qBAAmC;IAGnC,oBAAkC;IAGlC,0BAAwC;IACxC,wBAAsC;IACtC,sBAAsB;IAGtB,yBAAuC;IACvC,qBAAqB;IAMzB;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;;;;;;OAOG;IACH,iBAHW,MAAM,GACJ,MAAM,CAyBlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAoBhB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,OAAO,CAWnB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,QAAQ,GAAC,MAAM,CAI3B;IAED;;;OAGG;IACH,gBAHW,MAAM,QACN,QAAQ,GAAC,MAAM,QAIzB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAShB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,0BAOC;IAED;;OAEG;IACH,eAiCC;IAID;;;OAGG;IACH,oBAgBC;IAED;;;OAGG;IACH,mBAqBC;CACJ;yBAzawB,oBAAoB"}
+{"version":3,"file":"BodyStorage.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/body/BodyStorage.js"],"names":[],"mappings":"AA2BA;;;;;;GAMG;AACH,oCAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAlCD;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AA+BpC;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;OAGG;IACH,+BAFW,MAAM,EAqChB;IA9BG,mBAAqB;IAGrB,gBAAgB;IAEhB,uBAAqC;IACrC,0BAAwC;IACxC,oBAAkC;IAClC,qBAAmC;IAGnC,oBAAkC;IAGlC,0BAAwC;IACxC,wBAAsC;IACtC,sBAAsB;IAGtB,yBAAuC;IACvC,qBAAqB;IAMrB,iCAAkC;IAMtC;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;;;;;;OAOG;IACH,iBAHW,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAwBhB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,OAAO,CAWnB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,QAAQ,GAAC,MAAM,CAI3B;IAED;;;OAGG;IACH,gBAHW,MAAM,QACN,QAAQ,GAAC,MAAM,QAIzB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAShB;IAED;;;OAGG;IACH,qBAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,0BAOC;IAED;;OAEG;IACH,eAiCC;IAID;;;OAGG;IACH,oBAgBC;IAED;;;OAGG;IACH,mBAqBC;CACJ;yBAhcwB,oBAAoB"}

package/src/engine/physics/body/BodyStorage.js

@@ -106,6 +106,12 @@ export class BodyStorage {
         this.__free_heap = new Uint32Array(cap);
         this.__free_count = 0;
 
+        // Entity → body-index map (one body per entity). Keeps {@link
+        // index_of_entity} O(1) instead of an O(N) scan over the slot table on
+        // every collider attach / detach and joint link. Maintained on
+        // allocate / free; never grows with the typed arrays (a plain Map).
+        this.__entity_to_index = new Map();
+
         // Initialise reverse map to BODY_INDEX_ABSENT.
         this.__awake_pos.fill(BODY_INDEX_ABSENT);
     }
@@ -167,6 +173,7 @@ export class BodyStorage {
         this.__kinds[index] = BodyKind.Dynamic;
         this.__flags[index] = 0;
         this.__alive[index] = 1;
+        this.__entity_to_index.set(entity, index);
 
         // Insert into awake set.
         const awake_pos = this.__awake_count++;
@@ -196,6 +203,10 @@ export class BodyStorage {
 
         this.__alive[index] = 0;
 
+        // Drop the entity → index mapping (the slot still holds the old entity
+        // value until reallocation, so delete by it now while it's valid).
+        this.__entity_to_index.delete(this.__entities[index]);
+
         // Bump generation; wraps mod 256.
         this.__generations[index] = (this.__generations[index] + 1) & GENERATION_MASK;
 
@@ -229,6 +240,18 @@ export class BodyStorage {
         return this.__entities[index];
     }
 
+    /**
+     * Body index for `entity`, or {@link BODY_INDEX_ABSENT} if no live body owns
+     * it. O(1) reverse of {@link entity_at} — the lookup callers use on the
+     * link / attach / joint paths instead of scanning the slot table.
+     * @param {number} entity
+     * @returns {number}
+     */
+    index_of_entity(entity) {
+        const idx = this.__entity_to_index.get(entity);
+        return idx === undefined ? BODY_INDEX_ABSENT : idx;
+    }
+
     /**
      * @param {number} index
      * @returns {number}

package/src/engine/physics/broadphase/generate_pairs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate_pairs.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/generate_pairs.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,uIARW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAY;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,+CAElF,MAAM,OAAO,MAAM,KAAK,OAAO,QAsEhD"}
+{"version":3,"file":"generate_pairs.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/generate_pairs.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,uIARW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAY;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,+CAElF,MAAM,OAAO,MAAM,KAAK,OAAO,QA4EhD"}

package/src/engine/physics/broadphase/generate_pairs.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../core/assert.js";
 import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
 
 const scratch_aabb = new Float64Array(6);
@@ -65,6 +66,11 @@ export function generate_pairs(
                 dynamic_bvh,
                 scratch_aabb
             );
+            // The BVH query writes leaves unconditionally — at capacity it both
+            // drops leaves (typed-array OOB writes no-op) AND returns a count
+            // past the buffer end, so the loop below would read `undefined`
+            // candidates and build garbage pairs. Guard the buffer size.
+            assert.lessThan(n, candidates.length, 'generate_pairs: dynamic broadphase overflowed the candidate buffer');
             for (let c = 0; c < n; c++) {
                 const other = candidates[c];
                 if (other === my_packed) continue;
@@ -85,6 +91,7 @@ export function generate_pairs(
                 static_bvh,
                 scratch_aabb
             );
+            assert.lessThan(n, candidates.length, 'generate_pairs: static broadphase overflowed the candidate buffer');
             for (let c = 0; c < n; c++) {
                 const other = candidates[c];
                 const idA = my_packed < other ? my_packed : other;

package/src/engine/physics/ccd/linear_sweep.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Sweep `shape` (held at the fixed `rotation`) linearly from `(fx,fy,fz)` to
+ * `(tx,ty,tz)` through both broadphase trees, ignoring colliders owned by
+ * `exclude_entity`.
+ *
+ * Returns the traversable fraction of the segment in `[0, 1]`: `1` means the
+ * path is clear; a value `< 1` means a blocker was hit at that fraction and
+ * `result` has been filled — `result.position` is the swept-shape centre at
+ * first contact, `result.normal` is the blocker's outward surface normal
+ * (B → A), `result.entity` / `result.body_id` the blocker.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation fixed orientation
+ * @param {number} fx
+ * @param {number} fy
+ * @param {number} fz
+ * @param {number} tx
+ * @param {number} ty
+ * @param {number} tz
+ * @param {number} exclude_entity entity to ignore (the swept body itself)
+ * @param {PhysicsSurfacePoint} result populated on hit; untouched on a clear path
+ * @returns {number} traversable fraction in [0, 1]
+ */
+export function ccd_sweep_segment(system: import("../ecs/PhysicsSystem.js").PhysicsSystem, shape: import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D, rotation: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}, fx: number, fy: number, fz: number, tx: number, ty: number, tz: number, exclude_entity: number, result: PhysicsSurfacePoint): number;
+/**
+ * Post-solve continuous-collision pass over the awake set. For each awake
+ * Dynamic body flagged {@link RigidBodyFlags.CCD} that moved more than
+ * {@link CCD_MIN_SWEEP_DISTANCE} this step, sweep its primary collider along the
+ * step's net translation and stop it at the first blocker (clamp pose + remove
+ * inbound normal velocity).
+ *
+ * Start-of-step positions are captured into `system.__ccd_start_pos` (3 doubles
+ * per body index) before the substep loop; this pass reads the final pose from
+ * the live Transform. Iterates the awake list in storage order, so it is
+ * deterministic.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ */
+export function ccd_resolve(system: import("../ecs/PhysicsSystem.js").PhysicsSystem): void;
+/**
+ * Continuous collision detection — linear shape-cast (the "speculative margin
+ * floor, upgraded to an opt-in per-body sweep" item from PLAN.md).
+ *
+ * The discrete pipeline detects contacts by overlap at step boundaries: a body
+ * that moves more than its own thickness in one step can start a step on one
+ * side of a thin wall and end on the other, never overlapping it on any frame
+ * the broadphase samples — it tunnels. The speculative fat-AABB margin
+ * (`compute_fat_world_aabb`) covers moderate speeds; genuinely fast movers
+ * (bullets, dropped debris, a body flung by an explosion) need a swept test.
+ *
+ * Approach (Box2D `b2_continuousPhysics`-style conservative advancement): after
+ * the substep solver has produced each body's final pose, sweep a CCD-flagged
+ * fast mover's primary collider along its NET step translation
+ * (start-of-step → final pose) using the existing {@link shape_cast} TOI engine.
+ * On the first blocker, clamp the body to the contact pose and remove the
+ * inbound normal component of its velocity (an inelastic stop) — the next
+ * discrete step then resolves the now-touching contact with the real
+ * material / restitution.
+ *
+ * Scope (v1, deliberate):
+ *   - LINEAR sweep only: the orientation is held fixed through the sweep (the
+ *     per-step angular motion is small at the fixed-step rate).
+ *   - PRIMARY same-entity collider: a compound body sweeps its first collider;
+ *     child-entity colliders (whose transform is synced outside the step) are
+ *     not swept.
+ *   - EXACT against static geometry (the static BVH holds tight, never-moved
+ *     leaves); APPROXIMATE against other dynamic bodies (they have moved this
+ *     step too, but the sweep sees their start-of-step broadphase AABBs) — the
+ *     speculative-margin floor for the dynamic-vs-dynamic case.
+ *   - The CCD stop itself is inelastic; the impact does not bounce. Restitution
+ *     applies on the next discrete contact.
+ */
+/**
+ * Minimum per-step displacement (metres) before a CCD sweep is worth running.
+ * Its ONLY job is to skip a body that didn't meaningfully move — a resting /
+ * sleeping-soon body whose displacement is sub-millimetre jitter — which avoids
+ * a degenerate zero-length sweep and saves the query cost.
+ *
+ * It must NOT be tied to the body's own size. Tunnelling risk is governed by the
+ * *obstacle's* thickness, not the mover's: a 2 m sphere drifting at 0.5 m/step
+ * still passes clean through a 1 cm floor. A small absolute slop catches that;
+ * gating on a fraction of the body's extent would (wrongly) wait until the body
+ * moved more than its own radius and miss every thin-obstacle tunnel below that
+ * speed. The discrete narrowphase still owns any obstacle thicker than a body's
+ * per-step move, so CCD reliably prevents tunnelling of obstacles thicker than
+ * this slop.
+ * @type {number}
+ */
+export const CCD_MIN_SWEEP_DISTANCE: number;
+import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
+//# sourceMappingURL=linear_sweep.d.ts.map

package/src/engine/physics/ccd/linear_sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear_sweep.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ccd/linear_sweep.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0CAbW,OAAO,yBAAyB,EAAE,aAAa,SAC/C,OAAO,gDAAgD,EAAE,eAAe,YACxE;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,MACrC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,kBACN,MAAM,UACN,mBAAmB,GACjB,MAAM,CAmClB;AAED;;;;;;;;;;;;;GAaG;AACH,oCAFW,OAAO,yBAAyB,EAAE,aAAa,QAwEzD;AAvOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qCAFU,MAAM,CAE2B;oCArDP,mCAAmC"}

package/src/engine/physics/ccd/linear_sweep.js

@@ -0,0 +1,238 @@
+import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
+import { BodyKind } from "../ecs/BodyKind.js";
+import { RigidBodyFlags } from "../ecs/RigidBodyFlags.js";
+import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
+import { shape_cast } from "../queries/shape_cast.js";
+
+/**
+ * Continuous collision detection — linear shape-cast (the "speculative margin
+ * floor, upgraded to an opt-in per-body sweep" item from PLAN.md).
+ *
+ * The discrete pipeline detects contacts by overlap at step boundaries: a body
+ * that moves more than its own thickness in one step can start a step on one
+ * side of a thin wall and end on the other, never overlapping it on any frame
+ * the broadphase samples — it tunnels. The speculative fat-AABB margin
+ * (`compute_fat_world_aabb`) covers moderate speeds; genuinely fast movers
+ * (bullets, dropped debris, a body flung by an explosion) need a swept test.
+ *
+ * Approach (Box2D `b2_continuousPhysics`-style conservative advancement): after
+ * the substep solver has produced each body's final pose, sweep a CCD-flagged
+ * fast mover's primary collider along its NET step translation
+ * (start-of-step → final pose) using the existing {@link shape_cast} TOI engine.
+ * On the first blocker, clamp the body to the contact pose and remove the
+ * inbound normal component of its velocity (an inelastic stop) — the next
+ * discrete step then resolves the now-touching contact with the real
+ * material / restitution.
+ *
+ * Scope (v1, deliberate):
+ *   - LINEAR sweep only: the orientation is held fixed through the sweep (the
+ *     per-step angular motion is small at the fixed-step rate).
+ *   - PRIMARY same-entity collider: a compound body sweeps its first collider;
+ *     child-entity colliders (whose transform is synced outside the step) are
+ *     not swept.
+ *   - EXACT against static geometry (the static BVH holds tight, never-moved
+ *     leaves); APPROXIMATE against other dynamic bodies (they have moved this
+ *     step too, but the sweep sees their start-of-step broadphase AABBs) — the
+ *     speculative-margin floor for the dynamic-vs-dynamic case.
+ *   - The CCD stop itself is inelastic; the impact does not bounce. Restitution
+ *     applies on the next discrete contact.
+ */
+
+/**
+ * Minimum per-step displacement (metres) before a CCD sweep is worth running.
+ * Its ONLY job is to skip a body that didn't meaningfully move — a resting /
+ * sleeping-soon body whose displacement is sub-millimetre jitter — which avoids
+ * a degenerate zero-length sweep and saves the query cost.
+ *
+ * It must NOT be tied to the body's own size. Tunnelling risk is governed by the
+ * *obstacle's* thickness, not the mover's: a 2 m sphere drifting at 0.5 m/step
+ * still passes clean through a 1 cm floor. A small absolute slop catches that;
+ * gating on a fraction of the body's extent would (wrongly) wait until the body
+ * moved more than its own radius and miss every thin-obstacle tunnel below that
+ * speed. The discrete narrowphase still owns any obstacle thicker than a body's
+ * per-step move, so CCD reliably prevents tunnelling of obstacles thicker than
+ * this slop.
+ * @type {number}
+ */
+export const CCD_MIN_SWEEP_DISTANCE = 1e-3;
+
+/**
+ * Impact distances at or below this (metres) mean the body was already
+ * overlapping the target at the start of the step — i.e. a resting / sliding
+ * contact the discrete solver owns, not a tunnel. The sweep ignores these so
+ * CCD never clamps a body to a surface it is merely sitting or sliding on.
+ * @type {number}
+ */
+const CCD_INITIAL_OVERLAP_EPS = 1e-6;
+
+// ── Module scratch ──────────────────────────────────────────────────────────
+// CCD runs inside the step loop; reuse buffers so the pass allocates nothing.
+
+/** Swept ray, re-seeded per sweep (origin, unit direction, tMax). */
+const _ray = new Ray3();
+
+/** Sweep result reused across bodies inside {@link ccd_resolve}. */
+const _hit = new PhysicsSurfacePoint();
+
+/**
+ * Entity whose colliders the current sweep must ignore (the moving body's own).
+ * Module-scoped so {@link _exclude_self} stays a stable, non-allocating
+ * reference handed to {@link shape_cast}.
+ * @type {number}
+ */
+let _exclude_entity = -1;
+
+/**
+ * Self-exclusion filter for the sweep: drop candidates owned by the moving
+ * body's own entity (otherwise the body would "hit itself" at `t = 0`).
+ * @param {number} entity
+ * @returns {boolean}
+ */
+function _exclude_self(entity) {
+    return entity !== _exclude_entity;
+}
+
+/**
+ * Sweep `shape` (held at the fixed `rotation`) linearly from `(fx,fy,fz)` to
+ * `(tx,ty,tz)` through both broadphase trees, ignoring colliders owned by
+ * `exclude_entity`.
+ *
+ * Returns the traversable fraction of the segment in `[0, 1]`: `1` means the
+ * path is clear; a value `< 1` means a blocker was hit at that fraction and
+ * `result` has been filled — `result.position` is the swept-shape centre at
+ * first contact, `result.normal` is the blocker's outward surface normal
+ * (B → A), `result.entity` / `result.body_id` the blocker.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation fixed orientation
+ * @param {number} fx
+ * @param {number} fy
+ * @param {number} fz
+ * @param {number} tx
+ * @param {number} ty
+ * @param {number} tz
+ * @param {number} exclude_entity entity to ignore (the swept body itself)
+ * @param {PhysicsSurfacePoint} result populated on hit; untouched on a clear path
+ * @returns {number} traversable fraction in [0, 1]
+ */
+export function ccd_sweep_segment(
+    system, shape, rotation,
+    fx, fy, fz, tx, ty, tz,
+    exclude_entity, result,
+) {
+    const dx = tx - fx;
+    const dy = ty - fy;
+    const dz = tz - fz;
+    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (len === 0) return 1;
+
+    const inv = 1 / len;
+    _ray[0] = fx; _ray[1] = fy; _ray[2] = fz;
+    _ray[3] = dx * inv; _ray[4] = dy * inv; _ray[5] = dz * inv;
+    _ray[6] = len; // tMax in metres — direction is unit length
+
+    _exclude_entity = exclude_entity;
+    if (!shape_cast(system, _ray, shape, rotation, result, _exclude_self)) {
+        return 1;
+    }
+
+    // An impact at t ≈ 0 means the swept shape was already overlapping the
+    // target at the segment start — a resting / sliding contact, not a tunnel.
+    // The discrete solver owns it; clamping here would freeze a body onto a
+    // surface it is sitting or sliding on. Treat as a clear path.
+    if (result.t <= CCD_INITIAL_OVERLAP_EPS) return 1;
+
+    // result.t is the impact distance along the unit direction; normalise to a
+    // segment fraction. shape_cast reports the just-SEPARATING side of its
+    // bisection, so the swept shape at `result.t` is provably not overlapping —
+    // safe to place the body there.
+    const frac = result.t * inv;
+    return frac < 1 ? frac : 1;
+}
+
+/**
+ * Post-solve continuous-collision pass over the awake set. For each awake
+ * Dynamic body flagged {@link RigidBodyFlags.CCD} that moved more than
+ * {@link CCD_MIN_SWEEP_DISTANCE} this step, sweep its primary collider along the
+ * step's net translation and stop it at the first blocker (clamp pose + remove
+ * inbound normal velocity).
+ *
+ * Start-of-step positions are captured into `system.__ccd_start_pos` (3 doubles
+ * per body index) before the substep loop; this pass reads the final pose from
+ * the live Transform. Iterates the awake list in storage order, so it is
+ * deterministic.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ */
+export function ccd_resolve(system) {
+    const storage = system.storage;
+    const count = storage.awake_count;
+    const lists = system.__body_collider_lists;
+    const start = system.__ccd_start_pos;
+    const CCD = RigidBodyFlags.CCD;
+
+    for (let i = 0; i < count; i++) {
+        const idx = storage.awake_at(i);
+
+        const rb = system.__bodies[idx];
+        if (rb === undefined) continue;
+        if ((rb.flags & CCD) === 0) continue;
+        if (rb.kind !== BodyKind.Dynamic) continue;
+
+        const list = lists[idx];
+        if (list === undefined || list.length === 0) continue;
+        const primary = list[0];
+        const tr = primary.transform;
+        const p = tr.position;
+
+        const base = idx * 3;
+        const sx = start[base];
+        const sy = start[base + 1];
+        const sz = start[base + 2];
+        const ex = p[0];
+        const ey = p[1];
+        const ez = p[2];
+
+        const dx = ex - sx;
+        const dy = ey - sy;
+        const dz = ez - sz;
+        const disp2 = dx * dx + dy * dy + dz * dz;
+        if (disp2 === 0) continue;
+
+        // Motion gate: skip a body that barely moved (resting / negligible
+        // jitter) — avoids a degenerate sweep and the query cost. NOT tied to
+        // body size: a body tunnels a thin obstacle at speeds well below its
+        // own extent, so the threshold is a small absolute slop. A resting /
+        // sliding body that does clear it is still safe — the sweep ignores its
+        // initial-overlap contact (see CCD_INITIAL_OVERLAP_EPS).
+        if (disp2 <= CCD_MIN_SWEEP_DISTANCE * CCD_MIN_SWEEP_DISTANCE) continue;
+
+        const shape = primary.collider.shape;
+        const frac = ccd_sweep_segment(
+            system, shape, tr.rotation,
+            sx, sy, sz, ex, ey, ez,
+            primary.entity, _hit,
+        );
+        if (frac >= 1) continue; // clear path — no tunnelling this step
+
+        // Clamp the body to the first-contact pose (swept-shape centre at the
+        // TOI), so it cannot end the step on the far side of the blocker.
+        const hp = _hit.position;
+        p.set(hp[0], hp[1], hp[2]);
+
+        // Remove the inbound normal component of velocity (inelastic stop).
+        // `_hit.normal` is the blocker's outward surface normal; the body is
+        // moving into it (v·n < 0). Zeroing that component leaves the tangential
+        // slide intact and never adds energy. The next discrete step applies the
+        // real restitution / friction on the established contact.
+        const n = _hit.normal;
+        const lv = rb.linearVelocity;
+        const vn = lv[0] * n[0] + lv[1] * n[1] + lv[2] * n[2];
+        if (vn < 0) {
+            lv[0] -= vn * n[0];
+            lv[1] -= vn * n[1];
+            lv[2] -= vn * n[2];
+        }
+    }
+}

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -196,6 +196,21 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      * @type {Float64Array}
      */
     __pseudo_velocity: Float64Array;
+    /**
+     * Master switch for the continuous-collision pass. When false the
+     * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
+     * @type {boolean}
+     */
+    ccdEnabled: boolean;
+    /**
+     * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
+     * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
+     * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
+     * here to the final pose. Grows to `storage.high_water_mark * 3`; only
+     * CCD-flagged slots are written each step.
+     * @type {Float64Array}
+     */
+    __ccd_start_pos: Float64Array;
     /**
      * Bound reference to {@link __pair_filter} so we hand the same
      * callable to {@link generate_pairs} each step without per-step
@@ -322,9 +337,9 @@ export class PhysicsSystem extends System<any, any, any, any, any> {
      */
     detach_collider(body_entity: number, collider: Collider): void;
     /**
-     * Linear scan over body slots looking for the one whose entity matches.
-     * O(N) where N is the live body count — only called on the link/unlink
-     * paths, not during simulation, so the scan cost is bounded.
+     * Resolve an entity to its body index, or -1 if no live body owns it.
+     * O(1) via {@link BodyStorage#index_of_entity}'s entity → index map — used
+     * on the collider attach / detach and joint link paths.
      *
      * @private
      * @param {number} entity

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

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

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -21,6 +21,7 @@ import { narrowphase_step } from "../narrowphase/narrowphase_step.js";
 import { overlap_shape as overlap_shape_query } from "../queries/overlap_shape.js";
 import { raycast as raycast_query } from "../queries/raycast.js";
 import { shape_cast as shape_cast_query } from "../queries/shape_cast.js";
+import { ccd_resolve } from "../ccd/linear_sweep.js";
 import { returnTrue } from "../../../core/function/returnTrue.js";
 import {
     prepare_contacts,
@@ -294,6 +295,23 @@ export class PhysicsSystem extends System {
          */
         this.__pseudo_velocity = new Float64Array(0);
 
+        /**
+         * Master switch for the continuous-collision pass. When false the
+         * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
+         * @type {boolean}
+         */
+        this.ccdEnabled = true;
+
+        /**
+         * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
+         * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
+         * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
+         * here to the final pose. Grows to `storage.high_water_mark * 3`; only
+         * CCD-flagged slots are written each step.
+         * @type {Float64Array}
+         */
+        this.__ccd_start_pos = new Float64Array(0);
+
         /**
          * Bound reference to {@link __pair_filter} so we hand the same
          * callable to {@link generate_pairs} each step without per-step
@@ -586,20 +604,16 @@ export class PhysicsSystem extends System {
     }
 
     /**
-     * Linear scan over body slots looking for the one whose entity matches.
-     * O(N) where N is the live body count — only called on the link/unlink
-     * paths, not during simulation, so the scan cost is bounded.
+     * Resolve an entity to its body index, or -1 if no live body owns it.
+     * O(1) via {@link BodyStorage#index_of_entity}'s entity → index map — used
+     * on the collider attach / detach and joint link paths.
      *
      * @private
      * @param {number} entity
      * @returns {number} body index or -1
      */
     __find_body_index_by_entity(entity) {
-        const hwm = this.storage.high_water_mark;
-        for (let i = 0; i < hwm; i++) {
-            if (this.storage.entity_at(i) === entity) return i;
-        }
-        return -1;
+        return this.storage.index_of_entity(entity);
     }
 
     /**
@@ -1347,6 +1361,34 @@ export class PhysicsSystem extends System {
         const h = dt / N;
         const count_after_wake = this.storage.awake_count;
 
+        // CCD: capture start-of-step positions for flagged bodies over the
+        // post-wake awake set (poses are unchanged until the substep loop below
+        // integrates them). The CCD pass after the solver sweeps from here to
+        // each body's final pose. Reads the primary collider's transform so the
+        // start matches the end the resolve pass reads. Zero-cost when no body
+        // is flagged.
+        const ccd_on = this.ccdEnabled;
+        if (ccd_on) {
+            const ccd_need = this.storage.high_water_mark * 3;
+            if (this.__ccd_start_pos.length < ccd_need) {
+                this.__ccd_start_pos = new Float64Array(ccd_need);
+            }
+            const ccd_start = this.__ccd_start_pos;
+            for (let i = 0; i < count_after_wake; i++) {
+                const idx = this.storage.awake_at(i);
+                const rb = this.__bodies[idx];
+                if (rb.kind !== BodyKind.Dynamic) continue;
+                if ((rb.flags & RigidBodyFlags.CCD) === 0) continue;
+                const list = this.__body_collider_lists[idx];
+                if (list === undefined || list.length === 0) continue;
+                const cp = list[0].transform.position;
+                const cb = idx * 3;
+                ccd_start[cb] = cp[0];
+                ccd_start[cb + 1] = cp[1];
+                ccd_start[cb + 2] = cp[2];
+            }
+        }
+
         // Size the pseudo-velocity buffer ONCE (it may reallocate on growth),
         // then capture the reference. Inside the loop we only zero its live
         // region per substep — re-capturing is unnecessary since it won't
@@ -1403,6 +1445,15 @@ export class PhysicsSystem extends System {
         // the approach velocity captured at prepare time.
         apply_restitution(this.manifolds, this);
 
+        // Stage 8.5: continuous collision — sweep CCD-flagged fast movers along
+        // their net step translation and stop them at the first blocker, so they
+        // can't tunnel through thin geometry between discrete steps. Runs on the
+        // final post-solve poses, before the sleep test sees the clamped
+        // velocities. No-op when no awake body is flagged.
+        if (ccd_on) {
+            ccd_resolve(this);
+        }
+
         // Stage 9: sleep test.
         this.__sleep_test(dt);
 

package/src/engine/physics/ecs/RigidBodyFlags.d.ts

@@ -8,6 +8,11 @@
  *   component during solve.
  * - {@link DisableSleep }: this body never enters the sleeping set. Bodies near it
  *   may still sleep when stable.
+ * - {@link CCD }: opt-in continuous collision detection. After the solver, the
+ *   body's net step translation is shape-cast against the broadphase and the
+ *   body is stopped at the first blocker, so a fast mover can't tunnel through
+ *   thin geometry between discrete steps. Off by default — it costs one swept
+ *   query per fast-moving flagged body per step. See `ccd/linear_sweep.js`.
  */
 export type RigidBodyFlags = number;
 export namespace RigidBodyFlags {
@@ -17,5 +22,6 @@ export namespace RigidBodyFlags {
     let LockRotY: number;
     let LockRotZ: number;
     let DisableSleep: number;
+    let CCD: number;
 }
 //# sourceMappingURL=RigidBodyFlags.d.ts.map

package/src/engine/physics/ecs/RigidBodyFlags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RigidBodyFlags.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodyFlags.js"],"names":[],"mappings":";;;;;;;;;;;6BAYU,MAAM"}
+{"version":3,"file":"RigidBodyFlags.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodyFlags.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;6BAiBU,MAAM"}