diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 566 |
1 files changed, 550 insertions, 16 deletions
@@ -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`. |