Metadata-Version: 2.4
Name: termo
Version: 0.1.0
Summary: A modern game engine for building terminal-based games.
Project-URL: Homepage, https://github.com/termo-engine/termo
Project-URL: Repository, https://github.com/termo-engine/termo
Project-URL: Issues, https://github.com/termo-engine/termo/issues
Project-URL: Documentation, https://github.com/termo-engine/termo#readme
Author: Termo contributors
License: MIT License
        
        Copyright (c) 2026 yolezz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ascii,curses,game-engine,roguelike,terminal,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: windows
Requires-Dist: windows-curses>=2.3.1; (sys_platform == 'win32') and extra == 'windows'
Description-Content-Type: text/markdown

# Termo

**Termo** is a modern game engine for building terminal-based games in Python.
Think of it as *Pygame, but for your terminal*: a simple, well-documented API
covering the game loop, rendering, colors, sprites, input, entities, and
scenes — built entirely on the Python standard library.

```python
from termo import Game, Sprite

game = Game()

player = Sprite("@", x=10, y=5, color="green")
game.add(player)

game.run()
```

> **Status:** Termo is at version `0.1.0` — an early but functional
> foundation. The core API is stable enough to build real games on, but is
> still expected to grow.

---

## Features

- 🎮 **Simple game loop** — configurable FPS, delta-time based updates,
  clean start/stop handling.
- 🖥️ **Efficient rendering** — a character-grid canvas with diff-based
  redraws, so only changed cells are repainted each frame.
- 🎨 **Flexible colors** — named colors (`"green"`), hex (`"#00ff00"`), RGB
  tuples (`(0, 255, 0)`), and raw ANSI 256 indices, with automatic
  degradation on terminals with limited color support.
- 🧍 **Sprites & entities** — position, visibility, colors, and movement out
  of the box, or subclass `Entity` for fully custom game objects.
- ⌨️ **Keyboard input** — non-blocking polling with normalized key names for
  arrows, escape, enter, and more.
- 🗂️ **Scenes** — organize a game into menus, levels, and game-over screens
  with `game.set_scene(...)`.
- 🧩 **Groups** — manage collections of entities and update/draw them
  together.
- 📦 **Zero required dependencies** — built entirely on the Python standard
  library's `curses` module.
- 🧵 **Fully typed** — type hints throughout, ships a `py.typed` marker.

## Installation

```bash
pip install termo
```

On Windows, curses is not part of the standard library, so install the
`windows` extra as well:

```bash
pip install termo[windows]
```

Termo requires **Python 3.12+**.

## Quick start

```python
from termo import Game, Sprite

game = Game(title="My First Termo Game", fps=30)

player = Sprite("@", x=10, y=5, color="bright_green")
game.add(player)

game.run()
```

Run it, and you'll see a single green `@` sitting in your terminal. Press
`Ctrl+C` to quit. From here:

- Move things around with `sprite.move(dx, dy)` in an `Entity.update()`.
- Read the keyboard with the `Keyboard` passed into `Scene.update()`.
- Organize bigger games into `Scene` subclasses and switch between them
  with `game.set_scene(...)`.

See [`examples/`](examples/) for complete, runnable programs:

| Example | What it shows |
| --- | --- |
| [`hello_world.py`](examples/hello_world.py) | The smallest possible Termo game. |
| [`moving_player.py`](examples/moving_player.py) | Keyboard input and movement. |
| [`colors.py`](examples/colors.py) | Named, hex, and RGB colors. |
| [`animation.py`](examples/animation.py) | A custom `Entity` with frame-based animation. |
| [`mini_game.py`](examples/mini_game.py) | A complete mini-game: scenes, groups, collisions, score. |

Run any of them directly:

```bash
python examples/hello_world.py
```

## Screenshots

> _Screenshots and terminal recordings go here._
>
> Termo renders directly to your terminal via `curses`, so a static image
> can't fully capture it — an animated GIF or asciinema recording works
> best. Contributions welcome!

## Architecture

Termo is organized into small, focused subpackages under `src/termo/`:

```
termo/
├── engine/     # Game loop, delta-time clock, the Game entry point
├── graphics/   # Canvas, Color, Renderer, Sprite
├── input/      # Keyboard polling and key constants
├── entities/   # Entity base class and Group container
├── scenes/     # Scene base class
├── utils/      # Small shared helpers (clamp, lerp, sign)
└── exceptions.py
```

**How a frame happens:**

1. `Game.run()` starts a `GameLoop`, which initializes the terminal via
   `curses.wrapper` and creates a `Renderer` and `Keyboard`.
2. Each frame, the `Clock` computes `dt` (and sleeps if needed to hit the
   target FPS).
3. The `Keyboard` polls all pending key events, non-blocking.
4. The active `Scene`'s `update(dt, keyboard)` runs — by default, this
   updates every `Entity` in the scene's `Group`.
5. The `Renderer` creates a fresh `Canvas` sized to the terminal, the scene
   draws onto it, and the `Renderer` diffs it against the previous frame,
   only repainting cells that actually changed.

This separation means you can use as much or as little of Termo as you
want: drop a `Sprite` straight into a `Game` for a quick prototype, or
build custom `Entity` and `Scene` subclasses for a full game.

## Contributing

Contributions are very welcome! To get started:

```bash
git clone https://github.com/termo-engine/termo.git
cd termo
./build.sh   # cleans, installs, lints, tests, and builds the package
```

Or manually, with [`uv`](https://docs.astral.sh/uv/):

```bash
uv sync --extra dev
uv run pytest
uv run ruff check src tests examples
```

Please:

- Keep code fully typed and documented with docstrings.
- Add or update tests for any behavior change.
- Run `ruff check` before opening a pull request.
- Keep the public API beginner-friendly — Termo's whole goal is to make
  terminal games easy to start, while staying extensible for advanced use
  cases.

Bug reports and feature requests are welcome via GitHub Issues.

## License

See [`LICENSE`](LICENSE).
