@woosh/meep-engine 2.138.20 → 2.139.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.138.20",
+  "version": "2.139.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/collection/PairUint32Map.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Returned by {@link PairUint32Map#get} when the key pair is absent.
+ * @type {number}
+ */
+export const PAIR_UINT32_MAP_ABSENT: number;
+/**
+ * Open-addressed Robin Hood map from a pair of uint32 keys to a uint32 value.
+ *
+ * Layout: a single `Uint32Array` of `3 * capacity` words. Slot `s` is
+ * `[key_a + 1, key_b, value]`. The first word doubles as the slot-occupied
+ * marker (0 = empty).
+ *
+ * Hashing: `mix = imul(key_a + 1, MIX_A) ^ imul(key_b + 1, MIX_B)`, indexed via
+ * the high bits (right-shift, not low-bit mask — high bits of a multiplicative
+ * hash have more entropy, see Skarupke 2018).
+ *
+ * Collision resolution: Robin Hood linear probing with backward-shift deletion.
+ *
+ * Symmetric pair use: callers wanting `(a, b)` to be indistinguishable from
+ * `(b, a)` should canonicalise (e.g. `min, max`) before calling.
+ *
+ * Allowed key range per slot field: 0 .. UINT32_MAX − 1 (because key_a is stored
+ * as key+1). Allowed value range: full uint32.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PairUint32Map {
+    /**
+     *
+     * @param {number} [initial_capacity] minimum number of slots; rounded up to power of two.
+     */
+    constructor(initial_capacity?: number);
+    __capacity: number;
+    __mask: number;
+    __shift: number;
+    __grow_threshold: number;
+    __size: number;
+    __data: Uint32Array;
+    /**
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     *
+     * @param {number} key_a_shifted key_a + 1 (already shifted form, as stored)
+     * @param {number} key_b
+     * @returns {number}
+     */
+    __hash(key_a_shifted: number, key_b: number): number;
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {number} value or {@link PAIR_UINT32_MAP_ABSENT}.
+     */
+    get(key_a: number, key_b: number): number;
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    has(key_a: number, key_b: number): boolean;
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @param {number} value
+     */
+    set(key_a: number, key_b: number, value: number): void;
+    /**
+     * @private
+     * @param {number} ksa key_a + 1
+     * @param {number} kb  key_b (raw)
+     * @param {number} value
+     */
+    private __insert_no_grow;
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    delete(key_a: number, key_b: number): boolean;
+    clear(): void;
+    /**
+     * @private
+     * @param {number} new_capacity power of two
+     */
+    private __resize;
+}
+export namespace PairUint32Map {
+    let MAX_KEY: number;
+}
+//# sourceMappingURL=PairUint32Map.d.ts.map

package/src/core/collection/PairUint32Map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PairUint32Map.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/PairUint32Map.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qCAFU,MAAM,CAEyB;AA2BzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;;OAGG;IACH,+BAFW,MAAM,EAchB;IANG,mBAAqB;IACrB,eAAqB;IACrB,gBAAkC;IAClC,yBAA2E;IAC3E,eAAe;IACf,oBAAgD;IAGpD;;OAEG;IACH,mBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;OAKG;IACH,sBAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,WAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAiClB;IAED;;;;;OAKG;IACH,WAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAJW,MAAM,SACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,yBAiDC;IAED;;;;;OAKG;IACH,cAJW,MAAM,SACN,MAAM,GACJ,OAAO,CA+DnB;IAED,cAGC;IAED;;;OAGG;IACH,iBAkBC;CACJ;;iBAGS,MAAM"}

package/src/core/collection/PairUint32Map.js

