pablosgames

# 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](mailto:pablomurad@pm.me)

Made for people who still enjoy the command line.

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Pablo Murad.