# Orrery

An ASCII sci-fi-fantasy game for the terminal: a loose wrapping around a few
minigames (dungeon crawling, flying star systems, mining), with procedurally
generated everything.

```sh
cargo run                         # play (a random universe)
cargo run -- --seed 1312          # play a specific universe
cargo run -- names                # print generated names, no TUI
cargo run -- names --culture qaari -n 40
cargo run -- ship --seed 1312 -n 2   # print the 2nd derelict you'd board
cargo test
```

## Derelicts

Press `d` on the title screen to board a derelict. Each one is a ship-shaped
map: an engine room at the stern, a bridge at the nose, a spine corridor
between them, and rooms either side (cargo holds, a reliquary, a med-bay...).
You see only what your lamp reaches. Monsters stay dormant until they come
into view, then hunt you.

Walk over things to pick them up: `*` artifacts, `%` salvage, `!` medpatches
(press `m` to use one). Walk back into the airlock `Θ` to leave with what
you're carrying, which goes into your hold. If you die or abandon ship with
`esc`, you lose what you were carrying, but your hold is safe.

## Layout

| File | What it does |
| --- | --- |
| `src/app.rs` | Game loop (fixed 30 Hz tick) and the scene stack |
| `src/scenes/` | One file per screen. A scene handles keys, ticks and drawing, and returns a `Transition` (push, pop, quit) |
| `src/seed.rs` | Stable seed derivation: the whole universe is a function of one `u64` |
| `src/names/` | Name generator: per-culture syllables and templates, plus artifact names |
| `src/dungeon/` | Map and tiles; `fov.rs` (sight), `ship.rs` (generating derelicts), `crawl.rs` (turn rules, monsters, loot) |
| `src/term.rs` | Terminal setup, including the kitty keyboard protocol where supported |
| `src/cli.rs` | Command-line arguments and `orrery names` |

## Things to know

- **Seeds must stay stable.** `seed::derive` and `seed::rng` give the same
  output forever, and a test pins them. If you change them, every universe
  and save file changes too.
- **Names are tuned by ear.** Edit the syllable lists in `src/names/mod.rs`,
  then run `cargo run -- names --culture <name> -n 40`.
- **Held keys.** Only terminals with the kitty keyboard protocol report key
  releases. The title screen shows whether yours does. Real-time controls
  need a fallback for terminals that don't.
- **Cells are about twice as tall as they are wide.** For geometry, either
  double x, or draw on a braille `Canvas`, where the dots are roughly square
  (the title screen's orrery does this).

## Next

1. System flight and asteroid mining
2. Glue: galaxy map, ports, a market to sell salvage, scholars to identify
   artifacts, quest templates