Metadata-Version: 2.4
Name: squabble-game
Version: 0.1.0
Summary: Command-line SQUABBLE — a familiar-seeming but legally distinct word game
Project-URL: Homepage, https://github.com/klingj3/squabble-word-game
Project-URL: Repository, https://github.com/klingj3/squabble-word-game
Project-URL: Issues, https://github.com/klingj3/squabble-word-game/issues
Author-email: John Klingelhofer <jkklingelhofer@gmail.com>
License: MIT
License-File: LICENSE
Keywords: board game,cli,terminal,word game
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Python command-line SQUABBLE

A familiar-seeming but legally distinct word game for the terminal: local hot-seat play or computer opponents that search the move space each turn.

![Squabble demo](docs/demo.gif)

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Setup

From the repository root:

```bash
uv sync
```

Or with pip:

```bash
python3 -m pip install -e .
```

Copy `.env.example` to `.env` if you need to override where data files live (see **Data files** below).

## Data files

Dictionary and tile data are loaded from the directory pointed to by **`DATA_ROOT`**. If unset, it defaults to `game/data` next to the installed package (the usual layout in this repo).

You can set `DATA_ROOT` in a `.env` file at the project root (loaded automatically via `python-dotenv`) or export it in your shell.

## Run the game

```bash
uv run squabble
uv run squabble <human_players> <computer_players>
```

Or:

```bash
python3 -m game
python3 game_manager.py
```

### Moves (human)

- `quit` — leave the game
- `skip` — pass the turn
- `exchange <LETTERS>` — trade tiles (when bag rules allow)
- `define <WORD>` — look up a definition (when available)
- `<x> <y> <R|D> <WORD>` — play at column `x`, row `y`, direction right or down (coordinates use the same hex digit column headers as the printed board)

## Development

```bash
uv run pytest
uv run mypy game tests
```

Type checking targets the `game` package and `tests` with strict defaults (`pyproject.toml`).

## Layout

- `game/cli.py` — entry point and argument parsing
- `game/board.py` — board state
- `game/rulebook.py` — dictionary, scoring, validation
- `game/tile_bag.py` — tile pool
- `game/game_master.py` — turn loop and scoring
- `game/players/` — human and computer players
- `game/ui/` — rendering, panels, and display logic (includes deliberate animation delays for readability)
- `game/paths.py` — `DATA_ROOT` / `data_path()`
- `game/types.py` — shared type definitions
- `tests/` — pytest suite

The AI move search is fast enough that two computer players can complete multiple full games per second when run without the UI layer.

## Credits

- Word definitions sourced via the [Free Dictionary API](https://github.com/meetDeveloper/freeDictionaryAPI)
