@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,427 @@
+import { assert } from "../../../core/assert.js";
+import { BodyKind } from "../ecs/BodyKind.js";
+
+const DEFAULT_INITIAL_CAPACITY = 16;
+const MIN_CAPACITY = 4;
+
+/**
+ * Mask for the 8-bit generation field encoded in a packed body id.
+ * @type {number}
+ */
+const GENERATION_MASK = 0xFF;
+
+/**
+ * Bit width of the generation field. The remaining bits are the body index;
+ * 24-bit indices give us 16M live bodies which is comfortably above the design
+ * target of "millions".
+ * @type {number}
+ */
+const GENERATION_BITS = 8;
+
+/**
+ * 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 = -1;
+
+/**
+ * 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, generation) {
+    return (index << GENERATION_BITS) | (generation & GENERATION_MASK);
+}
+
+/**
+ *
+ * @param {number} packed
+ * @returns {number}
+ */
+export function body_id_index(packed) {
+    return packed >>> GENERATION_BITS;
+}
+
+/**
+ *
+ * @param {number} packed
+ * @returns {number}
+ */
+export function body_id_generation(packed) {
+    return packed & GENERATION_MASK;
+}
+
+/**
+ * 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 = DEFAULT_INITIAL_CAPACITY) {
+        assert.isNonNegativeInteger(initial_capacity, 'initial_capacity');
+
+        const cap = Math.max(MIN_CAPACITY, initial_capacity);
+
+        this.__capacity = cap;
+        // High-water mark of slot indices ever issued. Slots in [0, count) are
+        // either currently allocated or sitting on the free heap.
+        this.__count = 0;
+
+        this.__entities = new Int32Array(cap);
+        this.__generations = new Uint8Array(cap);
+        this.__kinds = new Uint8Array(cap);
+        this.__flags = new Uint32Array(cap);
+
+        // 1 = allocated, 0 = free. Cheaper than scanning the free heap.
+        this.__alive = new Uint8Array(cap);
+
+        // Awake set: dense list of awake body indices + reverse map.
+        this.__awake_list = new Uint32Array(cap);
+        this.__awake_pos = new Int32Array(cap);
+        this.__awake_count = 0;
+
+        // Min-heap of free body indices for deterministic reuse.
+        this.__free_heap = new Uint32Array(cap);
+        this.__free_count = 0;
+
+        // Initialise reverse map to BODY_INDEX_ABSENT.
+        this.__awake_pos.fill(BODY_INDEX_ABSENT);
+    }
+
+    /**
+     * Currently allocated body count (live, regardless of awake/sleeping).
+     * @returns {number}
+     */
+    get size() {
+        return this.__count - this.__free_count;
+    }
+
+    /**
+     * Total slot capacity. Always a power of two by construction.
+     * @returns {number}
+     */
+    get capacity() {
+        return this.__capacity;
+    }
+
+    /**
+     * Number of awake bodies.
+     * @returns {number}
+     */
+    get awake_count() {
+        return this.__awake_count;
+    }
+
+    /**
+     * High-water mark of slot indices ever issued. Useful when callers maintain
+     * per-slot side-tables.
+     * @returns {number}
+     */
+    get high_water_mark() {
+        return this.__count;
+    }
+
+    /**
+     * 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) {
+        let index;
+
+        if (this.__free_count > 0) {
+            index = this.__heap_pop();
+        } else {
+            if (this.__count === this.__capacity) {
+                this.__grow();
+            }
+            index = this.__count++;
+        }
+
+        this.__entities[index] = entity;
+        this.__kinds[index] = BodyKind.Dynamic;
+        this.__flags[index] = 0;
+        this.__alive[index] = 1;
+
+        // Insert into awake set.
+        const awake_pos = this.__awake_count++;
+        this.__awake_list[awake_pos] = index;
+        this.__awake_pos[index] = awake_pos;
+
+        return pack_body_id(index, this.__generations[index]);
+    }
+
+    /**
+     * 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) {
+        const index = body_id_index(packed_body_id);
+
+        assert.equal(this.is_valid(packed_body_id), true, 'free() called on stale or unknown body id');
+
+        // Remove from awake set if present.
+        const awake_pos = this.__awake_pos[index];
+        if (awake_pos !== BODY_INDEX_ABSENT) {
+            this.__awake_remove_at(awake_pos);
+            this.__awake_pos[index] = BODY_INDEX_ABSENT;
+        }
+
+        this.__alive[index] = 0;
+
+        // Bump generation; wraps mod 256.
+        this.__generations[index] = (this.__generations[index] + 1) & GENERATION_MASK;
+
+        this.__heap_push(index);
+    }
+
+    /**
+     *
+     * @param {number} packed_body_id
+     * @returns {boolean}
+     */
+    is_valid(packed_body_id) {
+        const index = body_id_index(packed_body_id);
+        if (index < 0 || index >= this.__count) {
+            return false;
+        }
+        if (this.__alive[index] !== 1) {
+            return false;
+        }
+        return this.__generations[index] === body_id_generation(packed_body_id);
+    }
+
+    /**
+     * @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) {
+        if (this.__alive[index] !== 1) {
+            return -1;
+        }
+        return this.__entities[index];
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    generation_at(index) {
+        return this.__generations[index];
+    }
+
+    /**
+     * @param {number} index
+     * @returns {BodyKind|number}
+     */
+    kind_at(index) {
+        return this.__kinds[index];
+    }
+
+    /**
+     * @param {number} index
+     * @param {BodyKind|number} kind
+     */
+    set_kind(index, kind) {
+        this.__kinds[index] = kind;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number}
+     */
+    flags_at(index) {
+        return this.__flags[index];
+    }
+
+    /**
+     * @param {number} index
+     * @param {number} flags
+     */
+    set_flags(index, flags) {
+        this.__flags[index] = flags;
+    }
+
+    /**
+     * Index of `index` in the awake list, or {@link BODY_INDEX_ABSENT} if asleep.
+     * @param {number} index
+     * @returns {number}
+     */
+    awake_position_of(index) {
+        return this.__awake_pos[index];
+    }
+
+    /**
+     *
+     * @param {number} index
+     * @returns {boolean}
+     */
+    is_awake(index) {
+        return this.__awake_pos[index] !== BODY_INDEX_ABSENT;
+    }
+
+    /**
+     * Read the body index at position `i` in the dense awake list (0-based).
+     * @param {number} i
+     * @returns {number}
+     */
+    awake_at(i) {
+        return this.__awake_list[i];
+    }
+
+    /**
+     * Add `index` to the awake set if not already present.
+     * @param {number} index
+     */
+    mark_awake(index) {
+        if (this.__awake_pos[index] !== BODY_INDEX_ABSENT) {
+            return;
+        }
+        const pos = this.__awake_count++;
+        this.__awake_list[pos] = index;
+        this.__awake_pos[index] = pos;
+    }
+
+    /**
+     * Remove `index` from the awake set if present.
+     * @param {number} index
+     */
+    mark_sleeping(index) {
+        const pos = this.__awake_pos[index];
+        if (pos === BODY_INDEX_ABSENT) {
+            return;
+        }
+        this.__awake_remove_at(pos);
+        this.__awake_pos[index] = BODY_INDEX_ABSENT;
+    }
+
+    /**
+     * Swap-with-last removal at position `pos` in the dense awake list.
+     * @private
+     * @param {number} pos
+     */
+    __awake_remove_at(pos) {
+        const last_pos = --this.__awake_count;
+        if (pos !== last_pos) {
+            const swapped_index = this.__awake_list[last_pos];
+            this.__awake_list[pos] = swapped_index;
+            this.__awake_pos[swapped_index] = pos;
+        }
+    }
+
+    /**
+     * @private
+     */
+    __grow() {
+        const new_cap = this.__capacity << 1;
+        this.__capacity = new_cap;
+
+        const grow_int32 = (a) => {
+            const next = new Int32Array(new_cap);
+            next.set(a);
+            return next;
+        };
+        const grow_uint8 = (a) => {
+            const next = new Uint8Array(new_cap);
+            next.set(a);
+            return next;
+        };
+        const grow_uint32 = (a) => {
+            const next = new Uint32Array(new_cap);
+            next.set(a);
+            return next;
+        };
+
+        this.__entities = grow_int32(this.__entities);
+        this.__generations = grow_uint8(this.__generations);
+        this.__kinds = grow_uint8(this.__kinds);
+        this.__flags = grow_uint32(this.__flags);
+        this.__alive = grow_uint8(this.__alive);
+        this.__awake_list = grow_uint32(this.__awake_list);
+        this.__free_heap = grow_uint32(this.__free_heap);
+
+        // Awake position has signed sentinel — needs fill on the grown portion.
+        const next_pos = new Int32Array(new_cap);
+        next_pos.set(this.__awake_pos);
+        next_pos.fill(BODY_INDEX_ABSENT, this.__awake_pos.length);
+        this.__awake_pos = next_pos;
+    }
+
+    // --- Min-heap of free indices --------------------------------------------
+
+    /**
+     * @private
+     * @param {number} index
+     */
+    __heap_push(index) {
+        const heap = this.__free_heap;
+        let i = this.__free_count++;
+        heap[i] = index;
+
+        while (i > 0) {
+            const parent = (i - 1) >>> 1;
+            if (heap[parent] > heap[i]) {
+                const tmp = heap[parent];
+                heap[parent] = heap[i];
+                heap[i] = tmp;
+                i = parent;
+            } else {
+                break;
+            }
+        }
+    }
+
+    /**
+     * @private
+     * @returns {number}
+     */
+    __heap_pop() {
+        const heap = this.__free_heap;
+        const result = heap[0];
+        const new_count = --this.__free_count;
+        if (new_count > 0) {
+            heap[0] = heap[new_count];
+            let i = 0;
+            while (true) {
+                const l = (i << 1) + 1;
+                const r = l + 1;
+                let smallest = i;
+                if (l < new_count && heap[l] < heap[smallest]) smallest = l;
+                if (r < new_count && heap[r] < heap[smallest]) smallest = r;
+                if (smallest === i) break;
+                const tmp = heap[i];
+                heap[i] = heap[smallest];
+                heap[smallest] = tmp;
+                i = smallest;
+            }
+        }
+        return result;
+    }
+}

