@woosh/meep-engine 3.29.0 → 3.30.0

package/src/core/wfc/WFCRuleTable.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Bits that name real tiles in the final word of a `words_per_cell`-word mask.
+ *
+ * A named function because the natural spelling `(1 << (tile_count & 31)) - 1` yields `0` — every
+ * tile dead — at exactly 32, 64, 96 … tiles, JavaScript taking the shift count modulo 32.
+ *
+ * @param {number} tile_count
+ * @returns {number}
+ */
+export function wfc_tail_mask(tile_count: number): number;
+/**
+ * Bytes a {@link WFCRuleTable} of this shape would hold, without building one.
+ *
+ * @param {number} tile_count
+ * @param {number} direction_count
+ * @returns {number}
+ */
+export function wfc_rule_table_byte_size(tile_count: number, direction_count: number): number;
+/**
+ * Is the table symmetric under `d ^ 1` — does `t` allow `u` across `d` exactly when `u` allows `t`
+ * across `d ^ 1`?
+ *
+ * Propagation assumes this. A table built only from {@link WFCRuleTable#allow_symmetric} and
+ * {@link WFCRuleTable#deny_symmetric} has it by construction; check one that did not.
+ *
+ * `O(tile_count² × direction_count)` — a build-time check, not a per-solve one.
+ *
+ * @param {WFCRuleTable} rules
+ * @returns {boolean}
+ */
+export function wfc_rule_table_is_symmetric(rules: WFCRuleTable): boolean;
+/**
+ * Which adjacencies are legal, as one flat bit table.
+ *
+ * `data[((d * tile_count) + t) * words_per_cell + w]` — bit `b` set means "tile `w*32 + b` may sit
+ * at the neighbour reached by stepping in direction `d` away from a tile `t`".
+ *
+ * **Directions.** `direction_count` must be even. Direction `d` is `axis = d >> 1`,
+ * `side = d & 1`, and `d ^ 1` is the opposite direction. Propagation is sound only if the table is
+ * symmetric under that involution, so build one with {@link allow_symmetric} and
+ * {@link deny_symmetric}; {@link allow_directed} is for deliberately asymmetric tables and is the
+ * documented way to get it wrong. {@link wfc_rule_table_is_symmetric} checks.
+ *
+ * **Size is quadratic in the tile count** — `direction_count × tile_count × ceil(tile_count/32) × 4`
+ * bytes: 2 KiB at 64 tiles in 2-D, 32 KiB at 256 (about one L1), 12 MiB at 4096 in 3-D. The design
+ * assumes this table is small enough to stay hot, so check {@link wfc_rule_table_byte_size} before
+ * committing to a large tile count.
+ *
+ * Call {@link finalize} after the last mutation and before building a {@link WFCState}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCRuleTable {
+    /**
+     * @param {number} tile_count number of distinct tiles, at least 1
+     * @param {number} direction_count `2 × dimension_count`, at least 2 and even
+     */
+    constructor(tile_count: number, direction_count: number);
+    /** @type {number} */
+    tile_count: number;
+    /** @type {number} */
+    direction_count: number;
+    /** @type {number} */
+    words_per_cell: number;
+    /**
+     * Bits at or above `tile_count` in the final word of a row. Every write masks with this,
+     * so no rule row can name a tile that does not exist and the wave's tail invariant is
+     * never threatened from this side.
+     * @type {number}
+     * @private
+     */
+    private __tail_mask;
+    /**
+     * `direction_count × tile_count` rows of `words_per_cell` words.
+     * @type {Uint32Array}
+     */
+    data: Uint32Array;
+    /**
+     * `full_support[d * words_per_cell + w]` — the union of every tile's row in direction `d`.
+     *
+     * Read by the propagator, which uses it to relax across a cell that has lost nothing in
+     * `O(words_per_cell)` rather than scanning that cell's whole domain.
+     *
+     * Built by {@link finalize}; stale until then.
+     * @type {Uint32Array}
+     */
+    full_support: Uint32Array;
+    /**
+     * @type {boolean}
+     * @private
+     */
+    private __finalized;
+    /**
+     * @returns {boolean}
+     */
+    get finalized(): boolean;
+    /**
+     * Bytes held by {@link data} and {@link full_support}.
+     * @returns {number}
+     */
+    get byte_size(): number;
+    /**
+     * Every adjacency legal. The starting point for a table you build by denying.
+     */
+    fill_allow(): void;
+    /**
+     * No adjacency legal. The starting point for a table you build by allowing.
+     */
+    fill_deny(): void;
+    /**
+     * Allow `tile_b` to sit on the `direction` side of `tile_a`, **and** `tile_a` to sit on the
+     * opposite side of `tile_b`.
+     *
+     * This is the mutator to use. The one-sided {@link allow_directed} exists for callers building
+     * a deliberately asymmetric table, and is the documented way to make propagation unsound.
+     *
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    allow_symmetric(direction: number, tile_a: number, tile_b: number): void;
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    deny_symmetric(direction: number, tile_a: number, tile_b: number): void;
+    /**
+     * Allow `tile_b` to sit on the `direction` side of `tile_a`, and say nothing about the reverse.
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    allow_directed(direction: number, tile_a: number, tile_b: number): void;
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    deny_directed(direction: number, tile_a: number, tile_b: number): void;
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     * @returns {boolean} may `tile_b` sit on the `direction` side of `tile_a`?
+     */
+    allows(direction: number, tile_a: number, tile_b: number): boolean;
+    /**
+     * Build {@link full_support}. Must be called after the last mutation and before a
+     * {@link WFCState} is built against this table; every mutator clears the flag.
+     *
+     * Builds nothing else. In particular a tile whose rule row is empty in some direction is left
+     * alone rather than removed, because such a tile can still sit legally on the matching border,
+     * where there is no neighbour that way. {@link rows_without_support} reports them.
+     */
+    finalize(): void;
+    /**
+     * Diagnostic: `(direction, tile)` pairs whose rule row is empty.
+     *
+     * Such a tile can only be placed where the lattice has no neighbour in that direction — on the
+     * matching border, or nowhere at all if the axis wraps. Usually it means a rule was forgotten,
+     * but a border-only tile is legitimate, so this is reported rather than treated as an error.
+     *
+     * @returns {{direction:number, tile:number}[]}
+     */
+    rows_without_support(): {
+        direction: number;
+        tile: number;
+    }[];
+}
+//# sourceMappingURL=WFCRuleTable.d.ts.map

