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.
- Rules: chess move legality, FEN, SAN, UCI, castling, en passant, and
repetition use the permissive
cozy-chessrules adapter. - AI: compiled-in Rust search engine for every difficulty on every platform; no subprocess sidecars or GPL engine dependency.
- Modes: human vs human (local), human vs AI.
- Platforms: macOS, Windows, Linux, iOS, Android.
Repository layout
| Path | Contents |
|---|---|
crates/game_core/ |
Shared game-suite primitives: registry, platform seams, suite store, generic search. |
crates/chess_core/ |
Chess module: api, engine, ai, clock, pgn, suite adapter, session, commands. |
crates/chess_core/src/platform.rs |
Compatibility re-exports for suite platform seams (AppDirs, EventSink). |
crates/chess_bridge/ |
flutter_rust_bridge crate. Exposes 15 commands + a single BackendEvent stream. |
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. |
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.
Game Suite + AI
crates/game_core provides the suite foundation: a static game registry
(Chess today), generic platform seams, a reusable suite session store, and a
deterministic turn-based alpha-beta search layer. crates/chess_core is the
first game module and keeps the existing Flutter chess API as a compatibility
facade. Chess rules are delegated to cozy-chess behind that facade, while
the public snapshot, PGN, SAN, and UCI behavior remain owned by chess_core.
AI difficulty levels 1-5 all use the compiled-in Rust engine. The engine runs inside the app process on macOS, Windows, Linux, iOS, and Android, so mobile targets do not need executable extraction and desktop targets do not need sidecar binaries.
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.
