Backgammon TUI
A modern, polished Backgammon terminal game built with TypeScript, React & Ink
Creator & Developer
2026
Other
9 Technologies
Interactive Terminal Gameplay, Heuristic AI & Real-time HUD
Experience full Backgammon gameplay directly in your terminal: navigate points via Arrow keys or Vim keybindings, roll dice, execute moves with hit/bar-entry validation, play against the heuristic AI opponent, undo moves, and switch themes on the fly.
Testing & Walkthrough Guide
- 1Install globally or run immediately with npx backgammon-tui, or clone the GitHub repo.
- 2Select Single Player mode against the automated heuristic AI or play local 2-Player.
- 3Press Space to roll the dice and highlight all legal destination points.
- 4Navigate with Arrow keys or Vim keys (HJKL) and press Enter to select and move.
- 5Press U anytime during your active turn to undo moves, or Q to save and quit.
About This Project
A modern, keyboard-driven Backgammon TUI game built with Node.js, TypeScript, React, and Ink. Features a pure, decoupled domain rule engine with 100% standard Backgammon rules, an automated AI opponent with heuristic move selection, 5 curated themes, Unicode and ASCII rendering, move rollbacks (undo), real-time HUD telemetry, and Zod-validated state persistence.
Key Features & Capabilities
Strict & Decoupled Rule Engine
Domain core contains zero UI dependencies, implementing standard 1–24 indexing, maximal turn sequence calculation, blot hitting, bar entries, bearing off, and Gammon/Backgammon win scoring.
Heuristic AI Opponent
Includes an automated computer player evaluating legal move trees with heuristic weights prioritizing safety, blot vulnerability minimization, aggressive hitting, and bearing off efficiency.
Ergonomic Terminal UX & Navigation
Smooth keyboard navigation supporting both standard Arrow keys and Vim keybindings (HJKL), single-key shortcuts for Bar (B) and Borne-off (O) trays, and instant turn rollbacks (U).
5 Visual Themes & Symbol Modes
Curated color palettes (Obsidian, Classic, Nordic, Monochrome, High Contrast) with automatic fallback from rich Unicode glyphs (●/○, ⚀–⚅) to pure ASCII symbols (O/X).
State Persistence & Zod Schema Validation
Automatically saves active match progress, player stats, and theme preferences to disk, validated at runtime with Zod schemas to guarantee data integrity against corrupted save files.
Property-Based & Invariant Testing
Verified with 32 automated test suites in Vitest, combining unit tests and fast-check property testing to fuzz random dice permutations and prove game invariant guarantees.
Technical Architecture & Stack
Architected as a four-tier clean system: Domain Core, Engine & Command Layer, Centralized Input, and Ink React Terminal UI. The domain model represents the board as immutable states and pure mathematical transformations. The command processor pattern decouples UI triggers from state mutations and supports single-turn move undos via an immutable snapshot stack. Zod schemas validate both JSON configuration and active game serialization.
Key Technical Highlights
- Strict layered architecture: pure domain logic entirely isolated from React and Ink runtime
- Command processor pattern with snapshot-based turn move rollback (Undo)
- Official Backgammon maximal move resolution (enforcing use of both dice or higher die)
- Heuristic evaluation engine for single-player AI decision making
- Runtime schema validation with Zod ensuring corrupted save files never crash the process
- 32 comprehensive Vitest suites combining invariant checks and fast-check fuzzing
Core & Engine
Testing & QA
UI & Terminal
Distribution
Key Engineering Challenges & Solutions
Accurately modeling official Backgammon move rules—specifically maximal turn sequence constraints where a player must play both dice if possible, or the higher die if only one can be played.
Implemented a recursive branch-and-bound generator (findMaximalTurnSequences) that explores all legal move permutations for rolled dice, filters paths that maximize the total number of dice used, and enforces the higher-die rule in single-move branch collisions.
Rendering a responsive, geometrically balanced Backgammon board with upper/lower quadrants, center bar, and bearing trays in an asynchronous ANSI terminal stream without flickering.
Built a dedicated BoardViewModel projection layer that maps the 24 internal points into upper and lower row views, utilizing Ink Flexbox layouts with fixed terminal cell widths and ANSI color caching.
Providing a reliable move undo mechanism without introducing mutable state leaks or corrupting dice tracking.
Structured the GameEngine with an immutable snapshot stack capturing the initial board and remaining dice state at turn start, enabling single-move undos as clean rollbacks without affecting the RNG dice seed.
Clean Architecture in a Terminal Game
Backgammon TUI was designed as a showcase of pure domain separation:
src/
├── domain/ # Zero external dependencies. Pure board math & rule logic.
├── engine/ # Command pattern, turn lifecycle, AI evaluation, snapshots.
├── input/ # Terminal keybinding translation (Arrows, Vim, shortcuts).
└── ui/ # Ink React components, ANSI palettes, ASCII fallbacks.
The Maximal Move Sequence Rule
In tournament Backgammon rules, if a player rolls two dice (e.g. 6 and 2) and can legally play either the 6 or the 2, but not both, the player must play the higher die (6).
If both dice are playable, but only in a specific order (e.g., playing the 2 unblocks a point for the 6), the engine must reject any move that leaves the second die unplayable. The engine implements a recursive graph search that generates all legal permutations and restricts the player's choices strictly to maximal paths.