package/src/core/wfc/WFCRuleTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WFCRuleTable.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCRuleTable.js"],"names":[],"mappings":"AAqRA;;;;;;;;GAQG;AACH,0CAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;GAMG;AACH,qDAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;;;;GAWG;AACH,mDAHW,YAAY,GACV,OAAO,CAkBnB;AAzUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IACI;;;OAGG;IACH,wBAHW,MAAM,mBACN,MAAM,EAuDhB;IAtCG,qBAAqB;IACrB,YADW,MAAM,CACW;IAC5B,qBAAqB;IACrB,iBADW,MAAM,CACqB;IACtC,qBAAqB;IACrB,gBADW,MAAM,CACmB;IAEpC;;;;;;OAMG;IACH,oBAA4C;IAE5C;;;OAGG;IACH,MAFU,WAAW,CAEqD;IAE1E;;;;;;;;OAQG;IACH,cAFU,WAAW,CAEgD;IAErE;;;OAGG;IACH,oBAAwB;IAG5B;;OAEG;IACH,yBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,mBAaC;IAED;;OAEG;IACH,kBAGC;IAED;;;;;;;;;;OAUG;IACH,2BAJW,MAAM,UACN,MAAM,UACN,MAAM,QAKhB;IAED;;;;OAIG;IACH,0BAJW,MAAM,UACN,MAAM,UACN,MAAM,QAKhB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,UACN,MAAM,UACN,MAAM,QAehB;IAED;;;;OAIG;IACH,yBAJW,MAAM,UACN,MAAM,UACN,MAAM,QAehB;IAED;;;;;OAKG;IACH,kBALW,MAAM,UACN,MAAM,UACN,MAAM,GACJ,OAAO,CAanB;IAED;;;;;;;OAOG;IACH,iBAmBC;IAED;;;;;;;;OAQG;IACH,wBAFa;QAAC,SAAS,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,EAAE,CAyB7C;CACJ"}

