@woosh/meep-engine 3.29.0 → 3.31.0

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

@@ -0,0 +1,105 @@
+/**
+ * Largest number of axes an {@link WFCLattice} can have.
+ *
+ * {@link WFCLattice#edge_flags} spends two bits per axis — one per side — in a `u32`.
+ * @type {number}
+ */
+export const WFC_MAX_DIMENSION_COUNT: number;
+/**
+ * An N-dimensional box of cells with per-axis wrapping. The topology the solver ships with, and
+ * the reason dimensionality is a number rather than three separate implementations.
+ *
+ * `WFCLattice.from_shape([64])` is 1-D, `[16, 16, 16]` is 3-D, `[8, 8, 8, 8]` is 4-D. Cells are
+ * numbered row-major — the last axis varies fastest — and {@link index_of} / {@link coordinate_of}
+ * convert between a cell index and coordinates.
+ *
+ * Direction `d` is `axis = d >> 1`, `side = d & 1` (0 toward the lower coordinate), and `d ^ 1` is
+ * the opposite direction. There are `2 × dimension_count` of them.
+ *
+ * At most {@link WFC_MAX_DIMENSION_COUNT} axes, which is what {@link edge_flags} can describe.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCLattice {
+    /**
+     * @param {number[]|Uint32Array} shape
+     * @param {boolean[]|Uint8Array} [wrap]
+     * @returns {WFCLattice}
+     */
+    static from_shape(shape: number[] | Uint32Array, wrap?: boolean[] | Uint8Array): WFCLattice;
+    /**
+     * Prefer {@link WFCLattice.from_shape}.
+     *
+     * @param {number[]|Uint32Array} shape extent along each axis, every entry at least 1
+     * @param {boolean[]|Uint8Array} [wrap] per axis; defaults to no wrapping
+     */
+    constructor(shape: number[] | Uint32Array, wrap?: boolean[] | Uint8Array);
+    /** @type {number} */
+    dimension_count: number;
+    /** @type {number} */
+    direction_count: number;
+    /** @type {Uint32Array} */
+    shape: Uint32Array;
+    /** @type {Uint8Array} */
+    wrap: Uint8Array;
+    /** @type {number} */
+    cell_count: number;
+    /**
+     * Row-major: the last axis is the fastest-varying.
+     * @type {Uint32Array}
+     */
+    strides: Uint32Array;
+    /**
+     * `neighbour_offsets[d]` — what to add to a cell index to step in direction `d`, valid
+     * only when the cell is not on the face `d` points off.
+     * @type {Int32Array}
+     */
+    neighbour_offsets: Int32Array;
+    /**
+     * `wrap_offsets[d]` — what to add instead when the cell *is* on the face `d` points off
+     * and that axis wraps.
+     *
+     * An axis of extent 1 gives an offset of zero, making the cell its own neighbour. That is
+     * correct — stepping off a one-cell ring lands back where it started — and it means such a
+     * tile must be compatible with itself along that axis.
+     * @type {Int32Array}
+     */
+    wrap_offsets: Int32Array;
+    /**
+     * Bit `d` set means the neighbour in direction `d` is outside the lattice.
+     * @type {Uint32Array}
+     */
+    edge_flags: Uint32Array;
+    /**
+     * Mark the two faces of every axis.
+     *
+     * @private
+     */
+    private __build_edge_flags;
+    /**
+     * Cell index of a coordinate — how a caller turns its own coordinates into the cell ids this
+     * module speaks in.
+     *
+     * @param {number[]|Uint32Array} coordinate one entry per axis
+     * @returns {number}
+     */
+    index_of(coordinate: number[] | Uint32Array): number;
+    /**
+     * Inverse of {@link index_of}, written into `out`.
+     *
+     * @param {number[]|Uint32Array} out at least `dimension_count` long
+     * @param {number} index
+     */
+    coordinate_of(out: number[] | Uint32Array, index: number): void;
+    /**
+     * The neighbour of `cell` in direction `direction`, or `-1` when there is none — off a
+     * non-wrapping face.
+     *
+     * @param {number} cell
+     * @param {number} direction
+     * @returns {number} neighbour cell index, or -1
+     */
+    neighbour_of(cell: number, direction: number): number;
+}
+//# sourceMappingURL=WFCLattice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WFCLattice.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCLattice.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;GAeG;AACH;IAwMI;;;;OAIG;IACH,yBAJW,MAAM,EAAE,GAAC,WAAW,SACpB,OAAO,EAAE,GAAC,UAAU,GAClB,UAAU,CAItB;IA9MD;;;;;OAKG;IACH,mBAHW,MAAM,EAAE,GAAC,WAAW,SACpB,OAAO,EAAE,GAAC,UAAU,EAgG9B;IA9EG,qBAAqB;IACrB,iBADW,MAAM,CACqB;IACtC,qBAAqB;IACrB,iBADW,MAAM,CACyB;IAE1C,0BAA0B;IAC1B,OADW,WAAW,CACuB;IAC7C,yBAAyB;IACzB,MADW,UAAU,CACsB;IAmB3C,qBAAqB;IACrB,YADW,MAAM,CACW;IAE5B;;;OAGG;IACH,SAFU,WAAW,CAE0B;IAQ/C;;;;OAIG;IACH,mBAFU,UAAU,CAEyC;IAE7D;;;;;;;;OAQG;IACH,cAFU,UAAU,CAEoC;IAaxD;;;OAGG;IACH,YAFU,WAAW,CAEwB;IAKjD;;;;OAIG;IACH,2BAmBC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,CAiBlB;IAED;;;;;OAKG;IACH,mBAHW,MAAM,EAAE,GAAC,WAAW,SACpB,MAAM,QAgBhB;IAED;;;;;;;OAOG;IACH,mBAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAiBlB;CAUJ"}

