@fortemate/dicechess-engine-wasm 0.12.3 → 0.14.0

package/README.md

@@ -27,7 +27,7 @@ so importing both in the same application loads the shared half once.
 
 | Import | What it gives you | What it loads |
 | :--- | :--- | :--- |
-| `@fortemate/dicechess-engine` | everything: `DiceChess`, `EngineFacade`, the bots, `getBestMove`, equity, doubling and draw decisions | 1,308,539 B (191,262 B gzipped) |
+| `@fortemate/dicechess-engine` | everything: `DiceChess`, `EngineFacade`, the legal turn tree, the bots, `getBestMove`, equity, doubling and draw decisions | 1,308,539 B (191,262 B gzipped) |
 | `@fortemate/dicechess-engine/rules` | the rules only: `getLegalUciMoves`, `generateMoves`, `applyMove`, `endTurn`, `perft`, `getPieceFromDice`, `canonicalKey` | 891,712 B (138,394 B gzipped) |
 
 Use `/rules` wherever the application validates, applies and renders moves but never asks the engine
@@ -68,44 +68,61 @@ const legalMoves = DiceChess.getLegalUciMoves(dfen);
 console.log("Legal moves in this turn:", legalMoves);
 // e.g. ["e2e3", "e2e4", "b1c3", "b1a3", ...]
 
-// 2. Apply a micro-move. Note that applyMove preserves the active color
-// (White) since a Dice Chess turn may consist of multiple micro-moves.
+// 2. Get every legal turn as a prefix tree of UCI micro-moves. A node without children is a
+// complete turn. getLegalUciMoves judges each position in isolation, so a client that follows
+// a turn one action at a time walks this tree instead of calling getLegalUciMoves again.
+const turns = DiceChess.getLegalTurnTree(dfen);
+console.log("Continuations of e2e4:", Object.keys(turns["e2e4"]));
+// e.g. ["b1a3", "b1c3", "g1e2", "g1f3", "g1h3"]
+
+// The dice a legal turn can still spend: pass the rolled DFEN and the moves played since, not the
+// DFEN after them, because the turn is judged as a whole. A client can dim every other die.
+console.log("Playable after e2e4:", DiceChess.getPlayableDice(dfen, ["e2e4"]));
+// "N"
+
+// 3. Apply a micro-move. applyMove preserves the active color (White), since a Dice Chess turn
+// may consist of multiple micro-moves, and keeps the dice the move did not spend ("N" here).
 // Arguments: (dfen, fromSquare, toSquare, optionalPromotionPiece)
 const nextDfen = DiceChess.applyMove(dfen, "e2", "e4");
 console.log("DFEN after micro-move:", nextDfen);
 
-// 3. Explicitly end the turn when the player has exhausted their dice.
-// This toggles the active color to Black, increments the move counter,
-// and clears any stale en-passant targets from the previous turn.
-const finalDfen = DiceChess.endTurn(nextDfen);
+// Spend the knight die too: the turn ends at a leaf of the tree, here after e2e4 then g1f3.
+const turnDfen = DiceChess.applyMove(nextDfen, "g1", "f3");
+
+// 4. Explicitly end the turn when the player has exhausted their dice.
+// This toggles the active color to Black, clears the dice pool (the full-move number advances
+// only after Black's turn), and clears any stale en-passant targets from the previous turn.
+const finalDfen = DiceChess.endTurn(turnDfen);
 console.log("DFEN after ending turn:", finalDfen);
 
-// 4. Discover available bots (search algorithms)
+// 5. Discover available bots (search algorithms)
 const bots = DiceChess.getAvailableBots();
 console.log("Available bots:", bots);
 // e.g. [ { id: 'random', name: 'Random', description: '...', difficulty: 1, isExperimental: false }, ... ]
 
-// 5. Discover the built-in time-management policies.
+// 6. Discover the built-in time-management policies.
 const timePolicies = DiceChess.getAvailableTimePolicies();
 console.log("Available time policies:", timePolicies);
 // [ "empirical-v1", "legacy-linear-v1" ]
 
-// 6. Compute the best sequence of micro-moves using the greedy bot search
+// 7. Compute the best sequence of micro-moves using the greedy bot search.
+// The bot needs Black's roll: append the dice (lowercase for Black), here a Pawn and a Knight.
 // Arguments: (dfen, optionalOptions)
-const botResult = DiceChess.getBestMove(finalDfen, { algorithm: "greedy" });
+const rolledDfen = `${finalDfen} pn`;
+const botResult = DiceChess.getBestMove(rolledDfen, { algorithm: "greedy" });
 console.log("Bot moves:", botResult.moves);
-// e.g. [ { from: "g8", to: "f6" } ]
+// e.g. [ { from: "b8", to: "c6" }, { from: "a7", to: "a5" } ]
 
 // Clock-aware searches use empirical-v1 by default. Pass legacy-linear-v1 to
 // reproduce the original allocation for rollback or an A/B comparison.