package/src/core/wfc/WFCRuleTable.js

@@ -0,0 +1,334 @@
+import { assert } from "../assert.js";
+import { WFC_UNRESOLVED } from "./WFC_UNRESOLVED.js";
+import { wfc_words_per_cell } from "./wfc_words_per_cell.js";
+
+/**
+ * Which adjacencies are legal, as one flat bit table.
+ *
+ * `data[((d * tile_count) + t) * words_per_cell + w]` — bit `b` set means "tile `w*32 + b` may sit
+ * at the neighbour reached by stepping in direction `d` away from a tile `t`".
+ *
+ * **Directions.** `direction_count` must be even. Direction `d` is `axis = d >> 1`,
+ * `side = d & 1`, and `d ^ 1` is the opposite direction. Propagation is sound only if the table is
+ * symmetric under that involution, so build one with {@link allow_symmetric} and
+ * {@link deny_symmetric}; {@link allow_directed} is for deliberately asymmetric tables and is the
+ * documented way to get it wrong. {@link wfc_rule_table_is_symmetric} checks.
+ *
+ * **Size is quadratic in the tile count** — `direction_count × tile_count × ceil(tile_count/32) × 4`
+ * bytes: 2 KiB at 64 tiles in 2-D, 32 KiB at 256 (about one L1), 12 MiB at 4096 in 3-D. The design
+ * assumes this table is small enough to stay hot, so check {@link wfc_rule_table_byte_size} before
+ * committing to a large tile count.
+ *
+ * Call {@link finalize} after the last mutation and before building a {@link WFCState}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCRuleTable {
+    /**
+     * @param {number} tile_count number of distinct tiles, at least 1
+     * @param {number} direction_count `2 × dimension_count`, at least 2 and even
+     */
+    constructor(tile_count, direction_count) {
+        assert.isPositiveInteger(tile_count, 'tile_count');
+        assert.isPositiveInteger(direction_count, 'direction_count');
+
+        if (tile_count >= WFC_UNRESOLVED) {
+            // the read-out sentinel would collide with a real tile id
+            throw new Error(`tile_count(=${tile_count}) must be below ${WFC_UNRESOLVED}`);
+        }
+
+        if ((direction_count & 1) !== 0) {
+            throw new Error(`direction_count(=${direction_count}) must be even; d ^ 1 is the opposite direction`);
+        }
+
+        const words_per_cell = wfc_words_per_cell(tile_count);
+
+        /** @type {number} */
+        this.tile_count = tile_count;
+        /** @type {number} */
+        this.direction_count = direction_count;
+        /** @type {number} */
+        this.words_per_cell = words_per_cell;
+
+        /**
+         * Bits at or above `tile_count` in the final word of a row. Every write masks with this,
+         * so no rule row can name a tile that does not exist and the wave's tail invariant is
+         * never threatened from this side.
+         * @type {number}
+         * @private
+         */
+        this.__tail_mask = wfc_tail_mask(tile_count);
+
+        /**
+         * `direction_count × tile_count` rows of `words_per_cell` words.
+         * @type {Uint32Array}
+         */
+        this.data = new Uint32Array(direction_count * tile_count * words_per_cell);
+
+        /**
+         * `full_support[d * words_per_cell + w]` — the union of every tile's row in direction `d`.
+         *
+         * Read by the propagator, which uses it to relax across a cell that has lost nothing in
+         * `O(words_per_cell)` rather than scanning that cell's whole domain.
+         *
+         * Built by {@link finalize}; stale until then.
+         * @type {Uint32Array}
+         */
+        this.full_support = new Uint32Array(direction_count * words_per_cell);
+
+        /**
+         * @type {boolean}
+         * @private
+         */
+        this.__finalized = false;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get finalized() {
+        return this.__finalized;
+    }
+
+    /**
+     * Bytes held by {@link data} and {@link full_support}.
+     * @returns {number}
+     */
+    get byte_size() {
+        return this.data.byteLength + this.full_support.byteLength;
+    }
+
+    /**
+     * Every adjacency legal. The starting point for a table you build by denying.
+     */
+    fill_allow() {
+        const { data, words_per_cell } = this;
+        const last = words_per_cell - 1;
+        const tail = this.__tail_mask;
+
+        data.fill(0xFFFFFFFF);
+
+        // the final word of every row carries only the bits that name real tiles
+        for (let address = last; address < data.length; address += words_per_cell) {
+            data[address] = tail;
+        }
+
+        this.__finalized = false;
+    }
+
+    /**
+     * No adjacency legal. The starting point for a table you build by allowing.
+     */
+    fill_deny() {
+        this.data.fill(0);
+        this.__finalized = false;
+    }
+
+    /**
+     * Allow `tile_b` to sit on the `direction` side of `tile_a`, **and** `tile_a` to sit on the
+     * opposite side of `tile_b`.
+     *
+     * This is the mutator to use. The one-sided {@link allow_directed} exists for callers building
+     * a deliberately asymmetric table, and is the documented way to make propagation unsound.
+     *
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    allow_symmetric(direction, tile_a, tile_b) {
+        this.allow_directed(direction, tile_a, tile_b);
+        this.allow_directed(direction ^ 1, tile_b, tile_a);
+    }
+
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    deny_symmetric(direction, tile_a, tile_b) {
+        this.deny_directed(direction, tile_a, tile_b);
+        this.deny_directed(direction ^ 1, tile_b, tile_a);
+    }
+
+    /**
+     * Allow `tile_b` to sit on the `direction` side of `tile_a`, and say nothing about the reverse.
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    allow_directed(direction, tile_a, tile_b) {
+        assert.isNonNegativeInteger(direction, 'direction');
+        assert.isNonNegativeInteger(tile_a, 'tile_a');
+        assert.isNonNegativeInteger(tile_b, 'tile_b');
+        assert.lessThan(direction, this.direction_count, 'direction < direction_count');
+        assert.lessThan(tile_a, this.tile_count, 'tile_a < tile_count');
+        assert.lessThan(tile_b, this.tile_count, 'tile_b < tile_count');
+
+        const row = ((direction * this.tile_count) + tile_a) * this.words_per_cell;
+
+        this.data[row + (tile_b >> 5)] |= (1 << (tile_b & 31));
+
+        this.__finalized = false;
+    }
+
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     */
+    deny_directed(direction, tile_a, tile_b) {
+        assert.isNonNegativeInteger(direction, 'direction');
+        assert.isNonNegativeInteger(tile_a, 'tile_a');
+        assert.isNonNegativeInteger(tile_b, 'tile_b');
+        assert.lessThan(direction, this.direction_count, 'direction < direction_count');
+        assert.lessThan(tile_a, this.tile_count, 'tile_a < tile_count');
+        assert.lessThan(tile_b, this.tile_count, 'tile_b < tile_count');
+
+        const row = ((direction * this.tile_count) + tile_a) * this.words_per_cell;
+
+        this.data[row + (tile_b >> 5)] &= ~(1 << (tile_b & 31));
+
+        this.__finalized = false;
+    }
+
+    /**
+     * @param {number} direction
+     * @param {number} tile_a
+     * @param {number} tile_b
+     * @returns {boolean} may `tile_b` sit on the `direction` side of `tile_a`?
+     */
+    allows(direction, tile_a, tile_b) {
+        assert.isNonNegativeInteger(direction, 'direction');
+        assert.isNonNegativeInteger(tile_a, 'tile_a');
+        assert.isNonNegativeInteger(tile_b, 'tile_b');
+        assert.lessThan(direction, this.direction_count, 'direction < direction_count');
+        assert.lessThan(tile_a, this.tile_count, 'tile_a < tile_count');
+        assert.lessThan(tile_b, this.tile_count, 'tile_b < tile_count');
+
+        const row = ((direction * this.tile_count) + tile_a) * this.words_per_cell;
+
+        return (this.data[row + (tile_b >> 5)] & (1 << (tile_b & 31))) !== 0;
+    }
+
+    /**
+     * Build {@link full_support}. Must be called after the last mutation and before a
+     * {@link WFCState} is built against this table; every mutator clears the flag.
+     *
+     * Builds nothing else. In particular a tile whose rule row is empty in some direction is left
+     * alone rather than removed, because such a tile can still sit legally on the matching border,
+     * where there is no neighbour that way. {@link rows_without_support} reports them.
+     */
+    finalize() {
+        const { data, full_support, tile_count, direction_count, words_per_cell } = this;
+
+        full_support.fill(0);
+
+        for (let d = 0; d < direction_count; d++) {
+            const support_base = d * words_per_cell;
+            const direction_base = d * tile_count * words_per_cell;
+
+            for (let t = 0; t < tile_count; t++) {
+                const row = direction_base + t * words_per_cell;
+
+                for (let w = 0; w < words_per_cell; w++) {
+                    full_support[support_base + w] |= data[row + w];
+                }
+            }
+        }
+
+        this.__finalized = true;
+    }
+
+    /**
+     * Diagnostic: `(direction, tile)` pairs whose rule row is empty.
+     *
+     * Such a tile can only be placed where the lattice has no neighbour in that direction — on the
+     * matching border, or nowhere at all if the axis wraps. Usually it means a rule was forgotten,
+     * but a border-only tile is legitimate, so this is reported rather than treated as an error.
+     *
+     * @returns {{direction:number, tile:number}[]}
+     */
+    rows_without_support() {
+        const { data, tile_count, direction_count, words_per_cell } = this;
+        const result = [];
+
+        for (let d = 0; d < direction_count; d++) {
+            const direction_base = d * tile_count * words_per_cell;
+
+            for (let t = 0; t < tile_count; t++) {
+                const row = direction_base + t * words_per_cell;
+
+                let any = 0;
+
+                for (let w = 0; w < words_per_cell; w++) {
+                    any |= data[row + w];
+                }
+
+                if (any === 0) {
+                    result.push({ direction: d, tile: t });
+                }
+            }
+        }
+
+        return result;
+    }
+}
+
+/**
+ * Bits that name real tiles in the final word of a `words_per_cell`-word mask.
+ *
+ * A named function because the natural spelling `(1 << (tile_count & 31)) - 1` yields `0` — every
+ * tile dead — at exactly 32, 64, 96 … tiles, JavaScript taking the shift count modulo 32.
+ *
+ * @param {number} tile_count
+ * @returns {number}
+ */
+export function wfc_tail_mask(tile_count) {
+    const remainder = tile_count & 31;
+
+    return remainder === 0 ? 0xFFFFFFFF : (((1 << remainder) >>> 0) - 1);
+}
+
+/**
+ * Bytes a {@link WFCRuleTable} of this shape would hold, without building one.
+ *
+ * @param {number} tile_count
+ * @param {number} direction_count
+ * @returns {number}
+ */
+export function wfc_rule_table_byte_size(tile_count, direction_count) {
+    const words_per_cell = wfc_words_per_cell(tile_count);
+
+    return (direction_count * tile_count * words_per_cell * 4) + (direction_count * words_per_cell * 4);
+}
+
+/**
+ * Is the table symmetric under `d ^ 1` — does `t` allow `u` across `d` exactly when `u` allows `t`
+ * across `d ^ 1`?
+ *
+ * Propagation assumes this. A table built only from {@link WFCRuleTable#allow_symmetric} and
+ * {@link WFCRuleTable#deny_symmetric} has it by construction; check one that did not.
+ *
+ * `O(tile_count² × direction_count)` — a build-time check, not a per-solve one.
+ *
+ * @param {WFCRuleTable} rules
+ * @returns {boolean}
+ */
+export function wfc_rule_table_is_symmetric(rules) {
+    const { tile_count, direction_count } = rules;
+
+    for (let d = 0; d < direction_count; d++) {
+        const opposite = d ^ 1;
+
+        for (let a = 0; a < tile_count; a++) {
+            for (let b = 0; b < tile_count; b++) {
+                if (rules.allows(d, a, b) !== rules.allows(opposite, b, a)) {
+                    return false;
+                }
+            }
+        }
+    }
+
+    return true;
+}