Orrery 0.1.0: the galaxy, flight, cities, inventory and saves

Grows the derelict crawler into the whole game, and gets it ready to
publish.

- A galaxy of star systems joined by lanes, split between four peoples'
  territories, with a star map and a system map. Systems are modelled
  with Kepler orbits, moons inside their Hill spheres, belts past the
  frost line and stations at Lagrange points.
- Flight around one place at a time: arcade flight with a throttle
  fallback where held keys can't be detected, mining rocks for ore,
  landing, docking at stations, and boarding wrecks that come and go by
  the calendar.
- Your ship to walk about, and capital cities to land at: generated
  plans with walls, quarters and streets, building interiors, shops,
  taverns, scholars and armourers.
- Fighting with a weapon and a gun ready, six damage types and how each
  monster takes them, and armour that guards, wears and can be mended.
- Everything you own has a weight: a vim-keyed inventory, a pack and the
  ship's lockers, and trade in ore, salvage, arms and fuel.
- Characters with a people and a ship of their own, saved as versioned
  JSON on every scene change and on quit, with a character sheet, a
  saves list and a pause menu wherever you are.
- `orrery weapons`, `armour`, `galaxy`, `system` and `town` print the
  generators' output without the TUI.
- Release: README install steps for macOS and Linux, a Makefile whose
  install also works with macOS's install, an MIT licence, and Cargo
  metadata with rust-version 1.88.

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

1 files changed, 550 insertions, 16 deletions

diff --git a/README.md b/README.md
index b224202..8a31fb9 100644
--- a/README.md
+++ b/README.md
@@ -4,56 +4,590 @@ 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.
 
+## Installing
+
+Orrery is built from source. It needs git, Rust 1.88 or newer, and a
+terminal, and nothing else: no libraries to install, no assets to fetch.
+
+### macOS
+
+In Terminal (Applications → Utilities → Terminal):
+
+1. Install Apple's command-line tools, which bring git and the linker Rust
+   builds with:
+
+   ```sh
+   xcode-select --install
+   ```
+
+   A window asks to install them; click Install and wait for it to finish.
+   If it says they're already installed, go on to the next step.
+
+2. Install Rust:
+
+   ```sh
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+   Press enter for the standard installation. Then quit Terminal (⌘Q) and
+   open it again, so it can find `cargo`.
+
+3. Download Orrery and build it. The first build takes a minute or two:
+
+   ```sh
+   git clone https://git.skylarcloud.xyz/orrery.git
+   cd orrery
+   cargo install --locked --path .
+   ```
+
+4. Play:
+
+   ```sh
+   orrery
+   ```
+
+   If Terminal says `command not found`, run it as `~/.cargo/bin/orrery`.
+
+To update to the latest version later:
+
 ```sh
