dicechess.engine

Core domain models for the Dice Chess Engine.

This package contains the fundamental data structures used to represent the chess board, pieces, moves, and game state. It heavily relies on Scala 3 Opaque Types and bitwise memory packing to guarantee zero-allocation performance during hot-path evaluations like Expectimax search.

JVM-language-agnostic facade over the engine, for callers not written in Scala.

This is the JVM row's counterpart to the JS row's EngineFacade: the surface a Java or Kotlin consumer binds to instead of the Scala API, which leans on Either returns, extension methods, and opaque types that do not survive the language boundary intact. Everything outside this package is internal to such a consumer, whatever its Scala visibility says.

Key Components

• dicechess.engine.jvmapi.JvmApi: DFEN parsing, active color, and legal-turn enumeration, exposed through java.util types and primitives only.
• JvmApi.Turn: one legal turn as its UCI micro-moves plus the position they lead to.

The facade's Java-callability is pinned by a Java-source test (jvm/src/test/java/) — signatures can stop being reachable from Java without any Scala-side compiler error.

Move generation for the Dice Chess Engine.

This package implements a fully bitboard-based pseudo-legal move generator. Each subsystem is responsible for a specific piece class, and MoveGenerator orchestrates them into a unified interface.

Architecture

Object	Responsibility
PawnGeneration	Parallel push/capture generation via bitboard shifts
LeaperAttacks	Precomputed attack tables for Knights and Kings
MagicBitboards	O(1) sliding-piece attacks via magic-number hashing
MoveGenerator	Unified entry point; serialises bitboards into Move lists

Move representation

All generated moves are 16-bit dicechess.engine.domain.Move values encoding origin square, destination square, and a 4-bit flag field (quiet, capture, castling, en passant, promotion).

Pseudo-legal generation

The generator produces pseudo-legal moves — moves that obey piece movement rules and match the available dice pool. Dice Chess has no notion of check: the game ends by direct King capture, so no check-based legality filtering exists anywhere in the engine. The only further constraint is the Maximum Micro-moves Rule, applied by LegalMovesFilter.

Search and evaluation layer for the Dice Chess Engine.

This package implements the bot strategies, turn-path enumeration, and static evaluation function that power the engine's decision-making. It sits above the move-generation layer and operates on complete dicechess.engine.domain.GameStates.

Architecture

Component	Responsibility
TurnGenerator	Enumerates all legal full-turn paths (1–3 micro-moves) via DFS
dicechess.engine.movegen.LegalMovesFilter	Filters first moves under the Maximum Micro-moves Rule (in movegen)
SearchAlgorithm	Trait contract for bot strategies; returns a ScoredSequence
GreedySearch	Picks the turn path with the highest material score; prefers short wins
RandomSearch	Selects a uniformly random legal path; useful as a baseline / test bot
Evaluator	Pure material-balance evaluator used by all current bot strategies
SearchScoring	Shared scoring helper: scores a path and handles king-capture termination

Turn Model

A turn in Dice Chess consists of:

1. A dice roll that yields 1–3 die values.
2. A sequence of 1–3 micro-moves — each micro-move must be made by the piece type matching the consumed die.
3. The active color is not toggled between micro-moves; only after the full turn completes.

The Maximum Micro-moves Rule requires a player to choose an opening move that is part of the longest achievable micro-move sequence. Any sequence that ends with a King capture is always legal regardless of length.

Scoring

SearchScoring.scorePath assigns SearchScoring.TerminalWinScore (Int.MaxValue) to any path that captures the opponent's King, and falls back to Evaluator.evaluateMaterial for non-terminal paths.