Metadata-Version: 2.4
Name: gravitype
Version: 1.0.0
Summary: A terminal typing game where the words fall from the sky
Project-URL: Homepage, https://github.com/kanakOS01/gravitype
Project-URL: Repository, https://github.com/kanakOS01/gravitype
Project-URL: Issues, https://github.com/kanakOS01/gravitype/issues
Author: Kanak Tanwar
License-Expression: MIT
License-File: LICENSE
Keywords: cli,game,terminal,textual,tui,typing,typing-game
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Games/Entertainment
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: textual>=8.2.7
Description-Content-Type: text/markdown

# Gravitype

A terminal typing game where words fall from the sky. Type them before they hit the bottom — miss one and you lose a life.

Built with [Textual](https://textual.textualize.io/).

```
 ██████╗ ██████╗  █████╗ ██╗   ██╗██╗████████╗██╗   ██╗██████╗ ███████╗
██╔════╝ ██╔══██╗██╔══██╗██║   ██║██║╚══██╔══╝╚██╗ ██╔╝██╔══██╗██╔════╝
██║  ███╗██████╔╝███████║██║   ██║██║   ██║    ╚████╔╝ ██████╔╝█████╗
██║   ██║██╔══██╗██╔══██║╚██╗ ██╔╝██║   ██║     ╚██╔╝  ██╔═══╝ ██╔══╝
╚██████╔╝██║  ██║██║  ██║ ╚████╔╝ ██║   ██║      ██║   ██║     ███████╗
 ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝  ╚═══╝  ╚═╝   ╚═╝      ╚═╝   ╚═╝     ╚══════╝
```

## Features

- Falling-word gameplay with difficulty that ramps up as you score
- Two word categories: **Tech** and **General**
- 7 colour themes (Dracula, Nord, Tokyo Night, Gruvbox, Catppuccin, Cyberspace, 80s After Dark)
- Configurable starting lives (3 / 5 / 8) and bell-on-miss sound
- Persistent high score
- Pause, in-game help and keybind reference

## Requirements

Python 3.9+ (developed on 3.12). Any terminal with 256-colour support.

## Install

The quickest way, which puts `gravitype` on your PATH in an isolated environment:

```bash
uv tool install gravitype
```

Or with pipx, or plain pip:

```bash
pipx install gravitype
pip install gravitype
```

Then launch it:

```bash
gravitype
```

`python -m gravitype` works too, if you'd rather not rely on the script being on your PATH.

### Running from source

```bash
git clone https://github.com/kanakOS01/gravitype.git
cd gravitype
uv sync
uv run gravitype
```

## How to play

Words spawn at the top of the board and drift down. Type a word and it disappears the moment the text matches — no Enter needed. Points are `10 × word length`, and every 150 points bumps you up a level, which makes words fall faster, spawn more often and get longer.

If a word reaches the bottom you lose a life. At zero lives the run ends and your score is checked against the high score.

The input box flashes on a hit, and turns red the moment what you have typed is no longer the prefix of any word on screen.

### Keybinds

**Menu**

| Key | Action |
| --- | --- |
| `ctrl+p` / `escape` | Play / back to menu |
| `ctrl+s` | Settings |
| `ctrl+h` | Help |
| `ctrl+a` | About |
| `ctrl+q` | Quit |

**In game**

| Key | Action |
| --- | --- |
| `escape` | Pause / resume |
| `ctrl+g` | Quit to menu (run is not scored) |
| `ctrl+w` | Clear the word being typed |

## Configuration

Settings are edited in-game (`ctrl+s`) and stored in `~/.gravitype/`, so your high score follows you regardless of which directory you launch from:

```
~/.gravitype/
  config.json            your settings and high score
  theme_active.tcss      generated stylesheet, safe to delete
```

Set `GRAVITYPE_HOME` to relocate that directory — handy for keeping separate profiles, or for trying things out without touching your real save:

```bash
GRAVITYPE_HOME=/tmp/gravitype-test gravitype
```

`config.json` is plain JSON, so you can edit it by hand if you prefer:

```json
{
    "high_score": 1790,
    "theme": "dracula",
    "sound_enabled": true,
    "starting_lives": 5
}
```

Unknown keys are ignored and a corrupt file falls back to defaults, so it is safe to delete the file to reset everything.

Versions before 0.3 kept this as a `.gravitype_config.json` dotfile in the working directory. If `~/.gravitype/config.json` does not exist yet, Gravitype reads that dotfile once and migrates your settings forward, leaving the original where it is. An existing `~/.gravitype/config.json` always takes precedence.

## Project layout

```
gravitype/
  cli.py                     console entry point
  __main__.py                enables `python -m gravitype`
  core/
    config.py                config load/save + theme compilation
    paths.py                 per-user config and cache locations
    words.py                 word pools and level-based word picking
  tui/
    app.py                   app, screens and game loop wiring
    widgets/
      game_board.py          falling words, collision, scoring
      header.py              in-game score/level/lives bar
      main_header.py         banner and nav tabs
      screens.py             settings, help, about
      table.py               keybind table
    styles/
      base.tcss              layout and component styles
      themes/*.tcss          colour variables per theme
```

Themes work by concatenation: on startup `generate_theme_file()` writes the selected theme's variables plus `base.tcss` into `~/.gravitype/theme_active.tcss`, and hands that path to Textual as the app's stylesheet. It is written outside the package so an installed, read-only copy still works, and it is safe to delete — it regenerates on next launch. Adding a theme means dropping a new `.tcss` of variables into `themes/` and adding it to the Settings dropdown.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Credits

Colour themes are inspired by and adapted from [Smassh](https://github.com/kraanzu/smassh).

## License

[MIT](LICENSE) © Kanak Tanwar
