@fortemate/dicechess-engine-wasm 0.13.0 → 0.14.0

package/README.md

@@ -75,6 +75,11 @@ 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)

package/dicechess-engine.d.ts

@@ -95,6 +95,29 @@ export interface DiceChessApi {
      */
     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.