Engine Integration

The web client delegates game rules, move validations, and FEN parsing to the @rabestro/dicechess-engine package, which is compiled to ScalaJS and published as @rabestro/dicechess-engine on GitHub Packages.

The module src/lib/engine.ts serves as the thin adapter between the database analytical models and the engine’s public APIs.

---

1. FEN Format vs. DFEN (Dice Chess FEN)

• Database / Analytical Model: Stores positions as standard 4-field FENs (piece placement, active color, castling rights, en passant square) and rolled dice pools as simple digit strings (e.g. "236" representing Knight, Bishop, King).
• Dice Chess Engine: Speaks DFEN, which is a 7-field structure extending the standard 6-field chess FEN with an additional dice pool field composed of lowercase piece letters (e.g., p for pawn, n for knight, b for bishop, r for rook, q for queen, k for king).

Conversion Logic

toDfen(fen, dicePool) converts a standard database FEN and digit-based dice pool into a valid engine-compliant DFEN:

// Example: FEN "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -" and dice pool "124"
// Result:  "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1 pnr"
const dfen = toDfen(dbFen, '124');

---

2. Validation & Legality Checks

Dice Chess rules impose constraints like the Maximum Micro-moves Rule (where players are forced to make up to 3 moves if possible). Rather than duplicating this logic, the frontend utilizes the engine’s getLegalUciMoves function:

export function hasAnyLegalMove(fen: string, dicePool: string): boolean {
  return DiceChess.getLegalUciMoves(toDfen(fen, dicePool)).length > 0;
}

If hasAnyLegalMove returns false, the active player is forced to pass, and the turn automatically transitions.

---

3. Applying Moves & Consuming Dice

To animate and validate moves during interactive game playback:

1. applyMove(dfen, from, to, promotion) is called.
2. It fetches legal UCI moves from the engine using the current DFEN.
3. Consumes the dice corresponding to the piece moved (e.g. moving a Knight consumes n).
4. Castling Rule: Castling (King moving two files) consumes both the King (k) and the Rook (r) dice.
5. Re-attaches the remaining dice pool (if any) and returns the updated board position.