package/src/engine/physics/broadphase/PairList.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Growable Uint32Array list of `(idA, idB)` body-id pairs. Stride is 2 words
+ * per pair. `count` tracks the number of pairs; capacity grows by doubling.
+ *
+ * No allocation happens during {@link push} until capacity is exceeded. The
+ * intended usage is `clear()` at the top of each step and `push` for each
+ * candidate pair encountered during broadphase.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PairList {
+    /**
+     * @param {number} [initial_capacity] pairs (not words)
+     */
+    constructor(initial_capacity?: number);
+    __capacity: number;
+    __count: number;
+    __data: Uint32Array;
+    /**
+     * @returns {number} number of pairs currently stored
+     */
+    get count(): number;
+    /**
+     * @returns {number} pair capacity (doubles on overflow)
+     */
+    get capacity(): number;
+    /**
+     * Raw word buffer. `data[i*2 + 0]` is idA, `data[i*2 + 1]` is idB for the
+     * `i`-th pair, where `i < count`. Exposed for hot-loop iteration; valid
+     * until the next {@link push} that triggers a grow.
+     * @returns {Uint32Array}
+     */
+    get data(): Uint32Array;
+    /**
+     * Reset to empty without releasing capacity.
+     */
+    clear(): void;
+    /**
+     * Append a pair. Caller is expected to have already canonicalised
+     * `idA < idB` if symmetric semantics are needed.
+     *
+     * @param {number} idA
+     * @param {number} idB
+     */
+    push(idA: number, idB: number): void;
+    /**
+     * @param {number} i pair index, `[0, count)`
+     * @returns {number}
+     */
+    get_a(i: number): number;
+    /**
+     * @param {number} i pair index, `[0, count)`
+     * @returns {number}
+     */
+    get_b(i: number): number;
+    /**
+     * @private
+     */
+    private __grow;
+}
+//# sourceMappingURL=PairList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PairList.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/PairList.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EAMhB;IAHG,mBAA+C;IAC/C,gBAAgB;IAChB,oBAAkD;IAGtD;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;OAKG;IACH,wBAEC;IAED;;OAEG;IACH,cAEC;IAED;;;;;;OAMG;IACH,UAHW,MAAM,OACN,MAAM,QAUhB;IAED;;;OAGG;IACH,SAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,SAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,eAMC;CACJ"}

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

