Metadata-Version: 2.4
Name: hoop-higher
Version: 0.3.0
Summary: Terminal higher-or-lower NBA game scaffold
Project-URL: Homepage, https://github.com/Davi-Gurgel/hoop-higher
Project-URL: Repository, https://github.com/Davi-Gurgel/hoop-higher
Project-URL: Issues, https://github.com/Davi-Gurgel/hoop-higher/issues
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: nba_api>=1.10.2
Requires-Dist: platformdirs>=4.9.4
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: sqlmodel>=0.0.38
Requires-Dist: textual>=8.2.8

# Hoop Higher

[![PyPI](https://img.shields.io/pypi/v/hoop-higher.svg)](https://pypi.org/project/hoop-higher/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)

![Hoop Higher gameplay](docs/assets/hoop-higher-gameplay.svg)

Hoop Higher is a terminal game for NBA fans: you see one player's points from an NBA box score, then guess whether another player scored higher or lower.

It is quick to start, easy to play from the keyboard, and built around short runs that test your NBA instincts one matchup at a time.

## Play

Run it without installing:

```bash
uvx hoop-higher
```

Or install the command:

```bash
uv tool install hoop-higher
hoop-higher
```

`hoop-higher` is the only supported command name.

## How It Works

Each question gives you a player and their point total. Your job is to decide whether the next player scored more or fewer points in that same game context.

After every guess, Hoop Higher reveals the answer, updates your score, and moves to the next comparison. Runs are saved locally so you can track your best scores, streaks, and overall stats.

## Game Modes

| Mode | What to expect |
| --- | --- |
| Endless | Keep playing through misses. Wrong answers cost points, but the run continues. |
| Arcade | One miss ends the run. Higher stakes, higher reward. |
| Historical | Play from randomly sampled historical NBA dates. |

## Controls

| Key | Action |
| --- | --- |
| `H` | Guess higher |
| `L` | Guess lower |
| `Left` / `Right` | Move between choices |
| `Enter` | Select or confirm |
| `Esc` | Go back |
| `Q` | Quit |
| `1`, `2`, `3` | Pick a game mode |
| `T` | Toggle light/dark theme |

Hoop Higher starts in its dark theme. Press `T` on any screen to switch between
the dark and light palettes; the choice is saved and restored on the next run.

## Data

By default, Hoop Higher uses real NBA game data through `nba_api` and caches results locally so future runs are faster.

If the live NBA data source is slow or unavailable, you can still try the game instantly with mock data:

```bash
HOOPHIGHER_STATS_PROVIDER=mock uvx hoop-higher
```

Local scores, stats, and cached games are stored in your platform's per-user data
directory (for example, `~/Library/Application Support/hoop-higher/hoophigher.db` on
macOS). Existing `var/hoophigher.db` databases remain in use so prior data is
preserved. To use another location, set `HOOPHIGHER_DATABASE_URL` to a SQLite URL,
such as `sqlite:////absolute/path/to/hoophigher.db`.

## From Source

```bash
git clone https://github.com/Davi-Gurgel/hoop-higher.git
cd hoop-higher
uv sync --all-groups
uv run hoop-higher
```

Run tests:

```bash
uv run pytest
```

## License

No license file is currently included in this repository.
