@woosh/meep-engine 2.138.20 → 2.139.0

package/src/engine/navigation/grid/find_path_on_grid_astar.js

@@ -241,6 +241,13 @@ export function find_path_on_grid_astar(
         // Grab the lowest f(x) to process next.  Heap keeps this sorted for us.
         const currentNode = open.pop_min();
 
+        // Lazy-push: a node may be in the heap multiple times if its g-score was improved after an earlier
+        // push. The lowest-score entry is popped first; later popped duplicates land on an already-closed
+        // node and must be skipped.
+        if (closed.get(currentNode)) {
+            continue;
+        }
+
         if (currentNode === goal) {
             // End case - result has been found, return the traced path.
             return compute_path(currentNode, g_score, width, height);
@@ -285,8 +292,10 @@ export function find_path_on_grid_astar(
 
                 const refined_heuristic = cost_so_far + remaining_heuristic;
 
-                // Pushing to heap will put it in proper place based on the 'f' value.
-                open.insert_or_update(neighbor, refined_heuristic)
+                // Lazy push: always insert. If neighbor was already on the open list, the older (worse-score)
+                // entry will be skipped when popped (see closed-check at the top of the loop). This avoids
+                // an O(n) find_index_by_id scan per relaxation.
+                open.insert(neighbor, refined_heuristic);
             }
 
         }

package/src/engine/navigation/mesh/bt_mesh_face_find_path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AAsHA;;;;;;;;;;;GAWG;AACH,+CANW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,6BAEJ,MAAM,CA0ElB"}
+{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AAsHA;;;;;;;;;;;GAWG;AACH,+CANW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,6BAEJ,MAAM,CAoFlB"}

package/src/engine/navigation/mesh/bt_mesh_face_find_path.js

@@ -156,6 +156,13 @@ export function bt_mesh_face_find_path(
 
         const current_node = open.pop_min();
 
+        // Lazy-push: a node may be in the heap multiple times if its g-score was improved after an earlier
+        // push. The lowest-score entry is popped first; later popped duplicates land on an already-closed
+        // node and must be skipped.
+        if (closed.has(current_node)) {
+            continue;
+        }
+
         if (current_node === goal_face_id) {
             // Reached the goal
             return construct_path(output, goal_face_id, g_score, topology);
@@ -190,7 +197,10 @@ export function bt_mesh_face_find_path(
 
                 const refined_heuristic = cost_so_far + remaining_heuristic;
 
-                open.insert_or_update(neighbor, refined_heuristic);
+                // Lazy push: always insert. If neighbor was already on the open list, the older (worse-score)
+                // entry will be skipped when popped (see closed-check at the top of the loop). This avoids
+                // an O(n) find_index_by_id scan per relaxation.
+                open.insert(neighbor, refined_heuristic);
 
             }
 

package/src/engine/physics/PLAN.md

@@ -0,0 +1,236 @@
+# Physics engine — state of play
+
+Tracker for what's built, what's pending, and what's deferred.
+
+---
+
+## Context
+
+Deterministic JS rigid-body physics engine for the meep ECS. Target: game
+scenarios with up to millions of mostly-sleeping bodies, deterministic replays
+for netcode and reproducible debugging, broad shape coverage for common game
+collisions. Pure JS — no WASM, no SIMD, no worker threads.
+
+Architectural references for design choices:
+- **Jolt** — pre-allocated body pool, active-list iteration, two-tree
+  broadphase (static + dynamic).
+- **Bullet** — `btPersistentManifold` cache layout with up to 4 points.
+- **Box2D / Catto** — sequential impulse with warm-starting, Sutherland-Hodgman
+  face clipping for box-box.
+
+---
+
+## Done
+
+### Foundations
+- `RigidBody`, `Collider`, `BodyKind`, `RigidBodyFlags`, `ColliderFlags`,
+  `SleepState`, `PhysicsEvents`.
+- `BodyStorage`: SoA pool, generation-tracked stable IDs, dense awake list,
+  min-heap free for deterministic ID reuse.
+- `PhysicsSystem`: full public API surface (gravity, force/impulse with and
+  without application point, torque, velocity setter, wake/sleep, contact
+  filter callback).
+- Binary serialization adapters for `RigidBody` and `Collider` (transient
+  runtime state deliberately excluded).
+- `PairUint32Map`: open-addressed Robin Hood + Fibonacci hash for the
+  pair → manifold-slot index (the one new collection added to `core/collection/`).
+
+### Pipeline (`PhysicsSystem.fixedUpdate`)
+1. Velocity integration (semi-implicit Euler, linear + angular, gravity,
+   damping, world-frame inverse-inertia for torque)
+2. Per-collider broadphase refit with fat AABB (Box2D-style velocity-padded
+   slack)
+3. Pair generation: per-leaf query against both BVHs (static + dynamic),
+   canonical `(min, max)` pairs, dedup via manifold touched flag
+4. Wake propagation for sleeping bodies in the pair list
+5. Narrowphase cross-product over collider lists
+6. Sequential-impulse solver (Catto-style, warm-start, friction, Baumgarte)
+7. Position integration (linear + quaternion)
+8. Sleep test (per-body velocity² below threshold for ≥ 0.5 s)
+9. Manifold diff → `ContactBegin` / `Stay` / `End` event dispatch
+10. `manifolds.advance_frame()` — roll touched bits, evict grace-expired slots
+
+### Shape coverage
+| Pair | Path | Manifold |
+|---|---|---|
+| sphere-sphere | closed-form | 1 point |
+| sphere-box | closed-form (handles centre-inside-box) | 1 point |
+| capsule-sphere | point-on-segment closed-form | 1 point |
+| capsule-capsule | segment-segment closest pair | 1 point |
+| capsule-box | iterative segment-vs-OBB (primary) + cap-centre sphere-vs-OBB at each endpoint | up to 3 |
+| box-box face-face | SAT + Sutherland-Hodgman clipping | up to 4 |
+| box-box edge-edge | SAT + midpoint fallback | 1 point |
+| anything else | GJK + EPA | 1 point (may fail on smooth shapes) |
+
+### Solver
+- Sequential impulse with warm-starting (10 velocity iterations by default).
+- Coulomb friction with disk-clamped tangent impulses.
+- Baumgarte position correction folded into the velocity solve.
+- Full angular Jacobian (`I_w⁻¹ = R · diag · R^T`) and angular impulse
+  application.
+- Public force/impulse-at-point API (`applyForceAt`, `applyImpulseAt`,
+  `applyTorque`).
+
+### Sleep + events
+- Per-island **atomic sleep**: an island sleeps when `max(|v|² + |ω|²)`
+  across all members stays below the threshold long enough; the whole
+  island sleeps in the same frame. Replaces the per-body chatter on
+  weakly-connected piles.
+- **Atomic wake**: members of a sleeping island are threaded into a
+  circular doubly-linked list (`sleep_group_next` / `sleep_group_prev`);
+  waking any one member walks the chain and wakes the rest in the same
+  call. A 100-block stack hit at the base wakes top-down in one frame
+  rather than over 100 frames of broadphase propagation.
+- `DisableSleep` on any island member exempts the whole island.
+- ContactBegin / Stay / End buffer + dispatch through both
+  `PhysicsSystem.onContactBegin/Stay/End` Signals and the per-entity
+  `entity.sendEvent(PhysicsEvents.ContactBegin, ...)` channel (when a
+  dataset is attached).
+
+### Islands
+- **Union-find** with path halving + union by min-index over the awake-body
+  + touched-contact graph (`engine/physics/island/union_find.js`).
+- **`IslandBuilder`** produces deterministic CSR-style output: bodies and
+  manifold slots grouped by island, sorted ascending within and across
+  islands. Static / kinematic bodies are constraint anchors only — they
+  don't merge islands, so disjoint piles on the same floor are separate
+  islands.
+- **Solver iterates per island**: impulse convergence happens inside an
+  island without waiting on unrelated bodies' Gauss-Seidel updates, and
+  disconnected awake bodies don't pay each other's solver cost.
+
+### Compound bodies
+- A body has 0..N attached colliders. Each collider has its own world
+  transform and its own BVH leaf.
+- Same-entity colliders, child-entity colliders (via `ParentEntity`), or
+  hybrids all supported.
+- `ColliderObserverSystem` auto-attaches colliders via the dataset when
+  paired with `PhysicsSystem` in an EntityManager.
+- Narrowphase runs the cross-product over both bodies' collider lists per
+  body-pair, accumulates candidates, reduces to ≤4 contacts by
+  depth + spread.
+
+### Public queries
+- `raycast(origin, dir, max_dist, filter?)` — nearest broadphase AABB hit
+  across both trees.
+
+### Determinism
+- Direct typed-array writes on hot paths (bypassing `Vector3#set`'s observer
+  dispatch) — Transform writes still go through `set()` because external
+  systems subscribe (TransformAttachment, EntityNode, FogOfWarRevealer,
+  ViewportPosition).
+- Active body iteration sorted by body index.
+- Pair canonicalisation `(min, max)`.
+- Min-heap free list for slot reuse.
+- No `Math.random` anywhere in the simulation step.
+- Same-runtime bit-exact determinism by design; cross-runtime is a known
+  future seam.
+
+### Migration
+- `Motion` / `MotionSystem` / `MotionSerializationAdapter` relocated from
+  the meep core (`engine/ecs/`) to the game-domain layer
+  (`mir-engine/model/game/ecs/`). meep no longer ships the legacy shim.
+
+### Bonus utilities
+- `core/geom/3d/line/line3_closest_points_segment_segment.js` — generally
+  useful 3D segment-segment closest-pair via Ericson §5.1.9.
+- `core/collection/PairUint32Map.js` — non-allocating
+  `Map<(u32, u32) → u32>` with Robin Hood + Fibonacci hash.
+
+---
+
+## Limitations / Known caveats
+
+- **Multi-collider material precision**: solver reads friction/restitution
+  from the first-attached collider of each body. Mixed-material compound
+  bodies lose accuracy here. The contact-filter callback's `colliderA/B`
+  arguments are similarly the body's primary collider, not the specific
+  collider in contact.
+- **EPA on smooth shapes**: degenerates (no flat face to converge on).
+  Mitigated by closed-form paths for sphere/cube/capsule pairs; exotic
+  convex shapes vs spheres can still fail.
+- **Box-box edge-edge contact**: single midpoint contact rather than
+  multi-point. Skewed-orientation cube collisions are stable-enough but
+  not as precise as face-face.
+- **CCD floor only**: speculative margin via the fattened AABB prevents
+  most tunnelling. No per-body swept shape-cast for very fast objects.
+- **Cross-runtime determinism is not guaranteed**: `Math.sin/cos/exp/log`
+  are ULP-correct but not bit-exact across V8 / SpiderMonkey / JSC.
+
+---
+
+## Backlog (planned, in scope)
+
+### Stability
+- [ ] **Edge-edge multi-point manifold** for skewed box contacts.
+- [ ] **Per-contact source-collider tracking** so multi-material compound
+      bodies get accurate per-contact friction/restitution. Requires
+      stashing the collider identity in the manifold contact stride.
+
+### Performance / Scale
+- [ ] **TGS (Temporal Gauss-Seidel) substepping**: optional alternative
+      to PGS for high-quality stacking with large mass ratios.
+- [ ] **Per-body linear CCD shape-cast**: optional opt-in for fast-moving
+      bodies where speculative margin isn't enough.
+- [ ] **Per-island parallel solve**: today's island data layout would
+      allow worker-based solving once `SharedArrayBuffer` is available.
+      Out-of-scope unless / until SAB is universally usable.
+
+### Features
+- [ ] **Joints**: distance, hinge, ball-socket, prismatic. The solver loop
+      is already set up to iterate `contacts ∪ joints`; only constraint
+      pre-step + warm-start hook is missing.
+- [ ] **Convex hull shape** with eigen-based principal-axes inertia
+      derivation. Hooks `matrix_eigenvalues_in_place` from the existing
+      linalg layer.
+- [ ] **Cylinder / cone shapes** (closed-form pairs against the existing
+      family + GJK+EPA fallback for general convex).
+
+### API polish
+- [ ] **`overlapShape(shape, position, rotation, filter?)`** public query
+      (broadphase + narrowphase) for AOE and selection use cases.
+- [ ] **`castShape(shape, from, to, rotation, filter?)`** for character
+      controllers and kinematic shape sweeps.
+
+---
+
+## Future / out-of-scope
+
+These are explicit architectural exclusions or post-v1 explorations.
+
+### Architecture
+- **Cross-runtime bit-exact determinism**: a soft-float library would
+  replace `Math.sin/cos/exp/log/pow` in the hot path. The codebase is
+  already structured to make this a swap-in at `quat_integrate.js` and
+  tangent-basis construction in `build_manifold.js`. Not pursued because
+  the same-runtime determinism we have covers the common cases (single-
+  device replay, networked lockstep where all clients run the same JS
+  engine).
+- **WASM / SIMD**: the engine targets pure-JS portability. SIMD would
+  invalidate the determinism story (V8 doesn't expose deterministic
+  Float64x2 ops).
+- **Multi-threaded solver**: workers don't share memory cheaply without
+  `SharedArrayBuffer` plus the COOP/COEP HTTP headers, which are not
+  always available. Single-threaded is good-enough for the awake-body
+  budget that matters.
+
+### Simulation extensions
+- **Soft body / cloth / fluids**: the SoA layout in `BodyStorage` and the
+  manifold cache are rigid-body shaped. A soft-body system would be a
+  parallel subsystem, not an extension.
+- **Reduced-coordinate articulations** (MuJoCo / Featherstone-style):
+  game-physics audience runs in maximal coordinates by convention. Not
+  on the roadmap.
+
+### Game-side
+- **Vehicle physics** (suspensions, drivetrains): a domain layer that
+  sits on top of the rigid-body primitives, not in `meep/`.
+- **Character controllers**: same — `engine/control/first-person/` is the
+  natural home.
+
+---
+
+## Notable design files
+
+- Original design plan: `C:\Users\Alex\.claude\plans\let-s-plan-to-implement-transient-harp.md`
+- This file (state of play): `engine/physics/PLAN.md`

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

@@ -0,0 +1,187 @@
+/**
+ * Pack a body index and generation into a single integer handle.
+ *
+ * @param {number} index
+ * @param {number} generation
+ * @returns {number}
+ */
+export function pack_body_id(index: number, generation: number): number;
+/**
+ *
+ * @param {number} packed
+ * @returns {number}
+ */
+export function body_id_index(packed: number): number;
+/**
+ *
+ * @param {number} packed
+ * @returns {number}
+ */
+export function body_id_generation(packed: number): number;
+/**
+ * Sentinel returned by {@link BodyStorage#awake_position_of} and friends when a
+ * body is not in the awake set.
+ * @type {number}
+ */
+export const BODY_INDEX_ABSENT: number;
+/**
+ * Structure-of-arrays pool for rigid bodies.
+ *
+ * Owns:
+ *  - per-body identity (entity, generation, kind, flags),
+ *  - a dense list of awake body indices (the simulation hot iteration target),
+ *  - a min-heap of free body indices so reuse order is deterministic regardless
+ *    of how interleaved allocate / free calls have been.
+ *
+ * The pool grows by doubling when the high-water mark reaches capacity; arrays
+ * are replaced wholesale on grow, so callers must not retain references to the
+ * raw typed arrays across allocate-after-grow boundaries.
+ *
+ * Determinism: allocate always reuses the lowest free index. Two pools given the
+ * same sequence of allocate/free calls observe identical body indices.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BodyStorage {
+    /**
+     *
+     * @param {number} [initial_capacity]
+     */
+    constructor(initial_capacity?: number);
+    __capacity: number;
+    __count: number;
+    __entities: Int32Array;
+    __generations: Uint8Array;
+    __kinds: Uint8Array;
+    __flags: Uint32Array;
+    __alive: Uint8Array;
+    __awake_list: Uint32Array;
+    __awake_pos: Int32Array;
+    __awake_count: number;
+    __free_heap: Uint32Array;
+    __free_count: number;
+    /**
+     * Currently allocated body count (live, regardless of awake/sleeping).
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Total slot capacity. Always a power of two by construction.
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     * Number of awake bodies.
+     * @returns {number}
+     */
+    get awake_count(): number;
+    /**
+     * High-water mark of slot indices ever issued. Useful when callers maintain
+     * per-slot side-tables.
+     * @returns {number}
+     */
+    get high_water_mark(): number;
+    /**
+     * Allocate a body slot for `entity`. The new body starts in the awake set
+     * with default kind {@link BodyKind.Dynamic} and zero flags; the caller
+     * may override these via {@link set_kind} / {@link set_flags}.
+     *
+     * @param {number} entity
+     * @returns {number} packed body id
+     */
+    allocate(entity: number): number;
+    /**
+     * Release a body slot previously returned by {@link allocate}. Bumps the
+     * generation so any old packed id becomes stale.
+     *
+     * @param {number} packed_body_id
+     */
+    free(packed_body_id: number): void;
+    /**
+     *
+     * @param {number} packed_body_id
+     * @returns {boolean}
+     */
+    is_valid(packed_body_id: number): boolean;
+    /**
+     * @param {number} index body index (NOT a packed id)
+     * @returns {number} entity for the body, or -1 if the slot is free.
+     */
+    entity_at(index: number): number;
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    generation_at(index: number): number;
+    /**
+     * @param {number} index
+     * @returns {BodyKind|number}
+     */
+    kind_at(index: number): BodyKind | number;
+    /**
+     * @param {number} index
+     * @param {BodyKind|number} kind
+     */
+    set_kind(index: number, kind: BodyKind | number): void;
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    flags_at(index: number): number;
+    /**
+     * @param {number} index
+     * @param {number} flags
+     */
+    set_flags(index: number, flags: number): void;
+    /**
+     * Index of `index` in the awake list, or {@link BODY_INDEX_ABSENT} if asleep.
+     * @param {number} index
+     * @returns {number}
+     */
+    awake_position_of(index: number): number;
+    /**
+     *
+     * @param {number} index
+     * @returns {boolean}
+     */
+    is_awake(index: number): boolean;
+    /**
+     * Read the body index at position `i` in the dense awake list (0-based).
+     * @param {number} i
+     * @returns {number}
+     */
+    awake_at(i: number): number;
+    /**
+     * Add `index` to the awake set if not already present.
+     * @param {number} index
+     */
+    mark_awake(index: number): void;
+    /**
+     * Remove `index` from the awake set if present.
+     * @param {number} index
+     */
+    mark_sleeping(index: number): void;
+    /**
+     * Swap-with-last removal at position `pos` in the dense awake list.
+     * @private
+     * @param {number} pos
+     */
+    private __awake_remove_at;
+    /**
+     * @private
+     */
+    private __grow;
+    /**
+     * @private
+     * @param {number} index
+     */
+    private __heap_push;
+    /**
+     * @private
+     * @returns {number}
+     */
+    private __heap_pop;
+}
+import { BodyKind } from "../ecs/BodyKind.js";
+//# sourceMappingURL=BodyStorage.d.ts.map

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

@@ -0,0 +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"}