Metadata-Version: 2.4
Name: tui-racing
Version: 0.1.0
Summary: A colorful arcade racing game for the terminal
Author: TUI Racing contributors
License-Expression: MIT
Keywords: terminal,game,racing,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment :: Arcade
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# 🏎️ TUI Racing

TUI Racing is a dependency-free, 1990s-inspired terminal racing game written in Python. Race four
AI drivers through colorful pseudo-3D environments, dodge rivals, and spend nitro at the right
moment to take the lead. The presentation combines the immediate feel of a handheld brick game
with curved roads, scaled cars, parallax scenery, and smooth changed-line terminal animation.

> **Project status:** public alpha. The package is prepared for PyPI but has not been published yet.

## Features

- Real-time physics, collisions, race positions, countdown, pause, and instant restart
- Five fictional cars with distinct speed, acceleration, handling, and nitro statistics
- Sunset Highway, Neon City, and Desert Run environments
- Easy, normal, and hard AI with lane changes, varied driving styles, and nitro use
- Responsive full and compact renderers for terminals down to 40×16
- Flicker-resistant alternate-screen rendering that only redraws changed rows
- Perspective road bands, moving scenery, speed streaks, start lights, and finish-line effects
- Unicode/ASCII and ANSI/no-color modes
- Cross-platform nonblocking controls with no runtime dependencies
- Per-user preferences and best times stored outside the package directory

## Install and play

Python 3.10 or newer is required.

Once the first PyPI release is published:

```bash
python -m pip install tui-racing
tui-racing
```

For a source checkout:

```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
tui-racing
```

Controls: **W/↑** accelerate, **S/↓** brake, **A/D** or **←/→** steer, **Space** nitro,
**P** pause, **R** restart, and **Q/Esc** quit.

Useful options:

```bash
tui-racing --car neon-bolt --track neon-city --difficulty hard --quick-start
tui-racing --ascii --no-color --no-sound
tui-racing --help
```

Sound is reserved for a future optional backend; `--no-sound` is already accepted so scripts do
not need to change when it lands. The game never requires a network connection.

## Development

```bash
pytest
ruff check .
ruff format --check .
python -m build
```

The simulation lives in small independent modules under `src/tui_racing`, keeping rendering and
terminal input out of physics and AI tests. Cars and tracks are immutable data objects, making new
content straightforward to add in `cars.py` and `tracks.py`.

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before making a substantial
change. Release owners should follow [PUBLISHING.md](PUBLISHING.md); publishing uses PyPI Trusted
Publishing and does not require a long-lived package token.

## Roadmap

- Sound backend with a silent cross-platform fallback
- More track geometry, weather, and traffic hazards
- Championship and ghost-racing modes
- Accessibility presets and remappable controls
- Replay data and additional car silhouettes

## License

MIT © TUI Racing contributors. All terminal artwork is original.
