@woosh/meep-engine 2.169.0 → 2.169.1

package/src/engine/intelligence/mcts/MonteCarlo.js

@@ -1,345 +1,345 @@
-import { assert } from "../../../core/assert.js";
-import { mix } from "../../../core/math/mix.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-import { MoveEdge } from "./MoveEdge.js";
-import { StateNode, StateType } from "./StateNode.js";
-
-/**
- * From: A Survey of Monte Carlo Tree Search Methods
- * The value Cp = 1/√2 was shown by Kocsis and Szepesvari [120] to satisfy the Hoeffding ineqality with rewards in the range [0, 1]
- * @type {number}
- */
-const C_ks = 1 / Math.sqrt(2);
-
-/**
- * UCB1-style score for the parent choosing among its children. The exploitation
- * term is read from whichever component the parent's active player cares about —
- * each decision-maker maximizes their own outcome (maxN selection).
- *
- * @param {StateNode} parent
- * @param {StateNode} child
- * @returns {number}
- */
-function computeNodeSelectionScore(parent, child) {
-    const playouts = child.playouts;
-
-    if (playouts === 0) {
-        // child has 0 playouts, this can only happen if it ended up with no moves, avoid division by 0
-        return 0;
-    }
-
-    const player = parent.activePlayer;
-
-    // Exploitation heuristic
-    const Q = mix(child.totalScore[player] / playouts, child.heuristicValue[player], 0.65);
-
-    // Based on UCB1
-    // exploration heuristic
-    const u = Math.sqrt((2 * Math.log(parent.playouts)) / playouts);
-
-    return Q + C_ks * u;
-}
-
-/**
- * @template S
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class MonteCarloTreeSearch {
-
-    /**
-     *
-     * @type {S}
-     */
-    rootState = null;
-
-    /**
-     *
-     * @type {StateNode|null}
-     */
-    root = null;
-
-    /**
-     * Number of distinct players whose payoffs we track. Set in {@link initialize}.
-     * Sizes the per-node `heuristicValue` and `totalScore` buffers.
-     * @type {number}
-     */
-    numPlayers = 0;
-
-    /**
-     *
-     * @type {function(state:S, source:StateNode):MoveEdge[]}
-     */
-    computeValidMoves = null;
-
-    /**
-     *
-     * @type {function(state:S):StateType}
-     */
-    computeTerminalFlag = null;
-
-    /**
-     * Returns the player ID (0-based) who chooses the next move from a given state.
-     * Called when a non-terminal node is expanded. Players don't need to alternate
-     * or follow any fixed pattern — the framework just asks the game.
-     * @type {function(state:S):number}
-     */
-    computeActivePlayer = null;
-
-    /**
-     * Returns the per-player payoff vector for a terminal state.
-     * Indexed by player ID. The game decides the zero-sum/cooperative shape.
-     * @type {function(state:S):Float64Array}
-     */
-    computeOutcome = null;
-
-    /**
-     *
-     * @type {function(S):S}
-     */
-    cloneState = null;
-
-    /**
-     * Heuristic estimate of a non-terminal state's per-player value.
-     * Optional — if `null`, new nodes start with zero-valued heuristic vectors.
-     * @type {null|function(node:StateNode, state:S):Float64Array}
-     */
-    heuristic = null;
-
-    /**
-     * Depth to which plays will be explored
-     * @type {number}
-     */
-    maxExplorationDepth = 1000;
-
-    /**
-     *
-     * @type {Function}
-     */
-    random = seededRandom(0);
-
-    /**
-     * @param {S} rootState
-     * @param {number} numPlayers Total number of players whose payoffs are tracked. Use 1 for solitaire / planning.
-     * @param {function(state:S, source:StateNode):MoveEdge[]} computeValidMoves
-     * @param {function(state:S):StateType} computeTerminalFlag
-     * @param {function(state:S):number} computeActivePlayer
-     * @param {function(state:S):Float64Array} computeOutcome called on terminal states; must return a vector of length `numPlayers`
-     * @param {function(S):S} cloneState
-     * @param {null|function(node:StateNode, state:S):Float64Array} [heuristic] optional per-player estimator for intermediate states
-     */
-    initialize(
-        {
-            rootState,
-            numPlayers,
-            computeValidMoves,
-            computeTerminalFlag,
-            computeActivePlayer,
-            computeOutcome,
-            cloneState,
-            heuristic = null
-        }
-    ) {
-        assert.isInteger(numPlayers, `numPlayers`);
-        assert.greaterThanOrEqual(numPlayers, 1, `numPlayers`);
-
-        assert.isFunction(computeValidMoves, `computeValidMoves`);
-        assert.isFunction(computeTerminalFlag, `computeTerminalFlag`);
-        assert.isFunction(computeActivePlayer, `computeActivePlayer`);
-        assert.isFunction(computeOutcome, `computeOutcome`);
-        assert.isFunction(cloneState, `cloneState`);
-
-        this.numPlayers = numPlayers;
-        this.computeValidMoves = computeValidMoves;
-        this.computeTerminalFlag = computeTerminalFlag;
-        this.computeActivePlayer = computeActivePlayer;
-        this.computeOutcome = computeOutcome;
-        this.cloneState = cloneState;
-        this.heuristic = heuristic;
-
-        this.rootState = rootState;
-
-        this.root = new StateNode();
-        this.root.allocate(numPlayers);
-    }
-
-    /**
-     *
-     * @param {StateNode} node
-     * @param {S} state
-     * @returns {StateNode}
-     */
-    selectRandom(node, state) {
-        let score;
-
-        let i, bestScore, bestMove;
-
-        const random = this.random;
-
-        while (
-            node.isExpanded() &&
-            node.moves.length > 0 &&
-            !node.isTerminal()
-            ) {
-
-            bestScore = Number.NEGATIVE_INFINITY;
-            bestMove = null;
-
-            const moves = node.moves;
-
-            const numMoves = moves.length;
-
-            assert.notEqual(numMoves, 0, 'number of moves is 0, this is invalid state');
-
-            for (i = 0; i < numMoves; i++) {
-
-                const move = moves[i];
-
-                const randomRoll = random();
-
-                if (move.isTargetMaterialized()) {
-
-                    const child = move.target;
-
-                    const s = computeNodeSelectionScore(node, child);
-
-                    assert.notNaN(s, 'computed Node score');
-                    assert.isFinite(s, `computed Node score`);
-
-                    score = s + randomRoll * 1e-5;
-                } else {
-
-                    //use a constant value for unexplored nodes
-                    score = randomRoll * 100;
-
-                }
-
-
-                if (score > bestScore) {
-                    bestScore = score;
-                    bestMove = move;
-                }
-
-            }
-
-            if (!bestMove.isTargetMaterialized()) {
-                //materialize the target state
-                materializeEdgeTarget(state, node, bestMove, this);
-
-            } else {
-                //just follow the edge
-                bestMove.move(state);
-            }
-
-            node = bestMove.target;
-        }
-
-
-        return node;
-    }
-
-    /**
-     * Perform a playout from the root node
-     * @returns {S} final state of the playout
-     */
-    playout() {
-        const computeValidMoves = this.computeValidMoves;
-        const computeActivePlayer = this.computeActivePlayer;
-        const computeOutcome = this.computeOutcome;
-
-        const state = this.cloneState(this.rootState);
-
-        assert.notEqual(state, this.rootState, 'cloneState must produce a new state object, instead it produced the same one');
-
-        let node = this.root;
-
-        while (!node.isTerminal() && node.depth < this.maxExplorationDepth) {
-
-            if (!node.isExpanded()) {
-                node.expand(state, computeValidMoves, computeActivePlayer, computeOutcome);
-            }
-
-            const child = this.selectRandom(node, state);
-
-            if (child === node) {
-                // prevent infinite recursion
-                // can happen e.g. when expand produced no moves (NoMoves terminal)
-                break;
-            }
-
-            node = child;
-        }
-
-        let outcome;
-
-        if (!node.isTerminal() && node.depth >= this.maxExplorationDepth) {
-            // cap the state by depth, propagate heuristic score as payoff stand-in
-            node.type = StateType.DepthCapped;
-            outcome = node.heuristicValue;
-        } else if (node.outcome !== null) {
-            // terminal node with cached payoff
-            outcome = node.outcome;
-        } else {
-            // Defensive: shouldn't reach here under normal control flow, but if
-            // a node became terminal without a cached outcome, fall back to heuristic.
-            outcome = node.heuristicValue;
-        }
-
-        node.backpropagate(outcome);
-
-        return state;
-    }
-}
-
-/**
- * @template S
- * @param {S} state
- * @param {StateNode} source
- * @param {MoveEdge} edge
- * @param {MonteCarloTreeSearch} search
- */
-function materializeEdgeTarget(state, source, edge, search) {
-
-    const child = new StateNode();
-    child.allocate(search.numPlayers);
-    child.parent = source;
-    child.depth = source.depth + 1;
-
-    const computedState = edge.move(state);
-
-    const terminalFlag = search.computeTerminalFlag(computedState);
-
-    assert.enum(terminalFlag, StateType, 'terminalFlag');
-
-    child.type = terminalFlag;
-
-    edge.target = child;
-
-    if (terminalFlag === StateType.Undecided) {
-        // active player will be set when this node is expanded (we don't know
-        // yet whether it has any legal moves)
-        if (search.heuristic !== null) {
-            const h = search.heuristic(child, computedState);
-
-            assert.notNull(h, 'heuristic returned null');
-
-            child.heuristicValue.set(h);
-        }
-    } else {
-        // terminal — game decides per-player payoff, cache and mirror into heuristicValue.
-        // Copy into the node's own buffer so the user is free to reuse one across calls;
-        // outcome and heuristicValue share storage within the node (safe since bubble-up
-        // skips terminals — see StateNode.aggregateHeuristicScore).
-        const out = search.computeOutcome(computedState);
-
-        child.heuristicValue.set(out);
-        child.outcome = child.heuristicValue;
-    }
-
-    // Propagate the new node's value up the tree via maxN backup. This refines
-    // ancestors' heuristicValue with information from the freshly-materialized
-    // leaf — useful guidance for subsequent UCB selections at those ancestors.
-    child.bubbleUpHeuristicScore();
-
-    return computedState;
-}
+import { assert } from "../../../core/assert.js";
+import { mix } from "../../../core/math/mix.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { MoveEdge } from "./MoveEdge.js";
+import { StateNode, StateType } from "./StateNode.js";
+
+/**
+ * From: A Survey of Monte Carlo Tree Search Methods
+ * The value Cp = 1/√2 was shown by Kocsis and Szepesvari [120] to satisfy the Hoeffding ineqality with rewards in the range [0, 1]
+ * @type {number}
+ */
+const C_ks = 1 / Math.sqrt(2);
+
+/**
+ * UCB1-style score for the parent choosing among its children. The exploitation
+ * term is read from whichever component the parent's active player cares about —
+ * each decision-maker maximizes their own outcome (maxN selection).
+ *
+ * @param {StateNode} parent
+ * @param {StateNode} child
+ * @returns {number}
+ */
+function computeNodeSelectionScore(parent, child) {
+    const playouts = child.playouts;
+
+    if (playouts === 0) {
+        // child has 0 playouts, this can only happen if it ended up with no moves, avoid division by 0
+        return 0;
+    }
+
+    const player = parent.activePlayer;
+
+    // Exploitation heuristic
+    const Q = mix(child.totalScore[player] / playouts, child.heuristicValue[player], 0.65);
+
+    // Based on UCB1
+    // exploration heuristic
+    const u = Math.sqrt((2 * Math.log(parent.playouts)) / playouts);
+
+    return Q + C_ks * u;
+}
+
+/**
+ * @template S
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MonteCarloTreeSearch {
+
+    /**
+     *
+     * @type {S}
+     */
+    rootState = null;
+
+    /**
+     *
+     * @type {StateNode|null}
+     */
+    root = null;
+
+    /**
+     * Number of distinct players whose payoffs we track. Set in {@link initialize}.
+     * Sizes the per-node `heuristicValue` and `totalScore` buffers.
+     * @type {number}
+     */
+    numPlayers = 0;
+
+    /**
+     *
+     * @type {(state: S, source: StateNode) => MoveEdge[]}
+     */
+    computeValidMoves = null;
+
+    /**
+     *
+     * @type {(state: S) => StateType}
+     */
+    computeTerminalFlag = null;
+
+    /**
+     * Returns the player ID (0-based) who chooses the next move from a given state.
+     * Called when a non-terminal node is expanded. Players don't need to alternate
+     * or follow any fixed pattern — the framework just asks the game.
+     * @type {(state: S) => number}
+     */
+    computeActivePlayer = null;
+
+    /**
+     * Returns the per-player payoff vector for a terminal state.
+     * Indexed by player ID. The game decides the zero-sum/cooperative shape.
+     * @type {(state: S) => Float64Array}
+     */
+    computeOutcome = null;
+
+    /**
+     *
+     * @type {function(S):S}
+     */
+    cloneState = null;
+
+    /**
+     * Heuristic estimate of a non-terminal state's per-player value.
+     * Optional — if `null`, new nodes start with zero-valued heuristic vectors.
+     * @type {null|(node: StateNode, state: S) => Float64Array}
+     */
+    heuristic = null;
+
+    /**
+     * Depth to which plays will be explored
+     * @type {number}
+     */
+    maxExplorationDepth = 1000;
+
+    /**
+     *
+     * @type {Function}
+     */
+    random = seededRandom(0);
+
+    /**
+     * @param {S} rootState
+     * @param {number} numPlayers Total number of players whose payoffs are tracked. Use 1 for solitaire / planning.
+     * @param {(state: S, source: StateNode) => MoveEdge[]} computeValidMoves
+     * @param {(state: S) => StateType} computeTerminalFlag
+     * @param {(state: S) => number} computeActivePlayer
+     * @param {(state: S) => Float64Array} computeOutcome called on terminal states; must return a vector of length `numPlayers`
+     * @param {function(S):S} cloneState
+     * @param {null|(node: StateNode, state: S) => Float64Array} [heuristic] optional per-player estimator for intermediate states
+     */
+    initialize(
+        {
+            rootState,
+            numPlayers,
+            computeValidMoves,
+            computeTerminalFlag,
+            computeActivePlayer,
+            computeOutcome,
+            cloneState,
+            heuristic = null
+        }
+    ) {
+        assert.isInteger(numPlayers, `numPlayers`);
+        assert.greaterThanOrEqual(numPlayers, 1, `numPlayers`);
+
+        assert.isFunction(computeValidMoves, `computeValidMoves`);
+        assert.isFunction(computeTerminalFlag, `computeTerminalFlag`);
+        assert.isFunction(computeActivePlayer, `computeActivePlayer`);
+        assert.isFunction(computeOutcome, `computeOutcome`);
+        assert.isFunction(cloneState, `cloneState`);
+
+        this.numPlayers = numPlayers;
+        this.computeValidMoves = computeValidMoves;
+        this.computeTerminalFlag = computeTerminalFlag;
+        this.computeActivePlayer = computeActivePlayer;
+        this.computeOutcome = computeOutcome;
+        this.cloneState = cloneState;
+        this.heuristic = heuristic;
+
+        this.rootState = rootState;
+
+        this.root = new StateNode();
+        this.root.allocate(numPlayers);
+    }
+
+    /**
+     *
+     * @param {StateNode} node
+     * @param {S} state
+     * @returns {StateNode}
+     */
+    selectRandom(node, state) {
+        let score;
+
+        let i, bestScore, bestMove;
+
+        const random = this.random;
+
+        while (
+            node.isExpanded() &&
+            node.moves.length > 0 &&
+            !node.isTerminal()
+            ) {
+
+            bestScore = Number.NEGATIVE_INFINITY;
+            bestMove = null;
+
+            const moves = node.moves;
+
+            const numMoves = moves.length;
+
+            assert.notEqual(numMoves, 0, 'number of moves is 0, this is invalid state');
+
+            for (i = 0; i < numMoves; i++) {
+
+                const move = moves[i];
+
+                const randomRoll = random();
+
+                if (move.isTargetMaterialized()) {
+
+                    const child = move.target;
+
+                    const s = computeNodeSelectionScore(node, child);
+
+                    assert.notNaN(s, 'computed Node score');
+                    assert.isFinite(s, `computed Node score`);
+
+                    score = s + randomRoll * 1e-5;
+                } else {
+
+                    //use a constant value for unexplored nodes
+                    score = randomRoll * 100;
+
+                }
+
+
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestMove = move;
+                }
+
+            }
+
+            if (!bestMove.isTargetMaterialized()) {
+                //materialize the target state
+                materializeEdgeTarget(state, node, bestMove, this);
+
+            } else {
+                //just follow the edge
+                bestMove.move(state);
+            }
+
+            node = bestMove.target;
+        }
+
+
+        return node;
+    }
+
+    /**
+     * Perform a playout from the root node
+     * @returns {S} final state of the playout
+     */
+    playout() {
+        const computeValidMoves = this.computeValidMoves;
+        const computeActivePlayer = this.computeActivePlayer;
+        const computeOutcome = this.computeOutcome;
+
+        const state = this.cloneState(this.rootState);
+
+        assert.notEqual(state, this.rootState, 'cloneState must produce a new state object, instead it produced the same one');
+
+        let node = this.root;
+
+        while (!node.isTerminal() && node.depth < this.maxExplorationDepth) {
+
+            if (!node.isExpanded()) {
+                node.expand(state, computeValidMoves, computeActivePlayer, computeOutcome);
+            }
+
+            const child = this.selectRandom(node, state);
+
+            if (child === node) {
+                // prevent infinite recursion
+                // can happen e.g. when expand produced no moves (NoMoves terminal)
+                break;
+            }
+
+            node = child;
+        }
+
+        let outcome;
+
+        if (!node.isTerminal() && node.depth >= this.maxExplorationDepth) {
+            // cap the state by depth, propagate heuristic score as payoff stand-in
+            node.type = StateType.DepthCapped;
+            outcome = node.heuristicValue;
+        } else if (node.outcome !== null) {
+            // terminal node with cached payoff
+            outcome = node.outcome;
+        } else {
+            // Defensive: shouldn't reach here under normal control flow, but if
+            // a node became terminal without a cached outcome, fall back to heuristic.
+            outcome = node.heuristicValue;
+        }
+
+        node.backpropagate(outcome);
+
+        return state;
+    }
+}
+
+/**
+ * @template S
+ * @param {S} state
+ * @param {StateNode} source
+ * @param {MoveEdge} edge
+ * @param {MonteCarloTreeSearch} search
+ */
+function materializeEdgeTarget(state, source, edge, search) {
+
+    const child = new StateNode();
+    child.allocate(search.numPlayers);
+    child.parent = source;
+    child.depth = source.depth + 1;
+
+    const computedState = edge.move(state);
+
+    const terminalFlag = search.computeTerminalFlag(computedState);
+
+    assert.enum(terminalFlag, StateType, 'terminalFlag');
+
+    child.type = terminalFlag;
+
+    edge.target = child;
+
+    if (terminalFlag === StateType.Undecided) {
+        // active player will be set when this node is expanded (we don't know
+        // yet whether it has any legal moves)
+        if (search.heuristic !== null) {
+            const h = search.heuristic(child, computedState);
+
+            assert.notNull(h, 'heuristic returned null');
+
+            child.heuristicValue.set(h);
+        }
+    } else {
+        // terminal — game decides per-player payoff, cache and mirror into heuristicValue.
+        // Copy into the node's own buffer so the user is free to reuse one across calls;
+        // outcome and heuristicValue share storage within the node (safe since bubble-up
+        // skips terminals — see StateNode.aggregateHeuristicScore).
+        const out = search.computeOutcome(computedState);
+
+        child.heuristicValue.set(out);
+        child.outcome = child.heuristicValue;
+    }
+
+    // Propagate the new node's value up the tree via maxN backup. This refines
+    // ancestors' heuristicValue with information from the freshly-materialized
+    // leaf — useful guidance for subsequent UCB selections at those ancestors.
+    child.bubbleUpHeuristicScore();
+
+    return computedState;
+}