-cargo run                         # play (a random universe)
-cargo run -- --seed 1312          # play a specific universe
+cd ~/orrery
+git pull
+cargo install --locked --path .
+```
+
+Your saves carry over. They live in `~/.local/share/orrery/saves`, and
+`cargo uninstall orrery` removes the game but leaves them.
+
+**Which terminal.** Orrery plays in Terminal, with two caveats, and
+[Ghostty](https://ghostty.org) or [kitty](https://sw.kovidgoyal.net/kitty/)
+avoid both:
+
+- Terminal on macOS older than 26 (Tahoe) can't show 24-bit colour, so
+  Orrery's colours come out wrong there.
+- Terminal can't tell when a key is held down, so in flight `↑` and `↓`
+  step a throttle up and down instead of thrusting while held. Ghostty and
+  kitty can; the title screen says which kind you're in.
+
+Give it a big window, about 120 columns by 40 rows or more. Where the
+keys below say `ctrl`, that's the Control key, not ⌘.
+
+### Linux
+
+Install git and Rust 1.88 or newer (from [rustup](https://rustup.rs) or
+your distribution), then:
+
+```sh
+git clone https://git.skylarcloud.xyz/orrery.git
+cd orrery
+make install
+```
+
+`make install` copies `orrery` to `~/.local/bin` and adds an apps-menu
+launcher that opens it in kitty; `make uninstall` removes both. For the
+game alone, `cargo install --locked --path .` puts it in `~/.cargo/bin`.
+
+## Running from a checkout
+
+```sh
+cargo run                         # play: carry on as whoever you last played
+cargo run -- --seed 1312          # make a new character in 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 run -- weapons -n 20        # print weapons as you'd find them aboard wrecks
+cargo run -- armour -n 20         # print armour as you'd find it aboard wrecks
+cargo run -- galaxy --seed 1312      # print the star map: every system, its lanes, who holds it
+cargo run -- system --seed 1312      # print the star system the universe began in
+cargo run -- system --seed 1312 -n 7 # print the 7th system as `galaxy` numbers them
+cargo run -- town --seed 1312 --inside   # print its capital, and one of each kind of building inside
 cargo test
 ```
 
+## Characters and saves
+
+You play a character: a salvager with a name, a people they come from, and
+a ship of their own. Press `n` on the title screen to make one. Each line
+offers a suggestion, `←`/`→` steps through more of them, and you can type
+your own instead. Choosing where you're from changes the names on offer,
+unless you've typed one, and where you start: on the homeworld of your own
+people, at their seat (see The star map). A character also gets a universe,
+which is only a seed: type in someone else's to fly the same galaxy they
+do. You start landed, aboard your ship.
+
+`esc` opens a menu wherever you are in the game: flying, aboard your ship,
+in a city, at a dock, in a wreck. To quit, choose "Save and quit to the
+title" from it, and on the title `esc` quits Orrery; `esc` again just closes
+the menu. The menu also has whatever `esc` used to do there (abandon ship,
+take off, back to your ship, back out to the street), and keeps everything
+still while it's open. Anything else open (the inventory, a shop
+counter, a map, aiming) closes first.
+
+The game also saves itself every time the screen changes (landing,
+boarding, opening the map, coming back aboard) and when you quit, even with
+ctrl+c. Next time, `orrery` picks up the character you last played where
+you left them, and `enter` on the title carries on. `l` lists every saved
+character, to play one or delete one; `c`, on the title, in flight or
+aboard your ship, shows your character sheet: what's in your hold, on you
+and in your lockers, the wrecks you've boarded and how you left them, what
+you've killed, and what you've learned about what hurts it. You can rename
+your ship there (`r`).
+
+Saves are JSON, one file per character, in `$XDG_DATA_HOME/orrery/saves`
+(`~/.local/share/orrery/saves` by default). A save holds the universe seed
+and what you've changed in it: your hold, where you are and what day it is,
+which wrecks you've stripped, what you've learned. The universe itself is
+made again from the seed. Quit halfway through a derelict and you come back
+aboard it, just as you left it.
+
 ## Derelicts
 
-Press `d` on the title screen to board a derelict. Each one is a ship-shaped
+Fly alongside a wreck and board it (see Flight), or press `d` on the title
+screen to board one straight away. 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.
+Walk over things to pick them up: `*` artifacts, `(` salvage, `!` medpatches
+(press `m` to use one), `)` and `}` weapons, `[` armour. What won't fit in your pack
+stays where it is, and so does what you put down yourself; `g` (or `,`)
+picks it up, and lists what's there when there's more than one thing. Walk
+back into the airlock `Θ` to leave with what you're carrying. If you die or
+abandon ship (from the `esc` menu), you lose everything you carried but your
+own torch and rivet gun. What's in your ship's lockers is safe (see What you
+carry).
+
+Salvage is heavy (a stack of hull plates is 12 kg) and sells to a city's ore
+broker or at a station's market.
+
+### Fighting
+
+You fight with two weapons ready: one to hit with, used by walking into
+something, and a gun, fired with `f`. You start with your cutting torch
+and a rivet gun, and find more aboard: `)` blades and clubs, `}` guns.
+Machine shops have tools, armouries have the best stock, chapels and
+reliquaries have stranger things. Each weapon is rolled from a kind (a
+cleaver, a scattergun, a psalm-horn...) and a condition: worn ones hit
+softer, fine ones carry an affix ("serrated", "long-barrelled"), and the
+rare relic has two and a name of its own.
+
+- **Fire** (`f`): aim at the nearest thing in sight, `tab` for the next,
+  or move the reticle anywhere. The panel shows the odds of a hit. Shots
+  stray up to the gun's *spread* either side, so the odds fall with
+  distance; scatterguns fire several pellets that each stray on their own.
+  Guns hold a few rounds, and reloading (`r`) takes a turn. Gunfire is
+  loud: it wakes anything sleeping nearby.
+- **Ready** (`i`, then `w` on a weapon): readying another weapon takes a
+  turn, and the one in your hand goes into your pack. The inventory shows
+  every weapon's stats.
+
+Each kind of damage does something besides hurt:
+
+| Damage | Also |
+| --- | --- |
+| cut | the living bleed, a little less each turn |
+| blunt | knocks back; into a bulkhead, it staggers them |
+| pierce | goes through a monster's armour; fast rounds go through into what's behind |
+| burn | sets things alight for a few turns |
+| shock | may stun, costing the target its next turn |
+| hymn | may steady you as it lands |
+
+And every monster takes each kind its own way: rust-mites crack under
+blows, drones short out, rivets pass straight through a choir-wraith.
+Hitting something tells you how it took it, and the panel keeps what
+you've learned, from wreck to wreck. Bulkhead sentries shoot from where
+they're bolted; bilge-hounds run two steps to your one. Claws make you
+bleed, and a medpatch stops it. Welder drones spray fire from a few cells
+off and set you alight: you burn 1–2 a turn for a couple of turns, until
+the flames go out or a medpatch smothers them, and your torch does
+nothing to them. Cargo loaders lumber a step only every other turn, so you
+can get away, but they hit hard, and often knock you back a cell; into a
+bulkhead, you reel and lose a turn.
+
+### Armour
+
+You can wear a piece on your head, body, hands and feet. Each guards
+against certain kinds of blow, taking that much off one of that kind (a
+blow always does at least 1): a flight-jacket guards cut 2 and blunt 1 and
+keeps a claw wound from bleeding, insulated gauntlets guard shock, a
+choir-hood hymn, a vac-helmet pierce and blunt. A rust-mite's bite through
+a vac-helmet shows as "pierce 2 - 1 = 1". Armouries and crew berths have
+the most, chapels and reliquaries warded pieces. Like weapons, each piece
+is rolled from a kind and a condition: worn ones don't last as long, fine
+ones carry an affix ("insulated", "reinforced", "styptic-lined"), and the
+rare relic has two and a name of its own.
+
+Every blow a piece softens wears it by 1 (shown as "durability 12/30"),
+and so does every turn of burning a burn guard softens. Below half it
+guards 1 less against everything; worn out, it guards nothing at all,
+though it stays on you. An armourer mends it, for more the more worn and
+the finer it is: about half its price from worn out. Armour weighs what it
+weighs, and counts against what you can carry like anything else.
+
+## What you carry
+
+Everything you own is a thing with a weight. What you carry is limited by
+weight alone: 25 kg to begin with, more with a bigger pack from a city's
+shipyard (a frame pack, +10 kg, then a hauler rig, +10 more). Your ship's
+lockers hold the rest, up to 400 kg, and they're safe: only what you carry
+goes aboard a wreck.
+
+`i` opens your inventory wherever you're on foot: in a wreck, aboard your
+ship, in a city. It's laid out like Cataclysm: DDA's: what you wear and
+have ready at the top, then your pack by kind (weapons, armor, food,
+medical, artifacts, salvage), and all about the one picked out beside
+them: a weapon you're not holding says how it measures up against the one
+you have ready in its place, and armour against what you wear in its
+place. Aboard your ship the lockers sit beside your pack; at an
+armourer's, the rack; elsewhere, whatever's on the floor where you stand.
+
+Every row shows what it weighs and what it would fetch. At an armourer's
+that's their price; anywhere else it's about what a typical buyer would
+give, marked `~`: an armourer for arms and armour, a broker for salvage,
+a scholar for an artifact once one has told you what it is (`?` until
+then). Things no one buys show no price. `o` sorts both lists, within each
+kind, by name, weight, price, price per kilo, durability (the most worn
+armour first), strength (a weapon's average damage, armour's total guard)
+or how recently you came by it; `O` turns the sort round. Your sort is
+saved with your game.
+
+| Key | Does |
+| --- | --- |
+| `j` `k` | move |
+| `gg` `G` | top, end; `5G` goes to the fifth |
+| `ctrl-d` `ctrl-u` | half a page down, up |
+| `h` `l` | your pack, or what's beside it |
+| `/` | find by name or kind; `esc` clears it |
+| `o` `O` | sort by the next thing, turn the sort round |
+| `enter` | what you can do with it, as a menu |
+| `w` | ready a weapon, swapping it for the one in hand |
+| `W` `T` | wear armor, take it off |
+| `E` | eat |
+| `a` | use a medpatch, in a wreck |
+| `d` `D` | drop one, drop the whole stack |
+| `m` `M` | move one, or the whole stack, to the lockers, or take it from them or the floor |
+| `b` `s` | at an armourer's: buy what's on the rack, sell a weapon or armour of yours |
+| `r` `R` | at an armourer's: mend a piece of armour, or all of yours at once |
+| `esc` `q` `i` | close |
+
+Counts work as they do in vim: `3d` drops three. There's nothing to eat
+aboard the wrecks yet: eating is there for when there is.
+
+In a wreck, readying, wearing, taking off, eating and using a medpatch each
+take a turn, and close the inventory so you see what came of it. Looking,
+sorting and dropping are free.
+
+What you put down stays where you put it: on your ship's deck for good, in
+a wreck with the wreck, in a city until you leave it. That goes for your own
+cutting torch and rivet gun too, once something else is ready in their
+place: you can't put down the last thing you have to hit with, or to shoot
+with. If you lose everything aboard a wreck, your torch and rivet gun come
+back with you, if you had them; a hand left empty takes yours from the
+lockers, or a spare from the ship's stores.
+
+## Flight
+
+Take off from the pilot's seat to fly. Each star system is modelled properly: planets on Kepler orbits around the star (periods
+from Kepler's third law, eccentric orbits that speed up near the star), moons
+inside their planets' Hill spheres, an asteroid belt past the frost line,
+and stations at the Lagrange points 60° ahead of or behind a planet.
+
+You never fly at that scale. You fly around one *place* at a time: in orbit
+around a planet or moon, among the rocks of the belt, or by a station. Each
+place is its own local map, lit from wherever the star really is on that
+date, with nearby moons or a looming parent planet hanging in the sky.
+
+- **Fly:** turn, thrust, brake (`r` or `↓`). It's arcade flight: nothing
+  pulls on you. Without held keys, `↑`/`↓` step a throttle instead.
+- **Mine:** the laser (`space`) wears rocks down; they split and spill ore,
+  which you scoop up by flying over it. The hold takes 40 tons.
+- **Land or dock** (`l`) when slow and over a world, or close to a station.
+  On a world where people live you get up in the cockpit and walk aft
+  through your ship to the airlock (see Your ship), which opens onto the
+  landing field outside its capital (see Cities). Anywhere without a city
+  takes you straight to a simple screen about the place: at a station, a
+  dock that buys ore and salvage (`s`) and sells fuel (`f`). `l` there
+  takes off, or undocks, again.
+- **Get up** (`e`) when slow, to walk about your ship while it holds
+  station.
+- **Board wrecks** (`b`): blinking red beacons, also flagged `!` on the map.
+  Wrecks come and go. Each beacon calls for three to six weeks and then
+  fails, and the wreck is lost; new ones drift in all the while (a couple
+  at a time in most systems, more in graveyards). A wreck whose beacon is
+  calling when you set out for it is still there when you arrive, even if
+  the beacon fails on the way: you come by its last fix. It stays while
+  you're there, as does a wreck you've stripped, and is gone the next time
+  you come. The system map says how long each beacon has been calling, and
+  dims the `!` and warns when one is failing, so it'll wait for you only if
+  you go straight there.
+- **Travel** (`m`): the system map lists every place and how many days the
+  trip takes. Trips are quicker than real ones, and far places cost only a
+  little more than near ones: a moon is hours away, most planets two to
+  five days, and the far edge of the widest systems about ten. Trips aim
+  for where the destination will be when you arrive, and the calendar
+  moves on, so every planet does too. Each place is marked
+  with what you'll find there: `⌂` a capital city, `¤` a station that only
+  trades ore, `·` neither (empty worlds, giants with no ground, the belt).
+  Choosing a place also shows a survey of it: temperature on a thermometer,
+  with its swing over the year, day length, gravity, air, sky and how many
+  people live there. `g` swaps it for the star map.
+- **Jump** (`g`): the star map, to leave the system (see below).
+
+## The star map
+
+A universe is a galaxy of about ninety star systems, joined by lanes. You
+can only jump along a lane, so to reach a far system you jump through the
+ones between. Each jump takes a few days, longer for longer lanes, and
+burns a jump's worth of fuel however long it is. You come out at the edge
+of the new system, by its outermost planet or its belt, and fly in from
+there.
+
+Every system is held by one of the four peoples. Each has a seat, a system
+with their homeworld and its great capital, and their territory grows out
+from it along the lanes, so territories come in ragged patches of
+different sizes. Near a border the neighbours settle too, and keep the odd
+station; old battlefields cluster there.
+
+Systems come in kinds:
+
+| Kind | What's there |
+| --- | --- |
+| seat | a people's homeworld and great capital, busy stations |
+| settled | a capital and settled worlds, a station or two |
+| frontier | a small capital or an outpost station, little else |
+| desolate | no one at all, dead rock and ice, often a red dwarf. No fuel |
+| rubble field | few planets, and a wide belt thick with ore, worked by mining stations |
+| graveyard | an old battlefield: wrecks everywhere, few people |
+
+The map (`g` in flight, or from the system map) scrolls to follow your
+choice, with an inset of the whole galaxy. Each people's space is a stipple
+in their colour, brighter along the borders.
+
+- **Charted space.** You know the way through systems you've been to and
+  those one lane from them. Choose any of those (arrows, or `tab` for the
+  lanes from here) and the map plots the fewest jumps there; `enter` makes
+  them. Further out are faint uncharted dots, and the four seats, which
+  everyone knows. What's in a system you haven't been to you'll only know
+  from tavern talk: they'll tell you which neighbours are dead, or rich.
+- **Fuel.** The tank holds 4 jumps. Stations sell fuel at the dock (`f`)
+  and every city's shipyard sells it, along with extra tanks (+2 jumps
+  each, two of them).
+- **Stranded.** Run dry in a system where no one sells fuel and `t` on the
+  star map calls a tow to the nearest system that does. It's slow and
+  dear: what you can't pay, you owe, and what you earn (ore, artifacts,
+  salvage) pays it off first.
+
+## Your ship
+
+Your ship is somewhere you walk, too: the same dart you fly, with the
+cockpit in its nose, an engine room in each swept-back wing, and the
+airlock in the notch at the stern, and the name you gave it.
+
+When you land outside a city you get up from the pilot's seat, and the way
+out is at the other end of the ship: walk aft, down the corridor and through the
+hold, into the airlock `Θ`. Coming back, you climb in by the same airlock,
+and to take off you walk forward to the cockpit and sit in the pilot's seat
+`╥`.
+
+Out in space, `e` gets you up from the controls whenever you're flying
+slowly, and the ship holds station until you sit back down. If a wreck is
+alongside, the airlock boards it; otherwise there's only vacuum out there.
+
+On the way through you pass what you've gathered: the hold has a bin for
+every five tons of ore you can carry, more as cargo racks are fitted, and
+they fill with what you've mined. The shelf in the crew quarters shows the
+artifacts in your lockers, and the med-bay cabinet the medpatches; the
+weapons locker beside the shelf opens the lockers, as `i` does anywhere
+aboard. `g` picks up what you've put down on the deck. Bump anything to
+look at it. Shift and a direction runs, stopping at each doorway; the
+`esc` menu tells you which way to go.
+
+## Cities
+
+Land on a settled world or moon and you set down on a landing field outside
+its capital. Each city is generated from the place, so it's the same city
+every time you come back, and its size comes from how many people live on
+the world: from a walled town of about a hundred buildings to a sprawl of
+several hundred. Its streets, roofs and talk come from the culture that
+lives there: Qaari cisterns, Cant furnaces and pipework, High House
+fountains, Drift scrap.
+
+The world it stands on has a say too:
+
+| World | Outside the walls | Inside |
+| --- | --- | --- |
+| Desert | sand, cacti `ψ`, boulders | few parks, dry scrub, palms, small cisterns |
+| Ice | snow, ice spires `▲`, boulders | frost-ferns, glass-pines, frozen ponds |
+| Ocean | open sea `≈`, a black-sand shore | green gardens; the city's an island, its landing field on a spit and its other roads causeways out to sea |
+| Jungle | undergrowth and thick trees | parks everywhere, trees crowding the yards |
+| Barren rock | grey dust, crags, crystals `♦` | rust lichen, crystal spires, no ponds |
+| Forge | ash, basalt, burning vents `^` | ash-moss, fungus stalks `τ`, pools of lava |
+
+The weather on the day you land shows on worlds with air and water: frost
+from about 4°C down, freezing the ponds below about -4°C, and gardens going
+brown from 30°C up, the ponds dry by 46°C. And every city's ground is tinted
+a little its own way, so two on the same kind of world don't look alike.
+
+Walk in through the gate. Avenues run from the gates to the market square,
+and the rest of the city is split into quarters, each with its own name and
+its own streets: alleys and tenements in the poor quarter, workshops and
+warehouses in the works, big houses and wide streets on the rise around the
+palace, shrines round the temple, parks with ponds in the gardens. No two
+cities are laid out alike.
+
+Every building is a roof from the street. Step through an open door and the
+building becomes its own map, drawn larger, with rooms laid out for what it
+is: a house's kitchen and bedrooms, a palace's throne room and council
+chamber, a temple's nave, a tavern's taproom, a bathhouse's baths. Some
+doors are barred. You leave by the door you came in by, or from the `esc`
+menu.
+
+Shops have their trade painted on the roof. Walk up to a shop's counter, or
+bump the keeper, to trade:
+
+- **Ore broker** (`ORE`): buys all your ore at this city's prices, and
+  salvage, a stack at a time or all of it.
+- **Doctor**: sells medpatches, up to 9 on you and aboard together.
+- **Scholar**: for a fee, tells you what an artifact really is, then offers
+  to buy it. An artifact is worth the same everywhere, give or take what
+  this scholar likes.
+- **Tavern**: a round buys you a rumour about the rest of the system: where
+  wrecks went dark, where an ore sells best. Bigger cities have more than
+  one.
+- **Shipyard**: fuel, cargo racks (+20 tons of ore space, three sets),
+  better laser lenses (two, each cutting faster), extra fuel tanks (+2
+  jumps, two of them) and bigger packs (+10 kg, two of them).
+- **Armourer** (`ARMS`, usually in the works quarter): buys and sells
+  weapons and armour, and mends armour. Its counter opens your inventory
+  with the rack beside it, every price shown: `b` buys, `s` sells, `r`
+  mends the piece picked out and `R` everything of yours that needs it, on
+  you and aboard. They pay about half what they'd charge, and less for
+  worn armour. A rack holds six to ten weapons and two to five pieces of
+  armour and is restocked every fortnight; what you sell goes on it, so you
+  can buy it back until then. Each people stocks its own sort: Qaari blades,
+  wraps and veils against burns and cuts; Cant shock and burn tools, and
+  insulated plate; High House duelling pieces and fine plate and warded
+  pieces, in fine condition; Drift guns and patched vac-gear. About one
+  rack in five has a relic weapon, at a price, and now and then a relic
+  piece of armour. You can sell a weapon you have ready if you've another
+  of its sort to ready in its place, even your own torch or rivet gun; and
+  armour off your back.
+
+Brokers, scholars and armourers deal in what you carry and what's in your
+ship's lockers alike; the lockers' are marked "(in your ship)". What you
+buy that won't fit in your pack is sent to your ship. Prices differ from
+city to city but stay the same in any one.
+
+People walking about step aside as you walk through them. People who stay
+put (stallholders, guards, anyone at work indoors) are in the way, and
+bumping them is how you talk to them. `t` talks to whoever is next to you;
+passers-by will sometimes point you to a shop you haven't found yet.
+
+- **Run:** shift and a direction runs until something changes: a turning,
+  a door, someone in the way.
+- **Map** (`m` or `tab`): the whole city, with its quarters, the shops, the
+  palace and the temple marked.
+- **Inventory** (`i`): what you carry. `g` picks up what you put down.
+- **Leave:** walk out the door you came in by, and back to your ship; or
+  pick it from the `esc` menu.
 
 ## 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/app.rs` | Game loop (fixed 30 Hz tick), the scene stack, and saving whenever it changes |
