How shirne/chinese_chess works
Project type and purpose
• This is a cross-platform Flutter application (mobile, web, desktop) implementing a Chinese Chess client with a built-in rule engine and optional external engines via plugins.
• It’s not a server-backed system; it’s a standalone client with pluggable “engine” modules for move generation.
File structure
Top-level directories:
• android / ios / macos / linux / windows / web – platform-specific embedding code
• lib – core Dart code, subdivided into:
– components (UI widgets for board, dialogs, controls)
– widgets (reusable UI elements)
– models (game state, settings, events)
– driver (player/robot/online drivers)
– html (web/Win32 FFI abstractions)
– foundation (app-wide notifiers, globals)
– l10n (localization)
– utils (helper functions)
– main.dart (app entry)
• assets – images, skins, sounds
• plugins – engine_interface and per-platform engine implementations (elephanteye, pikafish, etc.)
• test – unit and widget tests
Review README insights
• Implements full chess rules, FEN/PGN import-export, multiple game modes (player vs player, player vs bot, web bot).
• Windows build integrates the Elephanteye engine; other platforms fall back to the bundled XQLite engine.
• Multi-language support, sound effects (except Linux), platform adaptation via Flutter.
Main components and interactions
a. UI Layer (Flutter widgets & components)
• lib/components & lib/widgets – board rendering, dialogs, input controls
• lib/theme, lib/setting – theming and user preferences
b. Application Logic (Dart)
• lib/models/game_manager – central state machine for game rules (move validation, win detection)
• lib/driver – abstracts move sourcing:
– driver_user (touch/click input)
– driver_robot (built-in XQLite or external engine via engine_interface)
– driver_online (future online play)
• lib/foundation/customer_notifier – state notification to UI
c. Engine Interface Layer
• plugins/engine_interface – defines UCCI protocol, move-request API, logging, abstract model objects
• lib/html/ffi & platform plugin code – FFI wrappers for Windows, web, Linux, macOS to load native engine binaries
d. External Engine Plugins
• plugins/engine_* (engine_darwin, engine_windows, engine_linux, engine_android, engine_web) – platform assets (elephanteye, pikafish) and Dart wrappers
e. Platform Embedding
• android/, ios/, macos/, linux/, windows/, web/ – native scaffolds generated by Flutter, plus any platform overrides (CMakeLists, Podfiles, etc.)
f. Assets & Localization
• assets/skins, assets/sounds – game visuals and audio
• lib/l10n – .arb files and generated Dart localization
Architectural patterns and principles
• Layered architecture: UI → Application Logic → Engine Interface → Native Engine
• Separation of concerns: rendering vs. state vs. engine communication
• Flutter’s reactive pattern: ChangeNotifier & Provider (or similar) to push state to UI
• Plugin-based extensibility: engine_interface defines a contract, platform packages implement it
Final checklist
• Clear labels for every component (include directory/name)