package/src/core/wfc/WFCLattice.js

@@ -0,0 +1,235 @@
+import { assert } from "../assert.js";
+
+/**
+ * Largest number of axes an {@link WFCLattice} can have.
+ *
+ * {@link WFCLattice#edge_flags} spends two bits per axis — one per side — in a `u32`.
+ * @type {number}
+ */
+export const WFC_MAX_DIMENSION_COUNT = 16;
+
+/**
+ * An N-dimensional box of cells with per-axis wrapping. The topology the solver ships with, and
+ * the reason dimensionality is a number rather than three separate implementations.
+ *
+ * `WFCLattice.from_shape([64])` is 1-D, `[16, 16, 16]` is 3-D, `[8, 8, 8, 8]` is 4-D. Cells are
+ * numbered row-major — the last axis varies fastest — and {@link index_of} / {@link coordinate_of}
+ * convert between a cell index and coordinates.
+ *
+ * Direction `d` is `axis = d >> 1`, `side = d & 1` (0 toward the lower coordinate), and `d ^ 1` is
+ * the opposite direction. There are `2 × dimension_count` of them.
+ *
+ * At most {@link WFC_MAX_DIMENSION_COUNT} axes, which is what {@link edge_flags} can describe.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCLattice {
+    /**
+     * Prefer {@link WFCLattice.from_shape}.
+     *
+     * @param {number[]|Uint32Array} shape extent along each axis, every entry at least 1
+     * @param {boolean[]|Uint8Array} [wrap] per axis; defaults to no wrapping
+     */
+    constructor(shape, wrap) {
+        assert.isArrayLike(shape, 'shape');
+
+        if (wrap !== undefined) {
+            assert.isArrayLike(wrap, 'wrap');
+            assert.greaterThanOrEqual(wrap.length, shape.length, 'wrap.length >= shape.length');
+        }
+
+        const dimension_count = shape.length;
+
+        assert.isPositiveInteger(dimension_count, 'shape.length');
+
+        if (dimension_count > WFC_MAX_DIMENSION_COUNT) {
+            throw new Error(`dimension_count(=${dimension_count}) exceeds ${WFC_MAX_DIMENSION_COUNT}; edge_flags holds two bits per axis`);
+        }
+
+        /** @type {number} */
+        this.dimension_count = dimension_count;
+        /** @type {number} */
+        this.direction_count = dimension_count * 2;
+
+        /** @type {Uint32Array} */
+        this.shape = new Uint32Array(dimension_count);
+        /** @type {Uint8Array} */
+        this.wrap = new Uint8Array(dimension_count);
+
+        let cell_count = 1;
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const extent = shape[axis];
+
+            assert.isPositiveInteger(extent, 'shape[axis]');
+
+            this.shape[axis] = extent;
+            this.wrap[axis] = (wrap !== undefined && wrap[axis]) ? 1 : 0;
+
+            cell_count *= extent;
+        }
+
+        if (!Number.isSafeInteger(cell_count)) {
+            throw new Error(`cell count overflows: shape ${Array.from(shape).join('x')}`);
+        }
+
+        /** @type {number} */
+        this.cell_count = cell_count;
+
+        /**
+         * Row-major: the last axis is the fastest-varying.
+         * @type {Uint32Array}
+         */
+        this.strides = new Uint32Array(dimension_count);
+
+        this.strides[dimension_count - 1] = 1;
+
+        for (let axis = dimension_count - 2; axis >= 0; axis--) {
+            this.strides[axis] = this.strides[axis + 1] * this.shape[axis + 1];
+        }
+
+        /**
+         * `neighbour_offsets[d]` — what to add to a cell index to step in direction `d`, valid
+         * only when the cell is not on the face `d` points off.
+         * @type {Int32Array}
+         */
+        this.neighbour_offsets = new Int32Array(this.direction_count);
+
+        /**
+         * `wrap_offsets[d]` — what to add instead when the cell *is* on the face `d` points off
+         * and that axis wraps.
+         *
+         * An axis of extent 1 gives an offset of zero, making the cell its own neighbour. That is
+         * correct — stepping off a one-cell ring lands back where it started — and it means such a
+         * tile must be compatible with itself along that axis.
+         * @type {Int32Array}
+         */
+        this.wrap_offsets = new Int32Array(this.direction_count);
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const stride = this.strides[axis];
+            const span = stride * (this.shape[axis] - 1);
+
+            this.neighbour_offsets[axis * 2] = -stride;
+            this.neighbour_offsets[axis * 2 + 1] = stride;
+
+            this.wrap_offsets[axis * 2] = span;
+            this.wrap_offsets[axis * 2 + 1] = -span;
+        }
+
+        /**
+         * Bit `d` set means the neighbour in direction `d` is outside the lattice.
+         * @type {Uint32Array}
+         */
+        this.edge_flags = new Uint32Array(cell_count);
+
+        this.__build_edge_flags();
+    }
+
+    /**
+     * Mark the two faces of every axis.
+     *
+     * @private
+     */
+    __build_edge_flags() {
+        const { cell_count, dimension_count, edge_flags, shape, strides } = this;
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const stride = strides[axis];
+            const extent = shape[axis];
+            const block = stride * extent;
+            const high_offset = stride * (extent - 1);
+
+            const low_bit = 1 << (axis * 2);
+            const high_bit = 1 << (axis * 2 + 1);
+
+            for (let block_start = 0; block_start < cell_count; block_start += block) {
+                for (let k = 0; k < stride; k++) {
+                    edge_flags[block_start + k] |= low_bit;
+                    edge_flags[block_start + high_offset + k] |= high_bit;
+                }
+            }
+        }
+    }
+
+    /**
+     * Cell index of a coordinate — how a caller turns its own coordinates into the cell ids this
+     * module speaks in.
+     *
+     * @param {number[]|Uint32Array} coordinate one entry per axis
+     * @returns {number}
+     */
+    index_of(coordinate) {
+        assert.equal(coordinate.length, this.dimension_count, 'coordinate.length === dimension_count');
+
+        let index = 0;
+
+        for (let axis = 0; axis < this.dimension_count; axis++) {
+            const value = coordinate[axis];
+
+            assert.isNonNegativeInteger(value, 'coordinate[axis]');
+            assert.lessThan(value, this.shape[axis], 'coordinate[axis] < shape[axis]');
+
+            index += value * this.strides[axis];
+        }
+
+        return index;
+    }
+
+    /**
+     * Inverse of {@link index_of}, written into `out`.
+     *
+     * @param {number[]|Uint32Array} out at least `dimension_count` long
+     * @param {number} index
+     */
+    coordinate_of(out, index) {
+        assert.isArrayLike(out, 'out');
+        assert.greaterThanOrEqual(out.length, this.dimension_count, 'out.length >= dimension_count');
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, this.cell_count, 'index < cell_count');
+
+        let rest = index;
+
+        for (let axis = 0; axis < this.dimension_count; axis++) {
+            const stride = this.strides[axis];
+
+            out[axis] = (rest / stride) | 0;
+            rest = rest % stride;
+        }
+    }
+
+    /**
+     * The neighbour of `cell` in direction `direction`, or `-1` when there is none — off a
+     * non-wrapping face.
+     *
+     * @param {number} cell
+     * @param {number} direction
+     * @returns {number} neighbour cell index, or -1
+     */
+    neighbour_of(cell, direction) {
+        assert.isNonNegativeInteger(cell, 'cell');
+        assert.isNonNegativeInteger(direction, 'direction');
+        assert.lessThan(cell, this.cell_count, 'cell < cell_count');
+        assert.lessThan(direction, this.direction_count, 'direction < direction_count');
+
+        if (((this.edge_flags[cell] >> direction) & 1) === 1) {
+            if (this.wrap[direction >> 1] === 0) {
+                return -1;
+            }
+
+            return cell + this.wrap_offsets[direction];
+        }
+
+        return cell + this.neighbour_offsets[direction];
+    }
+
+    /**
+     * @param {number[]|Uint32Array} shape
+     * @param {boolean[]|Uint8Array} [wrap]
+     * @returns {WFCLattice}
+     */
+    static from_shape(shape, wrap) {
+        return new WFCLattice(shape, wrap);
+    }
+}

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"}