-const timedResult = DiceChess.getBestMove(finalDfen, {
+const timedResult = DiceChess.getBestMove(rolledDfen, {
   algorithm: "monte-carlo",
   clock: { remainingMs: 180_000, incrementMs: 2_000, moveNumber: 8 },
   timePolicy: "empirical-v1",
 });
 console.log("Effective budget (ms):", timedResult.budgetMs);
 
-// 7. Doubling Cube & Draw Offers (New)
+// 8. Doubling Cube & Draw Offers (New)
 // Check if the bot wants to offer a double before its turn:
 const shouldDouble = DiceChess.shouldBotOfferDouble(finalDfen, 1);
 
@@ -133,7 +150,7 @@ const acceptDraw = DiceChess.shouldBotAcceptDraw(finalDfen);
 
 ## API Reference & Documentation
 
-* **[Interactive User & Developer Guide](https://fortemate.com/dicechess-engine/)**: Complete rules, architectural documentation, and live interactive visual catalogs.
+* **[Interactive User & Developer Guide](https://fortemate.github.io/dicechess-engine/)**: Complete rules, architectural documentation, and live interactive visual catalogs.
 * **[GitHub Repository](https://github.com/fortemate/dicechess-engine)**: Source code, issue tracker, and contribution guidelines.
 
 ---

package/dicechess-engine.d.ts

@@ -13,7 +13,10 @@ export interface EngineFacadeApi {
     getPieceTypeAt(dfen: string, square: string): number | undefined;
 
     /**
-     * Applies a move to the given DFEN and returns the resulting state.
+     * Applies a move to the given DFEN and returns the resulting state, keeping the dice the move
+     * did not spend (castling spends the king and the rook die) and, when the DFEN carries dice,
+     * refusing a move no die allows.
+     * Same as `DiceChess.applyMove`.
      */
     applyMove(dfen: string, from: string, to: string, promotion?: string): string | undefined;
 
@@ -27,6 +30,20 @@ export interface EngineFacadeApi {
 
 export const EngineFacade: EngineFacadeApi;
 
+/**
+ * Every legal turn of a rolled position as a prefix tree of UCI micro-moves, in the shape of
+ * dicechess-play-api's `MoveTree`, children in UCI order:
+ *
+ *     { "e2e3": { "e3e4": {} }, "e2e4": { "e4e5": {} } }
+ *
+ * A node with no children is a complete legal turn, and every complete legal turn is such a leaf:
+ * a turn that captures the king ends there, and every other turn spends the most dice the roll
+ * allows. An empty object means the roll has no legal move.
+ */
+export interface MoveTree {
+    [uci: string]: MoveTree;
+}
+
 export type TimePolicyId = "empirical-v1" | "legacy-linear-v1";
 
 export interface ClockStateOptions {
@@ -63,9 +80,44 @@ export interface DiceChessApi {
 
     /**
      * Returns all legal moves as a flat array of UCI strings (e.g., ["e2e4", "e7e8q"]).
+     * They are the legal first actions of a turn from this position, judged in isolation: asked
+     * again after each micro-move, the answer can admit actions the whole turn does not allow.
+     * Use `getLegalTurnTree` to follow a turn.
      */
     getLegalUciMoves(dfen: string): string[];
 
+    /**
+     * Returns every legal turn of the rolled position as a prefix tree of UCI micro-moves.
+     * Its first level equals `getLegalUciMoves(dfen)`. Deeper levels can be narrower than
+     * `getLegalUciMoves` asked again after each micro-move, so a client that follows a turn one
+     * action at a time walks this tree. Empty for an invalid DFEN, a DFEN without dice, or a roll
+     * with no legal move.
+     */
+    getLegalTurnTree(dfen: string): MoveTree;
+
+    /**
+     * Returns the dice that a legal turn can still spend once `moves` have been played: those that
+     * at least one legal turn beginning with `moves` spends after them. A client can dim the other
+     * dice, which no turn left can use.
+     *
+     * The turn is judged as a whole, so pass the rolled DFEN at the start of the turn, as for
+     * `getLegalTurnTree`, and the UCI micro-moves played since, not the DFEN after them. `moves`
+     * default to none. In the start position with `QRN` this returns `"NR"`: only a knight can
+     * move first, but the rook can follow it.
+     *
+     * The dice come as the DFEN dice field writes them: ascending by face, in the case of the side
+     * to move, and a face repeated as often as the most dice showing it that one legal turn spends.
+     * The result is `""` when no legal turn continues: after a complete turn, a king capture
+     * included, and for a roll with no legal move or a DFEN without dice. It is `undefined` for an
+     * invalid DFEN, when `moves` is not an array of UCI strings, and when it is not the beginning
+     * of a legal turn.
+     *
+     * A client holding the tree needs the call only when the current node has children but no path
+     * below it has as many actions as there are dice left: an empty node means no die is playable,
+     * and a path as long as the dice left means every one of them is.
+     */
+    getPlayableDice(dfen: string, moves?: string[]): string | undefined;
+
     /**
      * Executes perft (performance test) counting leaf nodes at given depth.
      * @param dfen The position in DFEN notation.
@@ -119,6 +171,11 @@ export interface DiceChessApi {
 
     /**
      * Applies a move to the given DFEN and returns the resulting state.
+     * The result keeps the dice the move did not spend; castling spends the king and the rook die.
+     * Pass it back unchanged: while dice remain, appending dice to it yields an eight-field DFEN,
+     * which is rejected. `undefined` when the move is not pseudo-legal, when no die in the pool
+     * allows it, or when an argument is invalid. A position without dice, including the one
+     * returned once the last die is spent, accepts any pseudo-legal move.
      * @param dfen The starting board state in DiceChess FEN notation.
      * @param from The algebraic notation of the starting square.
      * @param to The algebraic notation of the target square.