Pablo’s Terminal Games

A collection of ten small board, strategy and puzzle games designed to be played entirely inside the terminal. No browser, no GUI, no accounts, no internet — just games.

+================================+
|                                |
|     PABLO'S TERMINAL GAMES     |
|                                |
|         VERSION 0.0.1          |
|                                |
+================================+

          > 1. Tic-Tac-Toe
            2. Connect Four
            3. Checkers
            4. Reversi
            5. Naval Battle
            6. Gomoku
            7. Mancala
            8. Minesweeper
            9. 2048
            0. Fifteen Puzzle

 Arrows/W-S move - Enter select - H help - S stats - A about - Q quit

Games included

#	Game	Modes
1	Tic-Tac-Toe	vs Computer, vs Player
2	Connect Four	vs Computer, vs Player
3	Checkers	vs Computer, vs Player
4	Reversi	vs Computer, vs Player
5	Naval Battle	vs Computer
6	Gomoku	vs Computer, vs Player
7	Mancala	vs Computer, vs Player
8	Minesweeper	single player, 3 levels
9	2048	single player
0	Fifteen Puzzle	single player

Every game has its own help screen (press H in-game) explaining the objective, controls and rules.

Features

Retro terminal interface with arrow-key menus, ANSI colors and Unicode box drawing (with automatic ASCII fallback).
Cross-platform keyboard input: works on Windows (msvcrt) and Linux/Unix (termios) with no configuration.
Correct game rules kept separate from rendering, so they are fully unit-tested (236 tests).
Local JSON statistics: games played, won, lost and drawn, plus records (2048 high score and best tile, Minesweeper best times, Fifteen Puzzle best moves/time).
Graceful behavior: invalid input is explained and re-asked, the terminal is always restored on exit, and a corrupted statistics file never crashes the program.
Completely offline. No telemetry, no analytics, no network requests, no accounts. Everything stays on your computer.

Requirements

Python 3.8 or newer (standard library only — nothing to install).
A terminal of at least 80x24 characters.

Installation

Clone or copy this directory anywhere. There is no build step and no dependency to install.

Running

Windows

python main.py

or double-click / run:

play.bat

Works in Windows PowerShell, cmd and Windows Terminal.

Linux

python3 main.py

or:

./play.sh

Works in any standard terminal emulator (Debian/Ubuntu included).

Controls

Menus: Arrow keys or W/S to move, Enter to select, number keys as shortcuts, Q or ESC to go back.
Board games (Tic-Tac-Toe, Connect Four, Checkers, Reversi, Naval Battle, Gomoku, Mancala): type coordinates or numbers (e.g. b2, d3, b6-a5, E5, 1-6) and press Enter.
Real-time games (Minesweeper, 2048, Fifteen Puzzle): arrow keys and WASD. Minesweeper: Enter/Space reveals, F flags.
Everywhere: H for help, Q/ESC to return to the menu.

Note: game 10 (Fifteen Puzzle) is selected with the 0 key.

Statistics

Statistics are stored in a local stats.json file next to main.py and survive between executions. View them from the main menu with S. No data ever leaves your computer; delete the file to reset everything.

Project structure

terminal-games/
|
├── main.py               entry point, main menu, help/stats/about
├── play.bat              Windows launcher
├── play.sh               Linux launcher
├── GAME_SPEC.md          internal contract for game modules
│
├── core/
│   ├── __init__.py       app metadata (version lives here, once)
│   ├── terminal.py       screen, colors, boxes, centering, prompts
│   ├── input.py          cross-platform single-key and line input
│   ├── menu.py           reusable arrow-key menu
│   ├── storage.py        local JSON statistics
│   └── utils.py          small shared helpers
│
├── games/                one module per game, all following
│   ├── tic_tac_toe.py    GAME_SPEC.md (pure logic + UI layer)
│   ├── connect_four.py
│   ├── checkers.py
│   ├── reversi.py
│   ├── naval_battle.py
│   ├── gomoku.py
│   ├── mancala.py
│   ├── minesweeper.py
│   ├── game_2048.py
│   └── fifteen.py
│
└── tests/                one unittest file per game (headless)

Development

Game rules live in pure logic classes with no printing or input, which is what the tests drive. The Game class in each module is the terminal UI on top. To add a new game, follow GAME_SPEC.md and register the module in main.py.

Running tests

python -m unittest discover -s tests

All 236 tests should pass in well under a second.

Author

Pablo Murad pablomurad@pm.me

Made for people who still enjoy the command line.

pablosgames

Recent commits

Readme