Chess-Master is an in-progress, privacy-respecting, offline-first Android chess game built with Flutter. The project is intended to become a complete open-source game with standards-compliant chess rules, local and optional self-hosted friend play, computer opponents, training, daily challenges, and accessible multilingual interfaces.
Open-source chess game
Made by the Sanskar
Development status: all 12 planned source phases are implemented. Phase 12 adds local match history, complete derived statistics, fifteen achievements, integration and release gates, an auditable source SBOM, and Android build evidence. SQLite schema v3 stores durable preferences, games, progress, challenges, and ledger data. No real-money purchase, telemetry, or unverified native executable is bundled. Public distribution still requires the external approvals recorded in the feature status and the continuation manifest for exact evidence.
- No account, login, analytics, advertising identifier, or behavioral tracking.
- Durable settings and game data stay in the application database on the device.
- Android cloud backup is disabled; explicit export/import will be user-controlled.
- Friend matches use an optional temporary WebSocket relay. That relay necessarily processes active room messages but does not permanently store games, names, profiles, or session tokens.
- Offline features must not wait for the multiplayer service during startup.
- Challenge progress, balances, and reward history stay in local SQLite. The app explicitly does not claim that a device-clock-based open-source economy is tamper-proof.
- Configurable displayed app name with
Chess-Masteras the default. - Material 3 light and dark themes with accessible target sizes.
- Typed GoRouter navigation.
- ARB-based localization generation for exactly 33 language options, with English as the verified source and explicitly unreviewed fallback draft.
- Riverpod dependency injection.
- Explicit success/failure values for expected application errors.
- Structured logging with redaction of names, addresses, tokens, and team codes.
- Versioned SQLite schema and atomic first-run creation.
- Privacy-safe Android manifest, local backup exclusions, and cleartext disabled outside debug builds.
- Fast branded splash with reduced-motion support.
- Optional ten-page onboarding with durable completion state.
- Responsive home, play-mode selection, and optional player setup.
- Legal-move-driven accessible chessboard with promotion choice.
- Captured-piece panels, material advantage, SAN history, undo/redo, board flip, draw, resignation, pause surface, PGN copy, and match result summary.
- Asynchronous computer play at four resource-bounded difficulty levels with move locking, thinking status, analysis details, cancellation, and recovery.
- Engine-neutral lifecycle API plus a tested UCI Stockfish process adapter.
- Android ABI discovery and a strict source/checksum/load-test manifest gate for any future native Stockfish package.
- Fully offline local two-player coordination with optional names and no server or network dependency.
- Monotonic two-sided clocks with increment, pause/resume, lifecycle pause, timeout results, rematch reset, and clock-aware history restoration.
- Fixed White, fixed Black, or automatic after-move orientation and explicit opponent approval for undo, redo, and draw offers.
- Optional friend matches with validated four- or six-digit room codes, create/join/waiting/ready flow, assigned colors, move acknowledgement, state-hash verification, reconnect handling, and actionable failure states.
- A self-hostable Node.js/TypeScript WebSocket relay with authoritative legal move validation, memory-only rooms, expiring reconnect sessions, rate limits, input limits, origin controls, health checks, and graceful shutdown.
- Deterministic local-date daily challenges with midnight rollover, progress, completed/claim/claimed states, history, streak, debug date simulation, and explicit offline integrity limits.
- Non-negative local coin/hint wallet and atomic, idempotent SQLite ledger with before/after balances, stable sequence, challenge links, app version, chained integrity fields, validation, and JSON clipboard export.
- Confirmed computer-game hints that show and semantically highlight a suggested source/target move; failed generation never charges the wallet.
- Seventeen interactive tutorial lessons with objectives, instructions, legal validation, retry, durable progress, and first-completion rewards.
- Offline free-board and legal-move practice, strict custom FEN loading, and a schema-verified original CC0 puzzle catalog for mate, tactics, openings, and endgames.
- Searchable in-app chess/privacy/troubleshooting guide and factual feature catalog with availability labels.
- Local save, resume, rename, delete, FEN copy, PGN export, validated FEN/PGN import, and immutable move-by-move review with optional local evaluation.
- Idempotent local match history with result/mode/color/difficulty filters, review launch, complete derived statistics, confirmed reset boundary, and fifteen one-time timestamped achievements.
- Versioned typed settings with live theme, board, accessibility, gameplay, sound/haptic, startup, auto-save, and Android display behavior.
- Seven-tap documented Developer Options with diagnostics, FEN/PGN/board tools, ledger-safe economy tools, challenge simulations, multiplayer diagnostics, localization previews, typed feature flags, and storage integrity checks.
- Versioned local JSON export/import with preview, atomic merge/replace, foreign-key validation, selective confirmed resets, typed delete-all confirmation, and privacy-safe reward-ledger export.
- Searchable native/English language selector with system-language reset, immediate persisted switching, standard identifiers, documented format fallbacks, script-aware runtime tags, and 931-message parity across 33 ARBs.
- RTL navigation for Kashmiri, Sindhi, and Urdu while chess coordinates and notation retain their logical order; TalkBack labels, expanded-text tests, pseudo-localization, font fallbacks, and community review status are included.
The source is verified with Flutter 3.44.7 stable and Dart 3.12.2. The available machine currently has:
- Android Studio and an Android SDK
- Node.js 24.14.0
- npm 11.18.0
- Git 2.55.0.windows.3
- Android Studio's bundled OpenJDK 21 compiling the configured Java 17 target
- Dart SDK 3.12.2 stable
- Flutter 3.44.7 stable at
E:\Development\flutter - Android SDK 36.1 with Platform 35 and NDK
28.2.13676358; the Phase 12 debug APK build and API 36.1 emulator integration test pass
Use the JDK bundled with a current Android Studio or install JDK 17.
-
Install Flutter 3.44.7 stable with its bundled Dart SDK.
-
Install Android Studio, Android SDK API 36, Android build tools, and JDK 17.
-
Resolve packages and generated localizations:
flutter pub get flutter gen-l10n -
Verify the project:
dart format --set-exit-if-changed . flutter analyze flutter test flutter build apk --debug
The resolved pubspec.lock, Gradle wrapper scripts, and wrapper JAR are
committed. They were generated by the Flutter/Gradle toolchain, not hand-authored.
The visible Flutter title can be changed without restructuring the application:
flutter run --dart-define=CHESS_MASTER_APP_NAME="KnightForge"Optional development values:
CHESS_MASTER_ENVIRONMENT
CHESS_MASTER_RELAY_URL
CHESS_MASTER_STOCKFISH_PATH
No production relay URL is invented by default. Friend multiplayer remains
disabled until a distributor or self-hoster supplies an explicit ws:// or
wss:// relay URL. See friend multiplayer and
server setup.
CHESS_MASTER_STOCKFISH_PATH is a development-only escape hatch for a local UCI
executable. It is classified as unverified and is never accepted as release
evidence. See chess engine architecture.
The Android launcher label is in
android/app/src/main/res/values/strings.xml. Update it alongside the build-time
Flutter title when preparing a renamed distribution.
- Documentation index
- Architecture
- System requirements
- Database migrations
- Localization
- Translation contribution guide
- Logging
- Application flow
- UI and UX
- Accessibility
- Splash screen
- Captured pieces
- Game modes
- Chess engine
- Local multiplayer
- Friend multiplayer and relay
- Daily challenges
- Local reward economy
- Chess hints
- Practice and tutorial
- Puzzle catalog
- Saved games and review
- Settings system
- Developer Options
- Local data management
- Roadmap phases
- Exact next work
- Technology notes
- Legal and policy documentation
- Security threat model
- User suggestions and feature proposals
- Release preparation
- Repository: https://www.github.com/sanskarIN/Chess
- Creator: https://www.github.com/sanskarIN
- YouTube: https://youtube.com/@Sanskar-in
- LinkedIn: https://www.linkedin.com/in/sanskarin
- X: https://www.x.com/Sanskar_in
- Support: mailto:supportramsandesh@gmail.com
- Development contact: mailto:sanskarin@outlook.in
The project is licensed under GNU GPL v3.0 or later. The repository includes the complete license text, copyright and third-party notices, dependency audit procedure, privacy and security policies, and the Stockfish corresponding-source requirements that apply if a distributor adds Stockfish. No Stockfish binary or source archive is included in the current repository.
This repository is not ready for Play Store publication. Owner-controlled release signing, store review, physical-device accessibility/performance approval, community translation review, and final human legal authorization remain external gates. See the machine-readable release status.