+| `src/save.rs` | Characters, what they've done, and save files: writing, listing, loading what still fits |
+| `src/scenes/` | One file per screen. A scene handles keys, ticks and drawing, and returns a `Transition` (push, pop, replace, quit). `inventory.rs` isn't a screen but a panel the scenes you walk in open over themselves; it asks its scene to carry out what you choose |
+| `src/items.rs` | Everything you can own: items, stacks, weights, what you wear, have ready and carry, and bigger packs |
 | `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/dungeon/` | Map and tiles; `fov.rs` (sight), `ship.rs` (generating derelicts), `crawl.rs` (turn rules, fighting, monsters, loot), `arms.rs` (damage types, weapon kinds and affixes, generating weapons, the geometry of a shot), `armour.rs` (armour kinds and affixes, guards and wear, generating armour) |
+| `src/town/` | Capital cities: `mod.rs` (tiles, buildings, people), `plan.rs` (generating the city: walls, gates, quarters, streets, buildings, shops), `interior.rs` (generating a building's inside when you enter), `words.rs` (names and what people say) |
+| `src/trade.rs` | Prices and what they buy: ore markets, medpatches, scholars, arms and armour and mending, what a typical buyer pays, fittings, fuel, tows and debt, tavern rumours |
+| `src/space/` | `galaxy.rs` (the systems, lanes, territories and routes), `orbit.rs` (Kepler orbits, trip times), `system.rs` (generating star systems of each kind, and their places), `survey.rs` (each place's temperature, day, gravity, air and sky, for show), `locale.rs` (each place's local map), `flight.rs` (flight and mining rules) |
 | `src/term.rs` | Terminal setup, including the kitty keyboard protocol where supported |
-| `src/cli.rs` | Command-line arguments and `orrery names` |
+| `src/cli.rs` | Command-line arguments, `orrery names`, `ship`, `weapons`, `armour`, `galaxy`, `system` and `town` |
 
 ## 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.
+- **Saves outlive code.** A save names ores and monsters by name, and loading
+  drops what no longer exists rather than refusing the save. Adding a field
+  is fine if it has a `#[serde(default)]`; anything older Orreries can't
+  read means bumping `save::VERSION`.
+- **Weights are grams**, in `u32`, shown as kg to a decimal place. Your
+  torch and rivet gun are kit (`Item::is_kit`): they go anywhere anything
+  else does, but survive losing what you carried (`Hold::lose_carried`).
+  Each hand always holds a weapon of its sort; `Gear::remove` won't empty
+  one, and `Gear::mend` puts right a save that says otherwise.
+- **A wreck in progress is saved as what's changed.** `ctx.crawl` holds
+  `Crawl::saved()` after every move: where you are, what's alive, what's
+  lying about, what you carry, the doors open and the cells seen. The ship
+  is made again from its seed (`Crawl::resume`), and the dice roll afresh
+  from there. A saved wreck that no longer fits the ship its seed makes is
+  dropped on loading, and you're back as you were before you boarded.
+- **A weapon's price comes from its stats** (`arms::value`): its average
+  damage times how surely it lands, plus its extra, raised to the 1.5 and
+  multiplied up for a fine one or a relic. A piece of armour's
+  (`armour::value`) comes from what it guards against, whether it stops
+  bleeding and how long it lasts, raised to the 1.25 and multiplied up the
+  same way; worn down it's worth less (`armour::worth`), by just what
+  mending it would cost (`armour::mending`), so buying one worn out and
+  mending it costs what a whole one does. An armourer's `trade::Terms` set
+  what they ask, pay and charge to mend against those. Racks are kept in
+  `Ctx::racks` (saved) only for the fortnight they're stocked for;
+  `trade::rack` stocks one afresh when the fortnight turns, and a rack
+  saved before armour has none until then.
+- **A city's world changes its plan, but not its weather.** `town::Land`
+  holds the world's `Terrain` and today's frost and drought. Only the
+  terrain goes into `town::generate` (`plan::Lay`), so a city is laid out
+  the same whenever you land; the weather and `Town::tint` only change how
+  `scenes::town::theme` draws it.
+- **Pause menus are panels, not scenes**, like the inventory
+  (`scenes::pause`): the scene beneath stays drawn, and stops ticking.
+  `Transition::Title` closes everything above the title screen, which is
+  always at the bottom of the stack.
+- **Save version 2 is the inventory.** Version 1 saves are converted as
+  they load (`save::from_before`): weapons and medpatches go on you,
+  artifacts into the lockers, and whatever's too heavy to carry into the
+  lockers 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.
+  need a fallback for terminals that don't. Keys held down when the scene
+  changes stay with the old scene: they don't count as held, and their
+  auto-repeats are dropped, until they're let go (`Ctx::admit`), so the
+  step out of an airlock doesn't walk you straight back in.
 - **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).
