path: root/README.md

# 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.

## 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
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
[iTerm2](https://iterm2.com), [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. The others
  can; the title screen says which kind you're in.

In iTerm2, keep it up to date (3.6.9 or later: iTerm2 → Check for
Updates). If the title screen says held keys aren't detectable, turn on
Settings → Profiles → Keys → "Apps can change how keys are reported", then
quit Orrery and start it again.

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

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), `)` 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), 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, 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, `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. 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). 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. Astrology and culture woven into the sky (to be designed)
2. Glue: quest templates, and reasons to cross the map

## Licence

MIT. See `LICENSE`.