A Java chess engine built around persistent graph exploration, exact endgame solving, and interactive analysis.
Unlike a conventional engine centered on a single minimax search tree, this project explores chess positions through a shared canonical PositionGraph. Multiple persistent line walkers can encounter the same position from different move orders and reuse the same graph node, allowing transpositions, visit counts, solved-state propagation, and analysis history to accumulate over time.
- Persistent canonical position graph with transposition reuse rather than independent per-line trees.
- Dovetail search using a countable diagonal schedule of persistent walkers.
- Hybrid search combining the same walker schedule with fair node/edge coverage.
- Strength-aware stochastic exploration that preserves novelty and anti-repeat behavior while biasing tied choices toward stronger moves.
- Full legal chess rules, including castling, en passant, promotion, check, checkmate, stalemate, repetition, and move-count draw rules.
- Interactive analysis UI with candidate lines, board previews, continuation navigation, keyboard navigation, board flipping, and light/dark modes.
- Optional Stockfish 18 reference analysis through a dependency-free UCI client.
- Position Setup mode with free piece placement, side-to-move controls, material summary, live FEN output, undo/redo navigation, and arbitrary-position analysis.
- Exact 3- and 4-piece endgame solving backed by generated tablebases.
- 30 canonical four-piece material families validated by the v1.0 release regression suite.
- Endgame Curriculum with exact WDL/DTM feedback, exact defense, hints, solution review, progress tracking, and saved Ordered/Shuffle puzzle sequences.
- Formal v1.0 regression gate covering core chess rules, search, tablebases, endgame control, Stockfish integration, and packed-runtime memory behavior.
Dovetail is the project's original exploration model. Persistent walkers are scheduled diagonally:
A1
B1, A2
C1, B2, A3
D1, C2, B3, A4
...
Each walker can continue for up to 10,000 half-moves. Walkers write into one shared PositionGraph, so transpositions discovered by different walks collapse onto the same canonical node.
Move selection prioritizes exploration first:
- lower walker-specific edge usage,
- lower total edge traversals,
- lower target-node visits,
- a strong penalty for revisiting a position already on the current walk.
Evaluation is used only among moves tied at the best exploration penalty. Four repeating walker profiles provide different amounts of chess bias: EXPLORER, GUIDED, STRONG, and PRINCIPAL. Every fourth walker therefore remains a pure explorer.
Hybrid preserves the exact same Dovetail walker schedule and adds a second lane for fair persistent node/edge coverage.
The coverage queue determines which node receives work. Evaluation only selects the strongest currently unvisited move within that already-selected node. This separation prevents attractive regions of the graph from turning the global scheduler into a best-first queue and starving the rest of the explored graph.
Stockfish is intentionally separate from the native graph search. The application uses it as an optional UCI reference engine for comparison, calibration, MultiPV candidate analysis, and continuation inspection.
The native Dovetail/Hybrid engine remains its own search system; Stockfish does not drive the persistent graph exploration.
Setup mode can construct arbitrary positions directly on the board. The interface tracks material, validates the position, generates live FEN output, and can send the resulting position directly into analysis.
Setup-created positions intentionally begin without castling rights unless those rights are supplied through a loaded FEN.
The endgame subsystem combines generated exact tablebases with an interactive curriculum.
v1.0 includes exact 3-piece support and a completed 30-family canonical four-piece catalog. The solver routes supported positions to exact WDL/DTM data and the curriculum turns those results into practice positions.
The KP-KP tablebase includes en-passant-aware state handling. Its v1.0 packed runtime representation stores WDL and DTM in one byte per indexed state, reducing the core state array from roughly 96.3 MiB to 32.11 MiB. The release regression suite verifies the packed runtime in an isolated JVM limited to -Xmx128m.
Five-piece and larger tablebases are outside the v1.0 scope.
- Click Endgame in the header, choose a family, and wait for the puzzle to load. Play the indicated side by clicking a piece and its destination, or dragging it there. The trainer accepts exact-best moves and plays the opponent's exact reply automatically; other legal moves are returned with "Not the best move" feedback.
- Click Hint to display an exact move for the position currently shown. Hint leaves the board in place and marks the attempt as assisted.
- Click Give Up to end the attempt and reveal its exact continuation in SOLUTION / MOVE REVIEW. Wait for the solution to finish loading.
- Click a solution row, such as Qe7, to show the position after that move. Use Previous Move / Next Move or the Left / Right arrow keys to step through the line. Click START or press Up for the starting position; Down jumps to the final position. The board and turn indicator follow the selected row.
- To play the puzzle again after Give Up, click Reset in the application header. This clears the current attempt and solution, restores that puzzle's original position, and enables play once loading finishes.
Before giving up, select a row in PLAYED LINE / MOVE REVIEW or use Previous Move to review your played moves. Earlier positions are read-only; return to the latest played move to continue an unfinished attempt. Solution review is read-only throughout, and its moves do not become played moves. Assisted or surrendered attempts do not earn mastery.
Next in Training Actions advances to the next puzzle. Saved puzzles, their order, and the current attempt survive closing and reopening the application. The family reset and Reset All Endgame Progress clear attempts and mastery after confirmation, then replay the saved sequence from its beginning. They preserve the puzzles and their order; only an explicit Ordered / Shuffle change reorders the collection.
See trainer verification and the Qe7 repair report for repair evidence, regression coverage, and Windows EXE verification.
Download Chess-Engine-v1.0.4-windows.zip,
extract the complete ZIP to a writable folder, and double-click
Chess Engine.exe inside the extracted Chess Engine folder.
The Windows ZIP contains Java 26 and all 36 required tablebases (6 three-piece
and 30 four-piece assets). No separate Java or Maven installation is needed.
Keep app/, runtime/, and tablebases/ beside the EXE. Stockfish is optional;
place its executable in the adjacent stockfish/ folder.
v1.0.4 is the latest stable release.
- Repaired manual endgame movement, including continued play after the automatic reply.
- Hint shows an exact move; Give Up reveals a selectable solution and handles overlapping help requests.
- Synchronized the board, played history, solution selection, and turn indicator during review.
- Preserved saved puzzle order across resets and restarts, with the current attempt restored on reopening.
- JDK 26 — the v1.0 release candidate was built and verified on OpenJDK 26.
- Apache Maven 3.9+ for the command-line build.
- Stockfish 18 is optional and is not stored in this Git repository.
- Generated tablebase binaries are also distributed separately from the source repository because of their size.
From the repository root:
mvn clean packageMaven creates target/chess-engine-1.0.4.jar, as configured in pom.xml. Run it with:
java -jar target/chess-engine-1.0.4.jarThe application can also be launched directly from IntelliJ with:
main.java.chess.Main
On Windows x64, with Maven and JDK 26, use the verified original tablebase archive listed in Runtime Assets:
powershell -NoProfile -ExecutionPolicy Bypass -File .\package-windows.ps1 -JdkHome $env:JAVA_HOME -TablebaseArchive .\Chess-Engine-v1.0.0.zipThis runs a clean build, derives runtime modules using jdeps, bundles Java with
jlink, and creates the icon-branded launcher using jpackage --type app-image.
The packaging script reads version 1.0.4 from pom.xml and produces:
| Output | Path |
|---|---|
| Windows launcher | target/windows-v1.0.4/Chess Engine/Chess Engine.exe |
| Internal application JAR | target/windows-v1.0.4/Chess Engine/app/chess-engine-1.0.4.jar |
| Complete Windows ZIP | target/Chess-Engine-v1.0.4-windows.zip |
Launch the EXE from the complete app image.
The UCI client looks for Stockfish automatically in several common project/user locations. For an explicit path, use either the JVM property:
java -Dstockfish.path="/full/path/to/stockfish" -jar target/chess-engine-1.0.4.jaror the environment variable:
STOCKFISH_PATH
On PowerShell, for example:
$env:STOCKFISH_PATH="C:\path\to\stockfish-windows-x86-64-avx2.exe"
java -jar target\chess-engine-1.0.4.jarSee docs/RUNTIME-ASSETS.md for tablebase and Stockfish details.
The results below were recorded for the original v1.0 release and are preserved as historical verification.
The v1.0 release candidate has a dedicated automated regression entry point:
main.java.chess.release.V1ReleaseRegressionMain
M87 runs each subsystem gate in a fresh JVM so caches and state cannot leak between tests.
| Gate | Result | Recorded time |
|---|---|---|
| Core chess / graph / FEN | PASS | 5.394 s |
| M76 Dovetail frozen search | PASS | 11.625 s |
| M77 Hybrid frozen search | PASS | 94.981 s |
| Three-piece packaged tablebases | PASS | 0.597 s |
| 30-family four-piece catalog | PASS | 198.667 s |
| Endgame move controller / practice strength | PASS | 14.980 s |
| Stockfish process / forced-mate smoke | PASS | 2.241 s |
| M86 KPKP packed runtime / 128-MiB heap | PASS | 19.200 s |
8 / 8 automated gates passed in 347.700 seconds, followed by the manual GUI smoke check used to sign off the v1.0 interface.
For more detail, see docs/RELEASE-VERIFICATION.md.
src/main/java/chess/
├── analysis/ analysis models and presentation support
├── endgame/ exact tablebases, builders, codecs, services, curriculum
├── engine/ engine coordination and endgame move control
├── evaluation/ native position evaluation
├── gui/ Swing application and interactive analysis UI
├── model/ board, pieces, moves, positions, FEN/state models
├── release/ v1.0 release regression gate
├── rules/ legal move generation, attacks, game-state evaluation
├── search/ PositionGraph, Dovetail walkers, Hybrid scheduler
├── stockfish/ dependency-free UCI integration and formatting
└── tests/ verification and regression harnesses
The repository intentionally retains many tablebase builders, validation mains, and diagnostic harnesses. They form part of the reproducible development history for the exact endgame subsystem and release gates.
A deeper technical description of the graph model, search lanes, and endgame stack is available in docs/ARCHITECTURE.md.
This project is primarily an exploration of search architecture, graph persistence, exact endgame computation, and interactive analysis. It is not presented as a replacement for state-of-the-art alpha-beta engines in raw playing strength. Stockfish is included as an external reference precisely so the native system can be compared against a mature conventional engine.
Stockfish is a separate optional executable and is not included in this source repository. Stockfish is distributed under the GNU General Public License version 3. See THIRD_PARTY_NOTICES.md.
Shai Beekman
- GitHub: ShaiBeekman
- Portfolio: shaibeekman.github.io