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