Orrery: game loop, name generator and derelict dungeons

An ASCII sci-fi-fantasy game for the terminal, built on ratatui.

- Game loop with a fixed 30 Hz tick and a stack of scenes; the kitty
  keyboard protocol is turned on where the terminal supports it, so later
  real-time scenes can tell when a key is held.
- Stable hierarchical seeds: the whole universe derives from one u64,
  with tests pinning the exact outputs so old seeds keep working.
- Name generator with four cultures, each with its own syllables and
  templates, plus unidentified/true names for artifacts.
- Title screen with an animated orrery, and a name forge for browsing
  generated names.
- Derelict ships to board: ship-shaped maps with an engine room, spine
  corridor, side rooms and bridge; symmetric shadowcasting sight;
  monsters that wake on sight and hunt; loot carried out through the
  airlock goes into the hold.
- `orrery names` and `orrery ship` print the generators' output without
  the TUI, for tuning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b224202
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# 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