@woosh/meep-engine 3.29.0 → 3.31.0

package/src/core/wfc/WFCTileWeights.js

@@ -0,0 +1,86 @@
+import { assert } from "../assert.js";
+
+/**
+ * Relative placement likelihoods, one per tile.
+ *
+ * Nothing is normalised — `[1, 9]` and `[0.1, 0.9]` behave identically.
+ *
+ * Weights must be finite and strictly positive; a non-positive one throws. A zero-weight tile
+ * would sit in a cell's domain, count toward its possibility count and never be selected, which
+ * surfaces much later as a solve that cannot finish. A tile you do not want is one you leave out
+ * of the rule table.
+ *
+ * Held apart from {@link WFCRuleTable} so the same structure can be solved with different
+ * preferences.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCTileWeights {
+    /**
+     * @param {number[]|Float64Array} weights one strictly positive, finite weight per tile
+     */
+    constructor(weights) {
+        assert.isArrayLike(weights, 'weights');
+
+        const tile_count = weights.length;
+
+        assert.isPositiveInteger(tile_count, 'weights.length');
+
+        /** @type {number} */
+        this.tile_count = tile_count;
+
+        /** @type {Float64Array} */
+        this.weight = new Float64Array(tile_count);
+
+        /**
+         * `w · ln(w)`, the numerator term of the Shannon entropy of a weighted domain.
+         * @type {Float64Array}
+         */
+        this.weight_log_weight = new Float64Array(tile_count);
+
+        let total = 0;
+        let total_log = 0;
+
+        for (let t = 0; t < tile_count; t++) {
+            const w = weights[t];
+
+            // a real throw, not an assertion: consumers strip assert.* out of shipped builds, and
+            // a non-positive weight here surfaces much later as a solve that never terminates
+            if (!(w > 0) || !Number.isFinite(w)) {
+                throw new Error(`weight[${t}](=${w}) must be finite and strictly positive`);
+            }
+
+            const wlw = w * Math.log(w);
+
+            this.weight[t] = w;
+            this.weight_log_weight[t] = wlw;
+
+            total += w;
+            total_log += wlw;
+        }
+
+        /**
+         * Sum over every tile — the value a pristine cell's running sum starts at.
+         * @type {number}
+         */
+        this.total_weight = total;
+
+        /**
+         * @type {number}
+         */
+        this.total_weight_log_weight = total_log;
+    }
+
+    /**
+     * Every tile equally likely — the same as passing an array of ones.
+     *
+     * @param {number} tile_count
+     * @returns {WFCTileWeights}
+     */
+    static uniform(tile_count) {
+        assert.isPositiveInteger(tile_count, 'tile_count');
+
+        return new WFCTileWeights(new Float64Array(tile_count).fill(1));
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Written into the output of {@link wfc_state_read} for a cell that is not down to a single
+ * possibility — either the solve has not finished, or the cell was never eligible to be collapsed.
+ *
+ * Non-negative so the output can be a `Uint32Array`. {@link WFCRuleTable} rejects tile counts that
+ * would reach it, so it can never collide with a real tile id.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const WFC_UNRESOLVED: number;
+//# sourceMappingURL=WFC_UNRESOLVED.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WFC_UNRESOLVED.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFC_UNRESOLVED.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,6BAFU,MAAM,CAEyB"}

package/src/core/wfc/WFC_UNRESOLVED.js

@@ -0,0 +1,11 @@
+/**
+ * Written into the output of {@link wfc_state_read} for a cell that is not down to a single
+ * possibility — either the solve has not finished, or the cell was never eligible to be collapsed.
+ *
+ * Non-negative so the output can be a `Uint32Array`. {@link WFCRuleTable} rejects tile counts that
+ * would reach it, so it can never collide with a real tile id.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const WFC_UNRESOLVED = 0xFFFFFFFF;

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

@@ -0,0 +1,24 @@
+/**
+ * What a solve of this shape costs in memory, before building anything.
+ *
+ * Reported separately because the terms scale differently: `rules` grows as `tile_count²` and
+ * wants to stay in cache, `state` grows with the grid and decides whether a problem fits at all,
+ * `lattice` is a flat four bytes a cell, and `heap` is only allocated by the cell-choice policies
+ * that need one.
+ *
+ * Excludes the undo trail and decision stack, which grow with how hard the search turns out to be
+ * rather than with the problem's shape.
+ *
+ * @param {number} tile_count
+ * @param {number} direction_count
+ * @param {number} cell_count
+ * @returns {{rules:number, state:number, lattice:number, heap:number, total:number}}
+ */
+export function wfc_estimate_bytes(tile_count: number, direction_count: number, cell_count: number): {
+    rules: number;
+    state: number;
+    lattice: number;
+    heap: number;
+    total: number;
+};
+//# sourceMappingURL=wfc_estimate_bytes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_estimate_bytes.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_estimate_bytes.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,+CALW,MAAM,mBACN,MAAM,cACN,MAAM,GACJ;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,OAAO,EAAC,MAAM,CAAC;IAAC,IAAI,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAA;CAAC,CA6BnF"}

package/src/core/wfc/wfc_estimate_bytes.js

@@ -0,0 +1,47 @@
+import { assert } from "../assert.js";
+import { wfc_words_per_cell } from "./wfc_words_per_cell.js";
+
+/**
+ * What a solve of this shape costs in memory, before building anything.
+ *
+ * Reported separately because the terms scale differently: `rules` grows as `tile_count²` and
+ * wants to stay in cache, `state` grows with the grid and decides whether a problem fits at all,
+ * `lattice` is a flat four bytes a cell, and `heap` is only allocated by the cell-choice policies
+ * that need one.
+ *
+ * Excludes the undo trail and decision stack, which grow with how hard the search turns out to be
+ * rather than with the problem's shape.
+ *
+ * @param {number} tile_count
+ * @param {number} direction_count
+ * @param {number} cell_count
+ * @returns {{rules:number, state:number, lattice:number, heap:number, total:number}}
+ */
+export function wfc_estimate_bytes(tile_count, direction_count, cell_count) {
+    assert.isPositiveInteger(tile_count, 'tile_count');
+    assert.isPositiveInteger(direction_count, 'direction_count');
+    assert.isPositiveInteger(cell_count, 'cell_count');
+
+    const words_per_cell = wfc_words_per_cell(tile_count);
+
+    const rules = (direction_count * tile_count * words_per_cell * 4)
+        + (direction_count * words_per_cell * 4);
+
+    // weight_sum + weight_log_sum (8 each), wave (4 per word), possibility_count + queue +
+    // dirty_list (4 each), in_queue + dirty + eligible (1 each)
+    const state = cell_count * (16 + (words_per_cell * 4) + 12 + 3);
+
+    const lattice = cell_count * 4;
+
+    // IndexedFloatMinHeap: a 4-byte id->slot entry per cell, plus 8 bytes per occupied slot, and
+    // every cell can be in it at once
+    const heap = cell_count * 12;
+
+    return {
+        rules,
+        state,
+        lattice,
+        heap,
+        total: rules + state + lattice + heap
+    };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Partition the tiles into connected components of the adjacency graph — `t` and `u` are joined
+ * when `t` may touch `u` in any direction.
+ *
+ * **Every solution draws its tiles from exactly one component**, because a lattice is connected
+ * and each step along a path between two cells forces their tiles to be adjacent in this graph.
+ *
+ * More than one component is therefore worth knowing about: the solve still succeeds, it just
+ * picks a component and never emits anything from the others, so a tile set that has accidentally
+ * split loses tiles with no error anywhere.
+ * {@link WFCRuleTable#rows_without_support} does not catch this — every tile in every island can
+ * still have support in every direction.
+ *
+ * Reported rather than acted on, since a tile set deliberately holding two alternatives to pick
+ * between per solve is legitimate.
+ *
+ * The graph unions over every direction, which can only merge components a lattice using fewer
+ * directions would keep apart. The partition is therefore coarser than the truth, so "different
+ * components" is always sound while "same component" does not prove reachability.
+ *
+ * @param {Uint32Array|number[]} out_component at least `tile_count` long; receives a component id
+ *        in `[0, count)` for each tile, numbered by the smallest tile in each so they are stable
+ * @param {WFCRuleTable} rules
+ * @returns {number} number of components
+ */
+export function wfc_rule_table_tile_components(out_component: Uint32Array | number[], rules: WFCRuleTable): number;
+//# sourceMappingURL=wfc_rule_table_tile_components.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_rule_table_tile_components.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_rule_table_tile_components.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8DALW,WAAW,GAAC,MAAM,EAAE,wBAGlB,MAAM,CAoDlB"}

package/src/core/wfc/wfc_rule_table_tile_components.js

@@ -0,0 +1,80 @@
+import { assert } from "../assert.js";
+import { ctz32 } from "../binary/ctz32.js";
+import { uf_find, uf_init, uf_union } from "../collection/union-find/union_find.js";
+
+/**
+ * Partition the tiles into connected components of the adjacency graph — `t` and `u` are joined
+ * when `t` may touch `u` in any direction.
+ *
+ * **Every solution draws its tiles from exactly one component**, because a lattice is connected
+ * and each step along a path between two cells forces their tiles to be adjacent in this graph.
+ *
+ * More than one component is therefore worth knowing about: the solve still succeeds, it just
+ * picks a component and never emits anything from the others, so a tile set that has accidentally
+ * split loses tiles with no error anywhere.
+ * {@link WFCRuleTable#rows_without_support} does not catch this — every tile in every island can
+ * still have support in every direction.
+ *
+ * Reported rather than acted on, since a tile set deliberately holding two alternatives to pick
+ * between per solve is legitimate.
+ *
+ * The graph unions over every direction, which can only merge components a lattice using fewer
+ * directions would keep apart. The partition is therefore coarser than the truth, so "different
+ * components" is always sound while "same component" does not prove reachability.
+ *
+ * @param {Uint32Array|number[]} out_component at least `tile_count` long; receives a component id
+ *        in `[0, count)` for each tile, numbered by the smallest tile in each so they are stable
+ * @param {WFCRuleTable} rules
+ * @returns {number} number of components
+ */
+export function wfc_rule_table_tile_components(out_component, rules) {
+    assert.defined(rules, 'rules');
+    assert.isArrayLike(out_component, 'out_component');
+    assert.greaterThanOrEqual(out_component.length, rules.tile_count, 'out_component.length >= tile_count');
+
+    const { data, tile_count, direction_count, words_per_cell } = rules;
+
+    // one allocation for a diagnostic that runs once per rule table, rather than module-static
+    // scratch that two callers could share
+    const parent = new Uint32Array(tile_count);
+
+    uf_init(parent, tile_count);
+
+    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;
+
+            for (let w = 0; w < words_per_cell; w++) {
+                let word = data[row + w];
+                const tile_base = w << 5;
+
+                while (word !== 0) {
+                    const low = word & -word;
+
+                    word ^= low;
+
+                    uf_union(parent, t, tile_base + ctz32(low));
+                }
+            }
+        }
+    }
+
+    // `uf_union` keeps the smallest index as the root, so walking tiles in ascending order and
+    // numbering each root the first time it appears gives ids ordered by their smallest member
+    let count = 0;
+
+    for (let t = 0; t < tile_count; t++) {
+        const root = uf_find(parent, t);
+
+        if (root === t) {
+            out_component[t] = count;
+            count++;
+        } else {
+            out_component[t] = out_component[root];
+        }
+    }
+
+    return count;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Drive the solve until it finishes, proves the instance unsatisfiable, or runs out of budget.
+ *
+ * Returning {@link WFCStatus.RUNNING} means only that the budget ran out; call again to continue,
+ * including part-way through a propagation wave. That makes the solver drivable from a task graph
+ * or a frame loop without this module knowing about either.
+ *
+ * An operation is one edge relaxation or one collapse, so the budget tracks work rather than
+ * wall-clock.
+ *
+ * @param {WFCState} state
+ * @param {number} [max_operations] relaxations and collapses this call may perform
+ * @param {number} [max_backtracks] cumulative across calls, not per call; defaults to one per
+ *        cell. Exceeding it returns {@link WFCStatus.EXHAUSTED}, whose conventional answer is to
+ *        restart with a different seed.
+ * @returns {WFCStatus}
+ */
+export function wfc_solve(state: WFCState, max_operations?: number, max_backtracks?: number): WFCStatus;
+import { WFCState } from "./WFCState.js";
+import { WFCStatus } from "./WFCStatus.js";
+//# sourceMappingURL=wfc_solve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_solve.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_solve.js"],"names":[],"mappings":"AA2EA;;;;;;;;;;;;;;;;GAgBG;AACH,iCAPW,QAAQ,mBACR,MAAM,mBACN,MAAM,GAGJ,SAAS,CA+DrB;yBAxJwB,eAAe;0BACd,gBAAgB"}

package/src/core/wfc/wfc_solve.js

@@ -0,0 +1,154 @@
+import { assert } from "../assert.js";
+import { WFCState } from "./WFCState.js";
+import { WFCStatus } from "./WFCStatus.js";
+import { wfc_state_ban_bits } from "./wfc_state_ban_bits.js";
+import { wfc_state_collapse } from "./wfc_state_collapse.js";
+import { wfc_state_flush_dirty } from "./wfc_state_flush_dirty.js";
+import { wfc_state_propagate } from "./wfc_state_propagate.js";
+import { wfc_state_undo_to } from "./wfc_state_undo_to.js";
+
+/**
+ * Next cell to collapse, or `-1` when none is left.
+ *
+ * @param {WFCState} state
+ * @returns {number}
+ * @private
+ */
+function select_cell(state) {
+    const heap = state.heap;
+
+    if (heap !== null) {
+        // the flush keeps the heap in step with the wave, so a popped cell should always still be
+        // undecided; skipping rather than trusting turns a bookkeeping slip into a wasted decision
+        // instead of a spurious contradiction
+        for (let cell = heap.pop_min(); cell !== -1; cell = heap.pop_min()) {
+            if (state.possibility_count[cell] > 1 && state.eligible[cell] === 1) {
+                return cell;
+            }
+        }
+
+        return -1;
+    }
+
+    const { cell_count, eligible, possibility_count } = state;
+
+    let cursor = state.scan_cursor;
+
+    while (cursor < cell_count && (eligible[cursor] === 0 || possibility_count[cursor] <= 1)) {
+        cursor++;
+    }
+
+    state.scan_cursor = cursor;
+
+    return cursor < cell_count ? cursor : -1;
+}
+
+/**
+ * Undo the newest decision and forbid the tile it tried, popping further if that empties the cell.
+ *
+ * @param {WFCState} state
+ * @param {Uint32Array} decision scratch, three entries
+ * @returns {boolean} false when the decision stack is empty — the instance is unsatisfiable
+ * @private
+ */
+function backtrack(state, decision) {
+    while (state.decision_pop(decision)) {
+        const cell = decision[0];
+        const trail_mark = decision[1];
+        const tile = decision[2];
+
+        wfc_state_undo_to(state, trail_mark);
+
+        wfc_state_ban_bits(state, cell, tile >> 5, (1 << (tile & 31)) >>> 0);
+
+        if (state.contradiction) {
+            continue;
+        }
+
+        wfc_state_flush_dirty(state);
+
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Drive the solve until it finishes, proves the instance unsatisfiable, or runs out of budget.
+ *
+ * Returning {@link WFCStatus.RUNNING} means only that the budget ran out; call again to continue,
+ * including part-way through a propagation wave. That makes the solver drivable from a task graph
+ * or a frame loop without this module knowing about either.
+ *
+ * An operation is one edge relaxation or one collapse, so the budget tracks work rather than
+ * wall-clock.
+ *
+ * @param {WFCState} state
+ * @param {number} [max_operations] relaxations and collapses this call may perform
+ * @param {number} [max_backtracks] cumulative across calls, not per call; defaults to one per
+ *        cell. Exceeding it returns {@link WFCStatus.EXHAUSTED}, whose conventional answer is to
+ *        restart with a different seed.
+ * @returns {WFCStatus}
+ */
+export function wfc_solve(state, max_operations = Infinity, max_backtracks = state.cell_count) {
+    assert.isInstanceOf(state, WFCState, 'state');
+    assert.isNumber(max_operations, 'max_operations');
+    assert.isNumber(max_backtracks, 'max_backtracks');
+    assert.greaterThanOrEqual(max_operations, 0, 'max_operations >= 0');
+    assert.greaterThanOrEqual(max_backtracks, 0, 'max_backtracks >= 0');
+
+    const decision = new Uint32Array(3);
+
+    let budget = max_operations;
+
+    while (true) {
+        budget -= wfc_state_propagate(state, budget);
+
+        if (state.contradiction) {
+            if (!backtrack(state, decision)) {
+                return WFCStatus.UNSATISFIABLE;
+            }
+
+            state.backtrack_count++;
+
+            if (state.backtrack_count > max_backtracks) {
+                return WFCStatus.EXHAUSTED;
+            }
+
+            continue;
+        }
+
+        if (state.queue_count > 0) {
+            // the budget ran out mid-wave; the queue carries the rest
+            return WFCStatus.RUNNING;
+        }
+
+        wfc_state_flush_dirty(state);
+
+        if (state.undecided_eligible === 0) {
+            return WFCStatus.SOLVED;
+        }
+
+        if (budget <= 0) {
+            return WFCStatus.RUNNING;
+        }
+
+        const cell = select_cell(state);
+
+        if (cell === -1) {
+            // undecided_eligible said there was work left and the selection queue disagreed. A
+            // real throw rather than an assert.* (consumers strip those) and rather than reporting
+            // SOLVED, which would hand back a grid with holes in it and no way to tell.
+            throw new Error(
+                `no cell to collapse with ${state.undecided_eligible} eligible cells still undecided`
+            );
+        }
+
+        const trail_mark = state.trail_length;
+        const tile = wfc_state_collapse(state, cell);
+
+        state.decision_push(cell, trail_mark, tile);
+
+        budget--;
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Constrain what may face the outside of the lattice.
+ *
+ * A cell on a face has no neighbour that way, so by default anything may sit there. Use this for a
+ * closed border, a floor, or a wall of a particular tile.
+ *
+ * `masks[d * words_per_cell + w]` is the set of tiles allowed in a cell whose `d` side faces
+ * outward. A wrapping axis has no outward-facing cells, so its entries are ignored.
+ *
+ * Apply before the first {@link wfc_solve} call: it narrows domains like any other restriction, so
+ * a backtrack that rewound past it would restore the tiles.
+ *
+ * @param {WFCState} state
+ * @param {Uint32Array|number[]} masks `direction_count × words_per_cell` words
+ * @returns {boolean} false when the boundary emptied some cell
+ */
+export function wfc_state_apply_boundary(state: WFCState, masks: Uint32Array | number[]): boolean;
+//# sourceMappingURL=wfc_state_apply_boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_state_apply_boundary.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_state_apply_boundary.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,iEAHW,WAAW,GAAC,MAAM,EAAE,GAClB,OAAO,CA2CnB"}

package/src/core/wfc/wfc_state_apply_boundary.js

@@ -0,0 +1,61 @@
+import { assert } from "../assert.js";
+import { wfc_state_ban_bits } from "./wfc_state_ban_bits.js";
+
+/**
+ * Constrain what may face the outside of the lattice.
+ *
+ * A cell on a face has no neighbour that way, so by default anything may sit there. Use this for a
+ * closed border, a floor, or a wall of a particular tile.
+ *
+ * `masks[d * words_per_cell + w]` is the set of tiles allowed in a cell whose `d` side faces
+ * outward. A wrapping axis has no outward-facing cells, so its entries are ignored.
+ *
+ * Apply before the first {@link wfc_solve} call: it narrows domains like any other restriction, so
+ * a backtrack that rewound past it would restore the tiles.
+ *
+ * @param {WFCState} state
+ * @param {Uint32Array|number[]} masks `direction_count × words_per_cell` words
+ * @returns {boolean} false when the boundary emptied some cell
+ */
+export function wfc_state_apply_boundary(state, masks) {
+    assert.defined(state, 'state');
+    assert.isArrayLike(masks, 'masks');
+
+    const { cell_count, words_per_cell, direction_count, wave } = state;
+    const edge_flags = state.lattice.edge_flags;
+    const wrap = state.lattice.wrap;
+
+    assert.greaterThanOrEqual(
+        masks.length,
+        direction_count * words_per_cell,
+        'masks.length >= direction_count * words_per_cell'
+    );
+
+    for (let cell = 0; cell < cell_count; cell++) {
+        const flags = edge_flags[cell];
+
+        if (flags === 0) {
+            continue;
+        }
+
+        const base = cell * words_per_cell;
+
+        for (let d = 0; d < direction_count; d++) {
+            if (((flags >> d) & 1) === 0 || wrap[d >> 1] === 1) {
+                continue;
+            }
+
+            const mask_base = d * words_per_cell;
+
+            for (let w = 0; w < words_per_cell; w++) {
+                const removable = wave[base + w] & ~masks[mask_base + w];
+
+                if (removable !== 0) {
+                    wfc_state_ban_bits(state, cell, w, removable);
+                }
+            }
+        }
+    }
+
+    return !state.contradiction;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Pin a cell to one tile — the singleton case of {@link wfc_state_restrict}, and the usual way a
+ * caller expresses "this part of the grid is already decided".
+ *
+ * @param {WFCState} state
+ * @param {number} cell
+ * @param {number} tile
+ * @returns {boolean} false when the tile was already ruled out here, leaving the cell empty
+ */
+export function wfc_state_assign(state: WFCState, cell: number, tile: number): boolean;
+//# sourceMappingURL=wfc_state_assign.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_state_assign.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_state_assign.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wDAJW,MAAM,QACN,MAAM,GACJ,OAAO,CAyBnB"}

package/src/core/wfc/wfc_state_assign.js

@@ -0,0 +1,36 @@
+import { assert } from "../assert.js";
+import { wfc_state_ban_bits } from "./wfc_state_ban_bits.js";
+
+/**
+ * Pin a cell to one tile — the singleton case of {@link wfc_state_restrict}, and the usual way a
+ * caller expresses "this part of the grid is already decided".
+ *
+ * @param {WFCState} state
+ * @param {number} cell
+ * @param {number} tile
+ * @returns {boolean} false when the tile was already ruled out here, leaving the cell empty
+ */
+export function wfc_state_assign(state, cell, tile) {
+    assert.defined(state, 'state');
+    assert.isNonNegativeInteger(cell, 'cell');
+    assert.isNonNegativeInteger(tile, 'tile');
+    assert.lessThan(cell, state.cell_count, 'cell < cell_count');
+    assert.lessThan(tile, state.tile_count, 'tile < tile_count');
+
+    const { wave, words_per_cell } = state;
+    const base = cell * words_per_cell;
+    const tile_word = tile >> 5;
+    const tile_bit = (1 << (tile & 31)) >>> 0;
+
+    for (let w = 0; w < words_per_cell; w++) {
+        const removable = w === tile_word
+            ? (wave[base + w] & ~tile_bit)
+            : wave[base + w];
+
+        if (removable !== 0) {
+            wfc_state_ban_bits(state, cell, w, removable);
+        }
+    }
+
+    return !state.contradiction;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Remove a set of tiles from one word of one cell's domain.
+ *
+ * Every domain shrink goes through here: it moves the wave, the undo trail, the possibility count,
+ * both weight accumulators and the cell's queue membership together, and applying a shrink any
+ * other way desynchronises them.
+ *
+ * An emptied domain is reported on `state.contradiction` rather than returned, so the propagator
+ * checks it once per relaxation instead of once per call.
+ *
+ * @param {WFCState} state
+ * @param {number} cell
+ * @param {number} word_index which word of the cell's domain, in `[0, words_per_cell)`
+ * @param {number} bits tiles to remove; bits already clear are ignored
+ */
+export function wfc_state_ban_bits(state: WFCState, cell: number, word_index: number, bits: number): void;
+//# sourceMappingURL=wfc_state_ban_bits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wfc_state_ban_bits.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/wfc_state_ban_bits.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,0DAJW,MAAM,cACN,MAAM,QACN,MAAM,QAiEhB"}