<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/logo_dark.png">
  <img alt="The Way Out" src="assets/logo_light.png" width="600">
</picture>

<h3>A top-down pixel-art escape-room shooter.</h3>

<p>
    <a href="https://github.com/ajhahnde/the-way-out/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ajhahnde/the-way-out/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
    <img src="https://img.shields.io/badge/version-v1.0.5-10b981?style=flat-square" alt="Version">
    <img src="https://img.shields.io/badge/python-3.12+-lightgrey?style=flat-square" alt="Python 3.12+">
    <img src="https://img.shields.io/badge/target-macOS-lightgrey?style=flat-square" alt="macOS">
    <img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?style=flat-square" alt="License">
  </p>

<p>
    <b>README</b> ·
    <a href="DOCUMENTATION.md"><b>Documentation</b></a> ·
    <a href="VERSIONING.md"><b>Versioning</b></a> ·
    <a href="CHANGELOG.md"><b>Changelog</b></a>
  </p>

</div>

---

<p align="center">
  <img src="assets/screenshot.png" alt="The Way Out — character select" width="780">
</p>

> The character-select screen: five playables, each with its own HP,
> speed, damage, fire-rate, and signature ability.

Pick a character, fight your way through locked rooms, work the levers
and pressure plates, and find the way out.

## Play

```bash
pip install pygame
python main.py
```

## Controls

| Input         | Action             |
| ------------- | ------------------ |
| WASD / Arrows | Move & aim (4-way) |
| Space         | Shoot              |
| Shift         | Dash               |
| E             | Use / interact     |
| Esc           | Pause / back       |

## Characters

Five playable characters, each with its own HP, speed, damage and
fire-rate profile: the balanced Wizard, the Penguin tank, the rapid-fire
Elf, the glass-cannon Shiggy, and the speedster Wolf.

## Levels

Three hand-authored escape rooms. Levels are plain text maps under
`assets/levels/` (see `LEGEND.md` for the tile vocabulary) plus a
`manifest.json`, so new rooms can be added without touching code. An
in-game editor (`editor.py`) edits them live.

## Project layout

| Path                                                          | Purpose                                  |
| ------------------------------------------------------------- | ---------------------------------------- |
| `main.py`                                                   | Entry point & game loop                  |
| `menu.py`                                                   | Title, settings, character & level menus |
| `levels.py`                                                 | Level loading & runtime                  |
| `units.py`                                                  | Player & enemy logic                     |
| `interactables.py` / `static_objects.py` / `tileset.py` | World objects                            |
| `editor.py`                                                 | In-game level editor                     |
| `theme.py`                                                  | Shared palette & UI helpers              |
| `audio.py`                                                  | Music & SFX                              |
| `assets/`                                                   | Sprites, audio, fonts, level maps        |

A deeper walk-through of each subsystem — the game loop, levels,
combat, the editor, the save file, and the self-updater — is in
[Documentation](DOCUMENTATION.md).

## Build (macOS)

```bash
./build_mac.sh        # arm64 .app
./build_mac_intel.sh  # x86_64 .app
```

The app self-updates from this repository on launch via `updater.py`;
save data lives outside the app bundle and is never touched by updates.

## Versioning

Semantic versioning (`vMAJOR.MINOR.PATCH`); each release is a single
annotated git tag. See [`CHANGELOG.md`](CHANGELOG.md) for the history.

## License

Apache License 2.0 — see [`LICENSE`](LICENSE).

## See also

- [FlashOS](https://github.com/ajhahnde/FlashOS) — AArch64 bare-metal kernel for the Raspberry Pi 4 Model B.

---

[Next: Documentation →](DOCUMENTATION.md)