🏎️ 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:

python -m pip install tui-racing
tui-racing

For a source checkout:

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:

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

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 before making a substantial change. Release owners should follow 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.