A cross-platform chess game built with Flet.
- Overview
- Download
- Features
- Installation
- Usage
- Configuration
- Current Limitations
- Roadmap
- Contributing
- License
Pawn Passant is a cross-platform chess application built with Flet, a Python framework that wraps Flutter for native desktop, mobile, and web UIs. It delivers a polished chess experience with full rules enforcement, move animations, a configurable chess clock, and an AI opponent powered by Leela Chess Zero (Lc0).
The application separates game logic from presentation. The backend uses python-chess for move validation and rules enforcement, while the frontend provides a responsive, interactive interface. Components communicate through an event-driven signal bus, keeping the architecture modular and testable.
Grab the latest build for your platform:
| Platform | Format | Link |
|---|---|---|
| Windows | Installer (.exe) |
Download |
| Windows | Portable (.zip) |
Download |
| Android | APK (.apk) |
Download |
All assets are built automatically via GitHub Actions and signed for Android. See the Releases page for the full changelog.
- Full chess rules — En passant, castling, promotion, check, checkmate, stalemate, insufficient material, 75-move rule, fivefold repetition
- Configurable chess clock — Bullet, Blitz, Rapid, and Classical presets with custom time control and millisecond precision at critical time
- Move animations — Adjustable speed (off, fast, normal, slow)
- Drag-and-drop or click-to-move — Both interaction modes supported
- Promotion dialog — Interactive overlay to choose Queen, Rook, Bishop, or Knight
- Captured pieces panel — Visual display organized by color
- Legal move highlighting — Dots and rings for available destinations
- Board auto-flip — Optionally reverse orientation after each move
- Coordinate labels — Optional file/rank labels on board edges
- Draw and resign — Offer draw or resign with optional confirmation
- Move confirmation — Optional dialog before committing each move
- Responsive layout — Three breakpoints (mobile, tablet, desktop) with adaptive UI
- Persistent settings — Preferences saved across sessions (Android SharedPreferences, Windows JSON)
- Settings page — Configure board display, gameplay, and clock preferences
- Developer mode — Load test positions for debugging (set
PAWNPASSANT_DEV=true)
- Python 3.11 or later
- uv (recommended) or pip
# Clone the repository
git clone https://github.com/Sakth1/PawnPassant.git
cd PawnPassant
# Create and activate a virtual environment with uv (recommended)
uv venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# Install dependencies
uv syncIf you prefer pip:
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # macOS/Linux
pip install .Prebuilt binaries for Windows (portable ZIP and installer) and Android (APK) are available on the Releases page.
python src/main.pyOr with the Flet CLI:
flet run- Start a game — Select a time control preset (or enter a custom one) and choose to play against the computer or another player.
- Move pieces — Click a piece to select it, then click a destination square. Alternatively, drag and drop pieces.
- Promote a pawn — When a pawn reaches the back rank, choose a piece from the promotion dialog.
- Use the clock — The chess clock runs automatically. When your time runs out, the game ends.
- Draw or resign — Use the buttons below the clock to offer a draw or resign.
Set the PAWNPASSANT_DEV environment variable to true to expose a test position selector:
# Windows PowerShell
$env:PAWNPASSANT_DEV = "true"
# macOS / Linux
export PAWNPASSANT_DEV=trueSettings are persisted automatically. On Windows they are stored at %APPDATA%\pawnpassant\settings.json; on Android they use the platform SharedPreferences.
| Category | Setting | Options |
|---|---|---|
| Board | Legal move hints | On / Off |
| Board | Tap feedback | On / Off |
| Board | Auto-flip board | On / Off |
| Board | Coordinate labels | On / Off |
| Board | Move animation speed | Off / Fast / Normal / Slow |
| Gameplay | Confirm moves | On / Off |
| Gameplay | Default promotion | Ask / Queen / Rook / Bishop / Knight |
| Clock | Critical time threshold | Seconds (default: 10) |
| Clock | Show milliseconds | On / Off |
| Clock | Confirm draw / resign | On / Off |
- Draw agreement — Only the current player can offer a draw; the opponent cannot accept or reject it yet.
- AI opponent — The Lc0 integration is scaffolded but the bot does not yet make moves automatically.
- Local multiplayer — The "Play someone" option is marked as a work in progress.
- Online multiplayer — The game state defines an
ONLINEmode, but no networking implementation exists. - Captured piece drag feedback — Placeholder hooks exist but the drag interaction is not functional.
- Promotions
- Time control (clock backend and UI)
- Move animations
- Captured pieces display
- App icon
- Drag-and-drop piece movement
- APK signing and CI/CD pipeline
- Responsive UI
- Draw and resign options
- Home page with time control presets
- Chess game page
- Settings page
- AI opponent — Complete Lc0 integration so the computer plays moves with time-aware decision making
- "Play someone" mode — Local two-player (pass-and-play) mode
- Draw agreement flow — Allow the opposing player to accept or reject a draw offer
- Online multiplayer — Networked play against remote opponents
- Captured piece interaction — Drag feedback and interaction from the captured pieces panel
Contributions are welcome! To contribute:
- Fork the repository.
- Create a branch (
git checkout -b feature/my-feature). - Make your changes and ensure tests pass (
pytest). - Commit with a descriptive message.
- Push to your fork and submit a pull request.
The project includes a comprehensive test suite with unit tests, property-based tests, and fuzz tests. Please add tests for new functionality.
Distributed under the MIT License. See LICENSE for more information.