Chess Modern
Chess
A polished, native cross-platform chess game built with Flutter for the UI
and Rust for the engine + AI, connected through
flutter_rust_bridge.
- Stack: Flutter 3.27+ + Rust 1.77+ + flutter_rust_bridge 2.12.
- AI: hybrid — a custom Rust minimax engine for difficulty 1–3, and Stockfish 17 (UCI subprocess) for 4–10 on macOS, Windows, Linux desktop, and Android. iOS uses the custom Rust engine for every level (the iOS sandbox forbids spawning external binaries).
- Modes: human vs human (local), human vs AI.
- Platforms: macOS, Windows, Linux, iOS, Android.
Repository layout
| Path | Contents |
|---|---|
crates/chess_core/ |
Platform-agnostic Rust core: api, engine, ai, clock, pgn, session, commands. |
crates/chess_core/src/platform.rs |
Trait seams (AppDirs, EventSink, StockfishSpawner) every embedding implements. |
crates/chess_bridge/ |
flutter_rust_bridge crate. Exposes 15 commands + a single BackendEvent stream. |
crates/chess_bridge/binaries/ |
Stockfish desktop sidecars (gitignored). Populated by scripts/fetch-stockfish.sh. |
flutter/ |
Flutter app (lib/main.dart, controllers, board widget, modals, audio synth). |
flutter/lib/src/rust/ |
Auto-generated Dart bindings (do not hand-edit; regenerated by flutter_rust_bridge_codegen generate). |
flutter_rust_bridge.yaml |
Codegen config. |
scripts/fetch-stockfish.sh |
Download Stockfish 17 desktop binaries into crates/chess_bridge/binaries/. |
scripts/build-stockfish-android.sh |
Cross-compile Stockfish 17 for arm64-v8a / armv7 / x86_64 with the Android NDK. |
Develop
Prerequisites
- Rust toolchain (
rustup, stable channel). - Flutter SDK 3.27+ on your
PATH. - iOS builds: macOS host + Xcode 15+.
- Android builds: Android SDK + NDK r26+ (
ANDROID_NDK_ROOT).
Day-to-day
# Regenerate Dart bindings whenever you edit crates/chess_bridge/src/api.rs.
flutter_rust_bridge_codegen generate
# Run the headless workspace tests (engine, AI, session, trait seams).
cargo test --workspace
# Static analysis + Dart unit tests.
cd flutter
flutter pub get
flutter analyze
flutter test
Run the app
cd flutter
flutter run -d macos # or windows / linux / <ios sim> / <android emulator>
Flutter automatically invokes the Xcode build phase (flutter/macos/Runner/Scripts/build_rust.sh)
which compiles crates/chess_bridge and embeds it into the .app bundle.
AI / Stockfish
| Platform | Levels 1-3 | Levels 4-10 |
|---|---|---|
| macOS desktop | Custom Rust engine | Stockfish 17 sidecar (scripts/fetch-stockfish.sh) |
| Windows desktop | Custom Rust engine | Stockfish 17 sidecar |
| Linux desktop | Custom Rust engine | Stockfish 17 sidecar |
| Android | Custom Rust engine | Stockfish 17 (NDK source-built; scripts/build-stockfish-android.sh) |
| iOS | Custom Rust engine | Custom Rust engine (sandbox forbids spawning child processes) |
When Stockfish is unavailable for any reason — missing binary, failed spawn,
running on iOS — chess_core::ai::stockfish::choose_move transparently falls
back to the strongest custom-engine tier (fallback_custom_level in
crates/chess_core/src/ai/difficulty.rs). The user sees a slightly weaker
opponent at high levels, never an error.
Fetching desktop Stockfish binaries
bash scripts/fetch-stockfish.sh
This downloads official Stockfish 17 builds into crates/chess_bridge/binaries/
(gitignored). The macOS Xcode build phase picks them up automatically.
Building the Android Stockfish binaries
export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/26.1.10909125
bash scripts/build-stockfish-android.sh
This drops three binaries into flutter/assets/stockfish/<abi>/stockfish,
which Flutter bundles as part of flutter build apk. If you skip this step,
the Android build still works; AI levels 4-10 just use the custom Rust engine.
Backend ↔ frontend contract
15 commands + a single BackendEvent broadcast stream. They live in
crates/chess_core/src/api.rs and are exposed to Dart as:
bridgeInit(dataDir)once at startup.- 15
Future<...>commands (newGame,makeMove, …,setSettings). subscribeEvents()returningStream<BackendEvent>carryingBackendEvent.moveMade,BackendEvent.aiProgress,BackendEvent.gameOver,BackendEvent.clockTick.
Tests
cargo test --workspace # Rust unit + integration tests
flutter test # Dart tests
CI runs both jobs plus a Linux desktop smoke build on every push and pull
request. See .github/workflows/ci.yml.
