@woosh/meep-engine 2.155.0 → 2.157.0

package/src/engine/physics/persistence/solver_caches.js

@@ -0,0 +1,309 @@
+import { assert } from "../../../core/assert.js";
+import { BODY_INDEX_ABSENT, body_id_index, pack_body_id } from "../body/BodyStorage.js";
+import { CONTACT_STRIDE } from "../contact/ManifoldStore.js";
+import { SleepState } from "../ecs/SleepState.js";
+
+/**
+ * # Solver-cache serialization
+ *
+ * The engine's outcome-affecting state that does NOT live on components:
+ *
+ *  - contact manifolds: warm-start impulses, contact geometry awaiting the
+ *    next match-and-merge, and the lifecycle bits (grace, had_contacts,
+ *    prox-edge memory) that drive events and the stage-0 wake;
+ *  - joint warm-start impulses (`dofImpulse` — zeroed by link_joint, so a
+ *    re-linked joint must have it restored explicitly);
+ *  - sleep-group membership (circular chains of body indices — pure
+ *    world-instance ids that cannot ride on components).
+ *
+ * Reconstruction-determinism contract: copying body components alone makes
+ * a rebuilt world *converge* with the original, but the first few ticks
+ * differ — a cold solver re-converges its impulses, evicted manifolds
+ * re-fire Begin events, sleepers wake as singletons. Exporting this blob
+ * alongside the components and importing it after relinking makes the
+ * rebuilt world continue BIT-IDENTICALLY.
+ *
+ * Everything is keyed by ENTITY (the cross-engine identity); packed body
+ * ids and slot ids never enter the stream. Slots are written sorted by
+ * entity pair, so two engines holding identical state produce identical
+ * bytes. No mirroring is ever needed on import: the broadphase assigns
+ * manifold A/B roles entity-canonically (see generate_pairs), so the
+ * exported A side is the importing engine's A side by construction.
+ *
+ * Usage:
+ *
+ *     // export, at a step boundary:
+ *     write_solver_caches(system, buffer);
+ *
+ *     // import, into a freshly-built (or fully cleared) system AFTER all
+ *     // bodies and joints have been linked with their restored components:
+ *     read_solver_caches(system, buffer);
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const FORMAT_VERSION = 1;
+
+/**
+ * Serialize the system's solver caches. Call at a step boundary (between
+ * fixedUpdate calls) — mid-step state is not exportable.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+export function write_solver_caches(system, buffer) {
+    buffer.writeUint8(FORMAT_VERSION);
+
+    __write_manifolds(system, buffer);
+    __write_joint_impulses(system, buffer);
+    __write_sleep_groups(system, buffer);
+}
+
+/**
+ * Restore solver caches exported by {@link write_solver_caches} into a
+ * system whose bodies (and joints) have been re-linked under the SAME
+ * entity ids. The manifold store must be empty (a fresh system, or
+ * `system.manifolds.clear()` after a remove-all) so slot allocation starts
+ * from a known state.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+export function read_solver_caches(system, buffer) {
+    const version = buffer.readUint8();
+    assert.equal(version, FORMAT_VERSION, `solver-cache stream version ${version}, expected ${FORMAT_VERSION}`);
+
+    __read_manifolds(system, buffer);
+    __read_joint_impulses(system, buffer);
+    __read_sleep_groups(system, buffer);
+}
+
+/**
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __write_manifolds(system, buffer) {
+    const manifolds = system.manifolds;
+    const storage = system.storage;
+
+    // Collect live slots whose bodies are both still valid (a slot whose
+    // body was unlinked is inert, awaiting grace eviction — nothing to
+    // restore), then sort by entity pair so the stream is canonical.
+    const records = [];
+    const live_count = manifolds.count;
+    for (let i = 0; i < live_count; i++) {
+        const slot = manifolds.live_at(i);
+        const idA = manifolds.bodyA(slot);
+        const idB = manifolds.bodyB(slot);
+        if (!storage.is_valid(idA) || !storage.is_valid(idB)) continue;
+        records.push({
+            slot,
+            entA: storage.entity_at(body_id_index(idA)),
+            entB: storage.entity_at(body_id_index(idB)),
+        });
+    }
+    records.sort((a, b) => (a.entA - b.entA) || (a.entB - b.entB));
+
+    buffer.writeUint32(records.length);
+
+    const data = manifolds.data_buffer;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        buffer.writeInt32(r.entA);
+        buffer.writeInt32(r.entB);
+        buffer.writeUint32(manifolds.meta_bits(r.slot));
+
+        const count = manifolds.contact_count(r.slot);
+        const off = manifolds.slot_data_offset(r.slot);
+        const words = count * CONTACT_STRIDE;
+        for (let w = 0; w < words; w++) {
+            buffer.writeFloat64(data[off + w]);
+        }
+    }
+}
+
+/**
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __read_manifolds(system, buffer) {
+    const manifolds = system.manifolds;
+    const storage = system.storage;
+
+    assert.equal(manifolds.count, 0,
+        'read_solver_caches: manifold store must be empty (fresh system, or manifolds.clear() after a remove-all)');
+
+    const n = buffer.readUint32();
+    for (let i = 0; i < n; i++) {
+        const entA = buffer.readInt32();
+        const entB = buffer.readInt32();
+        const bits = buffer.readUint32();
+
+        const idxA = storage.index_of_entity(entA);
+        const idxB = storage.index_of_entity(entB);
+        assert.notEqual(idxA, BODY_INDEX_ABSENT, `read_solver_caches: no body linked for entity ${entA}`);
+        assert.notEqual(idxB, BODY_INDEX_ABSENT, `read_solver_caches: no body linked for entity ${entB}`);
+
+        // Entity-canonical roles: entA < entB in the stream, and the
+        // broadphase assigns A to the smaller entity — same side, no mirror.
+        const idA = pack_body_id(idxA, storage.generation_at(idxA));
+        const idB = pack_body_id(idxB, storage.generation_at(idxB));
+
+        const slot = manifolds.acquire(idA, idB);
+        manifolds.restore_meta_bits(slot, bits);
+
+        const count = manifolds.contact_count(slot);
+        const off = manifolds.slot_data_offset(slot);
+        const data = manifolds.data_buffer; // re-read: acquire may have grown the store
+        const words = count * CONTACT_STRIDE;
+        for (let w = 0; w < words; w++) {
+            data[off + w] = buffer.readFloat64();
+        }
+    }
+}
+
+/**
+ * Joint warm-start impulses, in canonical solve order. The importing
+ * engine must hold the SAME joints linked in the SAME per-pair order —
+ * the reconstruction contract replays joint links — so the records are
+ * matched positionally against its sorted registry, with the entity pair
+ * asserted at each position.
+ *
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __write_joint_impulses(system, buffer) {
+    const sorted = system.__joints_sorted;
+    buffer.writeUint32(sorted.length);
+    for (let i = 0; i < sorted.length; i++) {
+        const joint = sorted[i];
+        buffer.writeInt32(joint.entityA);
+        buffer.writeInt32(joint.entityB);
+        for (let d = 0; d < 6; d++) {
+            buffer.writeFloat64(joint.dofImpulse[d]);
+        }
+    }
+}
+
+/**
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __read_joint_impulses(system, buffer) {
+    const sorted = system.__joints_sorted;
+    const n = buffer.readUint32();
+    assert.equal(n, sorted.length,
+        `read_solver_caches: stream holds ${n} joints, system has ${sorted.length} linked`);
+
+    for (let i = 0; i < n; i++) {
+        const entA = buffer.readInt32();
+        const entB = buffer.readInt32();
+        const joint = sorted[i];
+        assert.ok(joint.entityA === entA && joint.entityB === entB,
+            `read_solver_caches: joint ${i} is (${joint.entityA}, ${joint.entityB}), stream says (${entA}, ${entB})`);
+        for (let d = 0; d < 6; d++) {
+            joint.dofImpulse[d] = buffer.readFloat64();
+        }
+    }
+}
+
+/**
+ * Sleep groups as entity chains. Only multi-member groups are written —
+ * a singleton sleeper's links are already `-1`, which is how link()
+ * restores every sleeper. Each chain is rotated to start at its
+ * smallest-entity member so the stream is canonical; the circular order
+ * itself only affects wake-walk order, which is outcome-neutral, but
+ * verbatim restore keeps the worlds bit-comparable.
+ *
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __write_sleep_groups(system, buffer) {
+    const storage = system.storage;
+    const bodies = system.__bodies;
+    const hwm = storage.high_water_mark;
+
+    const groups = [];
+    const visited = new Set();
+
+    for (let idx = 0; idx < hwm; idx++) {
+        const rb = bodies[idx];
+        if (rb === undefined) continue;
+        if (rb.sleep_group_next === -1) continue;
+        if (visited.has(idx)) continue;
+
+        // Walk the circular chain once, collecting member indices.
+        const chain = [];
+        let cur = idx;
+        do {
+            chain.push(cur);
+            visited.add(cur);
+            cur = bodies[cur].sleep_group_next;
+        } while (cur !== -1 && cur !== idx && !visited.has(cur));
+
+        // Rotate so the smallest-entity member leads.
+        let lead = 0;
+        let lead_entity = storage.entity_at(chain[0]);
+        for (let i = 1; i < chain.length; i++) {
+            const e = storage.entity_at(chain[i]);
+            if (e < lead_entity) {
+                lead_entity = e;
+                lead = i;
+            }
+        }
+        const entities = [];
+        for (let i = 0; i < chain.length; i++) {
+            entities.push(storage.entity_at(chain[(lead + i) % chain.length]));
+        }
+        groups.push(entities);
+    }
+
+    groups.sort((a, b) => a[0] - b[0]);
+
+    buffer.writeUint32(groups.length);
+    for (let g = 0; g < groups.length; g++) {
+        const entities = groups[g];
+        buffer.writeUint32(entities.length);
+        for (let i = 0; i < entities.length; i++) {
+            buffer.writeInt32(entities[i]);
+        }
+    }
+}
+
+/**
+ * @private
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {BinaryBuffer} buffer
+ */
+function __read_sleep_groups(system, buffer) {
+    const storage = system.storage;
+    const bodies = system.__bodies;
+
+    const group_count = buffer.readUint32();
+    for (let g = 0; g < group_count; g++) {
+        const len = buffer.readUint32();
+        assert.greaterThan(len, 1, 'read_solver_caches: a sleep group must have at least 2 members');
+
+        const indices = new Array(len);
+        for (let i = 0; i < len; i++) {
+            const entity = buffer.readInt32();
+            const idx = storage.index_of_entity(entity);
+            assert.notEqual(idx, BODY_INDEX_ABSENT, `read_solver_caches: no body linked for sleep-group entity ${entity}`);
+            indices[i] = idx;
+        }
+
+        for (let i = 0; i < len; i++) {
+            const rb = bodies[indices[i]];
+            assert.equal(rb.sleepState, SleepState.Sleeping,
+                'read_solver_caches: sleep-group member must be restored with sleepState=Sleeping before import');
+            rb.sleep_group_next = indices[(i + 1) % len];
+            rb.sleep_group_prev = indices[(i - 1 + len) % len];
+        }
+    }
+}

package/src/engine/physics/queries/overlap_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAoGlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAuGlB"}