@@ -0,0 +1,321 @@
+import { assert } from "../assert.js";
+
+/**
+ * Returned by {@link PairUint32Map#get} when the key pair is absent.
+ * @type {number}
+ */
+export const PAIR_UINT32_MAP_ABSENT = -1;
+
+const UINT32_MAX = 4294967295;
+
+/**
+ * Two multipliers chosen so the bits of `a` and `b` mix into one 32-bit hash
+ * with reasonable spread for sequential-ish keys. The first is 2^32 / phi
+ * (the Fibonacci constant used by {@link Uint32Map}); the second is a large
+ * odd 32-bit prime used in the FNV-1a family for the secondary mix.
+ * @type {number}
+ */
+const MIX_A = 2654435761;
+const MIX_B = 2246822519;
+
+/**
+ * Slot is 3 words wide: [key_a + 1, key_b, value]. `key_a` is stored offset by
+ * +1 so that 0 in the first word unambiguously means "empty slot" — see
+ * {@link Uint32Map} for the same trick on a single-key map.
+ * @type {number}
+ */
+const SLOT_STRIDE = 3;
+
+const DEFAULT_CAPACITY = 16;
+const MIN_CAPACITY = 2;
+const LOAD_FACTOR_NUMERATOR = 3;
+const LOAD_FACTOR_SHIFT = 2;
+
+/**
+ * Open-addressed Robin Hood map from a pair of uint32 keys to a uint32 value.
+ *
+ * Layout: a single `Uint32Array` of `3 * capacity` words. Slot `s` is
+ * `[key_a + 1, key_b, value]`. The first word doubles as the slot-occupied
+ * marker (0 = empty).
+ *
+ * Hashing: `mix = imul(key_a + 1, MIX_A) ^ imul(key_b + 1, MIX_B)`, indexed via
+ * the high bits (right-shift, not low-bit mask — high bits of a multiplicative
+ * hash have more entropy, see Skarupke 2018).
+ *
+ * Collision resolution: Robin Hood linear probing with backward-shift deletion.
+ *
+ * Symmetric pair use: callers wanting `(a, b)` to be indistinguishable from
+ * `(b, a)` should canonicalise (e.g. `min, max`) before calling.
+ *
+ * Allowed key range per slot field: 0 .. UINT32_MAX − 1 (because key_a is stored
+ * as key+1). Allowed value range: full uint32.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PairUint32Map {
+
+    /**
+     *
+     * @param {number} [initial_capacity] minimum number of slots; rounded up to power of two.
+     */
+    constructor(initial_capacity = DEFAULT_CAPACITY) {
+        assert.isNonNegativeInteger(initial_capacity, 'initial_capacity');
+
+        let cap = MIN_CAPACITY;
+        while (cap < initial_capacity) cap <<= 1;
+
+        this.__capacity = cap;
+        this.__mask = cap - 1;
+        this.__shift = Math.clz32(cap - 1);
+        this.__grow_threshold = (cap * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        this.__size = 0;
+        this.__data = new Uint32Array(cap * SLOT_STRIDE);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get size() {
+        return this.__size;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get capacity() {
+        return this.__capacity;
+    }
+
+    /**
+     *
+     * @param {number} key_a_shifted key_a + 1 (already shifted form, as stored)
+     * @param {number} key_b
+     * @returns {number}
+     */
+    __hash(key_a_shifted, key_b) {
+        return (Math.imul(key_a_shifted, MIX_A) ^ Math.imul(key_b + 1, MIX_B)) >>> 0;
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {number} value or {@link PAIR_UINT32_MAP_ABSENT}.
+     */
+    get(key_a, key_b) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const ksa = key_a + 1;
+
+        let slot = this.__hash(ksa, key_b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const ka = data[off];
+
+            if (ka === 0) {
+                return PAIR_UINT32_MAP_ABSENT;
+            }
+            if (ka === ksa && data[off + 1] === key_b) {
+                return data[off + 2];
+            }
+
+            // Robin Hood early-exit.
+            const home = this.__hash(ka, data[off + 1]) >>> shift;
+            const slot_dist = (slot - home) & mask;
+            if (dist > slot_dist) {
+                return PAIR_UINT32_MAP_ABSENT;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    has(key_a, key_b) {
+        return this.get(key_a, key_b) !== PAIR_UINT32_MAP_ABSENT;
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @param {number} value
+     */
+    set(key_a, key_b, value) {
+        if (this.__size >= this.__grow_threshold) {
+            this.__resize(this.__capacity << 1);
+        }
+        this.__insert_no_grow(key_a + 1, key_b, value);
+    }
+
+    /**
+     * @private
+     * @param {number} ksa key_a + 1
+     * @param {number} kb  key_b (raw)
+     * @param {number} value
+     */
+    __insert_no_grow(ksa, kb, value) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        let a = ksa;
+        let b = kb;
+        let v = value;
+        let slot = this.__hash(a, b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const occ_a = data[off];
+
+            if (occ_a === 0) {
+                data[off] = a;
+                data[off + 1] = b;
+                data[off + 2] = v;
+                this.__size++;
+                return;
+            }
+
+            if (occ_a === a && data[off + 1] === b) {
+                // overwrite existing
+                data[off + 2] = v;
+                return;
+            }
+
+            const home = this.__hash(occ_a, data[off + 1]) >>> shift;
+            const occ_dist = (slot - home) & mask;
+
+            if (occ_dist < dist) {
+                // steal
+                const tmp_a = occ_a;
+                const tmp_b = data[off + 1];
+                const tmp_v = data[off + 2];
+                data[off] = a;
+                data[off + 1] = b;
+                data[off + 2] = v;
+                a = tmp_a;
+                b = tmp_b;
+                v = tmp_v;
+                dist = occ_dist;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} key_a
+     * @param {number} key_b
+     * @returns {boolean}
+     */
+    delete(key_a, key_b) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const ksa = key_a + 1;
+
+        let slot = this.__hash(ksa, key_b) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const off = slot * SLOT_STRIDE;
+            const ka = data[off];
+
+            if (ka === 0) {
+                return false;
+            }
+            if (ka === ksa && data[off + 1] === key_b) {
+                break;
+            }
+
+            const home = this.__hash(ka, data[off + 1]) >>> shift;
+            const slot_dist = (slot - home) & mask;
+            if (dist > slot_dist) {
+                return false;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+
+        // backward-shift deletion
+        while (true) {
+            const next = (slot + 1) & mask;
+            const next_off = next * SLOT_STRIDE;
+            const next_ka = data[next_off];
+
+            if (next_ka === 0) {
+                break;
+            }
+
+            const next_home = this.__hash(next_ka, data[next_off + 1]) >>> shift;
+            const next_dist = (next - next_home) & mask;
+            if (next_dist === 0) {
+                break;
+            }
+
+            const off = slot * SLOT_STRIDE;
+            data[off] = next_ka;
+            data[off + 1] = data[next_off + 1];
+            data[off + 2] = data[next_off + 2];
+            slot = next;
+        }
+
+        const off = slot * SLOT_STRIDE;
+        data[off] = 0;
+        data[off + 1] = 0;
+        data[off + 2] = 0;
+
+        this.__size--;
+        return true;
+    }
+
+    clear() {
+        this.__data.fill(0);
+        this.__size = 0;
+    }
+
+    /**
+     * @private
+     * @param {number} new_capacity power of two
+     */
+    __resize(new_capacity) {
+        const old_data = this.__data;
+        const old_capacity = this.__capacity;
+
+        this.__capacity = new_capacity;
+        this.__mask = new_capacity - 1;
+        this.__shift = Math.clz32(new_capacity - 1);
+        this.__grow_threshold = (new_capacity * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        this.__data = new Uint32Array(new_capacity * SLOT_STRIDE);
+        this.__size = 0;
+
+        for (let i = 0; i < old_capacity; i++) {
+            const off = i * SLOT_STRIDE;
+            const a = old_data[off];
+            if (a !== 0) {
+                this.__insert_no_grow(a, old_data[off + 1], old_data[off + 2]);
+            }
+        }
+    }
+}
+
+/**
+ * @type {number}
+ */
+PairUint32Map.MAX_KEY = UINT32_MAX - 1;

package/src/core/collection/Uint32Map.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Returned by {@link Uint32Map#get} when the key is absent. Chosen so that any uint32 (0 .. UINT32_MAX) is
+ * unambiguously a valid value. As a JS Number this is a Smi on all V8 builds, so the return doesn't allocate.
+ * @type {number}
+ */
+export const UINT32_MAP_ABSENT: number;
+/**
+ * Non-allocating Map<uint32, uint32> backed by a single Uint32Array.
+ *
+ * Layout: one slot occupies two consecutive words — `data[2*slot] = key + 1`, `data[2*slot + 1] = value`.
+ * Keys are stored offset by +1 so that 0 is unambiguously "empty slot"; this also keeps every stored value
+ * inside the V8 Smi range (under pointer compression, Smi is 31-bit signed = max 2^30 − 1), which means
+ * reading any non-empty slot does not allocate a HeapNumber. Without the shift, a sentinel of 0xFFFFFFFF
+ * would box on every read of an empty slot — the exact opposite of what we want.
+ *
+ * Collision resolution: Robin Hood linear probing with backward-shift deletion (Knuth Algorithm R). Hash
+ * is Fibonacci multiplicative (see Skarupke 2018, "Fibonacci Hashing"), indexing from the high bits of
+ * the product. Table capacity is always a power of two; index is computed by right-shift, not by mask of
+ * the low bits — the high bits of a multiplicative hash have more entropy.
+ *
+ * Allowed key range: 0 .. UINT32_MAX - 1 (because we store key + 1). Allowed value range: full uint32.
+ * Values are returned via {@link UINT32_MAP_ABSENT} when not found — callers check `=== -1` rather than
+ * `=== undefined`, which is the Map API but is allocation-incompatible with typed-array storage.
+ */
+export class Uint32Map {
+    /**
+     *
+     * @param {number} [initial_capacity] minimum number of slots to reserve. Rounded up to next power of two.
+     */
+    constructor(initial_capacity?: number);
+    /**
+     * @type {number}
+     * @private
+     */
+    private __capacity;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __mask;
+    /**
+     * Right-shift amount that extracts log2(cap) high bits from a 32-bit hash.
+     * @type {number}
+     * @private
+     */
+    private __shift;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __grow_threshold;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __size;
+    /**
+     * Packed (key+1, value) pairs. Length is 2 * capacity. Zero-initialized so every slot starts empty.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __data;
+    /**
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     *
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     *
+     * @param {number} id
+     * @returns {number} value associated with `id`, or {@link UINT32_MAP_ABSENT} (-1) if not present.
+     */
+    get(id: number): number;
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    has(id: number): boolean;
+    /**
+     *
+     * @param {number} id
+     * @param {number} value
+     */
+    set(id: number, value: number): void;
+    /**
+     * Insert a (already key+1 shifted) entry assuming there is at least one empty slot. Performs Robin Hood
+     * swapping: when the new entry has been displaced further than the current occupant, swap them and
+     * continue placing the displaced occupant.
+     *
+     * @private
+     * @param {number} key_shifted
+     * @param {number} value
+     */
+    private __insert_no_grow;
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean} true if the entry existed and was removed.
+     */
+    delete(id: number): boolean;
+    /**
+     * Remove all entries. Capacity is unchanged.
+     */
+    clear(): void;
+    /**
+     * Grow the table and rehash every entry.
+     *
+     * @private
+     * @param {number} new_capacity power of two
+     */
+    private __resize;
+}
+//# sourceMappingURL=Uint32Map.d.ts.map

package/src/core/collection/Uint32Map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Uint32Map.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/Uint32Map.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AA6BpC;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEI;;;OAGG;IACH,+BAFW,MAAM,EA0ChB;IAhCG;;;OAGG;IACH,mBAAqB;IACrB;;;OAGG;IACH,eAAqB;IACrB;;;;OAIG;IACH,gBAAkC;IAClC;;;OAGG;IACH,yBAA2E;IAC3E;;;OAGG;IACH,eAAe;IACf;;;;OAIG;IACH,eAAuC;IAG3C;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,QAHW,MAAM,GACJ,MAAM,CAkClB;IAED;;;;OAIG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,QAHW,MAAM,SACN,MAAM,QAehB;IAED;;;;;;;;OAQG;IACH,yBA4CC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,OAAO,CA+DnB;IAED;;OAEG;IACH,cAGC;IAED;;;;;OAKG;IACH,iBAkBC;CACJ"}