@@ -0,0 +1,97 @@
+/**
+ * Growable Uint32Array list of `(idA, idB)` body-id pairs. Stride is 2 words
+ * per pair. `count` tracks the number of pairs; capacity grows by doubling.
+ *
+ * No allocation happens during {@link push} until capacity is exceeded. The
+ * intended usage is `clear()` at the top of each step and `push` for each
+ * candidate pair encountered during broadphase.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PairList {
+
+    /**
+     * @param {number} [initial_capacity] pairs (not words)
+     */
+    constructor(initial_capacity = 64) {
+        this.__capacity = Math.max(1, initial_capacity);
+        this.__count = 0;
+        this.__data = new Uint32Array(this.__capacity * 2);
+    }
+
+    /**
+     * @returns {number} number of pairs currently stored
+     */
+    get count() {
+        return this.__count;
+    }
+
+    /**
+     * @returns {number} pair capacity (doubles on overflow)
+     */
+    get capacity() {
+        return this.__capacity;
+    }
+
+    /**
+     * Raw word buffer. `data[i*2 + 0]` is idA, `data[i*2 + 1]` is idB for the
+     * `i`-th pair, where `i < count`. Exposed for hot-loop iteration; valid
+     * until the next {@link push} that triggers a grow.
+     * @returns {Uint32Array}
+     */
+    get data() {
+        return this.__data;
+    }
+
+    /**
+     * Reset to empty without releasing capacity.
+     */
+    clear() {
+        this.__count = 0;
+    }
+
+    /**
+     * Append a pair. Caller is expected to have already canonicalised
+     * `idA < idB` if symmetric semantics are needed.
+     *
+     * @param {number} idA
+     * @param {number} idB
+     */
+    push(idA, idB) {
+        if (this.__count === this.__capacity) {
+            this.__grow();
+        }
+        const off = this.__count * 2;
+        this.__data[off] = idA;
+        this.__data[off + 1] = idB;
+        this.__count++;
+    }
+
+    /**
+     * @param {number} i pair index, `[0, count)`
+     * @returns {number}
+     */
+    get_a(i) {
+        return this.__data[i * 2];
+    }
+
+    /**
+     * @param {number} i pair index, `[0, count)`
+     * @returns {number}
+     */
+    get_b(i) {
+        return this.__data[i * 2 + 1];
+    }
+
+    /**
+     * @private
+     */
+    __grow() {
+        const new_capacity = this.__capacity << 1;
+        const next = new Uint32Array(new_capacity * 2);
+        next.set(this.__data);
+        this.__data = next;
+        this.__capacity = new_capacity;
+    }
+}