+  (the title screen's orrery does this). Local flight maps use one unit per
+  cell across and two per cell down.
+- **Three coordinate systems.** The galaxy is in light-years, y up. Star
+  systems are in AU and days, y up, anticlockwise. Local maps are y down,
+  like the screen.
+- **Wrecks are made by the calendar.** `System::wrecks_on(day)` makes them
+  in ten-day batches, each seeded from the system and the batch's number,
+  so any day's wrecks are always the same and nothing about them needs
+  saving except which you've stripped, and the day you set out for where
+  you are (`Ctx::departed`): `System::wrecks_at` adds the wrecks calling
+  then, so one whose beacon failed on the way is still there. Naming a
+  wreck generates its whole ship, so a system caches batches it has made.
+- **The first system never changes.** The system a universe started
+  everyone in, before there was a galaxy, is still generated by
+  `system::generate` from its seed alone, drawing from the RNG exactly as
+  it did; old saves are there. Other systems are made by
+  `system::generate_as` from what the galaxy decided about them, and can
+  change freely.
 
 ## Next
 
-1. System flight and asteroid mining
-2. Glue: galaxy map, ports, a market to sell salvage, scholars to identify
-   artifacts, quest templates
+1. Astrology and culture woven into the sky (to be designed)
+2. Glue: quest templates, and reasons to cross the map
+
+## Licence
+
+MIT. See `LICENSE`.