package/src/engine/physics/broadphase/aabb_transform_oriented.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Compute the world-space axis-aligned bounding box of a local AABB after a
+ * rigid transform (position + orientation).
+ *
+ * Math: an AABB transformed by a rotation `R` is bounded by another AABB whose
+ * centre is `R · c_local + t` and whose half-extent along each world axis `i`
+ * is `Σ_j |R_ij| · half_extent_local_j`. The element-wise-abs trick avoids
+ * rotating all 8 corners and projecting.
+ *
+ * Output layout matches existing AABB conventions: `[x0, y0, z0, x1, y1, z1]`
+ * with `(x0,y0,z0)` as the min corner.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} lx0 local min x
+ * @param {number} ly0 local min y
+ * @param {number} lz0 local min z
+ * @param {number} lx1 local max x
+ * @param {number} ly1 local max y
+ * @param {number} lz1 local max z
+ * @param {number} px  translation x
+ * @param {number} py  translation y
+ * @param {number} pz  translation z
+ * @param {number} qx  quaternion x (unit)
+ * @param {number} qy  quaternion y
+ * @param {number} qz  quaternion z
+ * @param {number} qw  quaternion w
+ */
+export function aabb_transform_oriented(result: number[] | Float32Array | Float64Array, result_offset: number, lx0: number, ly0: number, lz0: number, lx1: number, ly1: number, lz1: number, px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number): void;
+//# sourceMappingURL=aabb_transform_oriented.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aabb_transform_oriented.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/aabb_transform_oriented.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gDAhBW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkEhB"}