The roadmap

This is the plan for twarp end to end: twelve epics that carry it from an empty deterministic engine to a deployed universe a person can inhabit. It rests on a settled base: the protocol is frozen at v1, the architecture is ratified (a deterministic single-writer sim plus an append-only journal, Connect-RPC on the wire, Nostr identity), and a ten-document spec set, distilled clean-room from the surviving TradeWars corpus, is the requirements source. What this entry describes is the sequence built on top of that base: what each epic contains, where it sits, and why the epics run in this order and not another. The per-epic entries in this log cover the work itself; this one is the map.

The shape of the plan

There are two honest ways to slice a game this size. Horizontally: finish each subsystem end to end, all of combat before any of planets. Or vertically: build the thinnest playable path first, a walking skeleton, then flesh the subsystems out in the order play actually needs them. twarp is sliced vertically, and the reason is the fitness function: the test that matters is a person flying the game, not a green suite. TradeWars' heart, the loop that made people dial in nightly, is move, look, trade. Everything else decorates that loop. Vertical slicing puts a Merchant Cruiser in a real universe several epics before combat exists, and every epic after the skeleton is judged by whether it makes the next flight better.

The cost of slicing this way is that subsystems are not each built in a single pass: an epic may introduce a subsystem that a later epic extends, and the daily maintenance pass in particular gathers its chores across several epics rather than arriving whole. That is deliberate. A partial subsystem that serves the current flight is worth more than a complete one the flight cannot yet reach. The dependency graph below is the itinerary: solid edges are hard prerequisites, the dashed edge a soft one.

graph TD
    A["1 Engine kernel"] --> C["3 Walking skeleton"]
    B["2 Big Bang"] --> C
    C --> D["4 Knowledge and computer"]
    D --> E["5 Ports and trading"]
    E --> F["6 Turns and maintenance"]
    F --> G["7 Combat and deployables"]
    G --> H["8 Planets and citadels"]
    G --> I["9 Corporations and comms"]
    H --> J["10 NPCs and factions"]
    E -.-> K["11 Flagship client"]
    J --> L["12 Operations"]
    K --> L

The twelve epics

1 · Engine kernel

The deterministic substrate, and nothing else: a command queue, a reducer loop, an append-only journal, a replay harness, and the three clocks the engine keeps distinct. No game rules of any kind, only the skeleton that makes determinism testable from the first commit. Every change to the world arrives as a command, is serialized through the single writer, and is applied by a pure reducer whose only inputs are the current state and that command. The journal is the sole source of truth; the live state is a cache the journal can rebuild at any time.

Determinism is not a nicety here, it is the fidelity contract. A faithful reimplementation has to be able to prove that it reproduces the original's behavior, and the only way to prove it at scale is to replay: feed the same journal through the same reducer and demand the same bytes out, this year and next. That property is what lets every rule in the spec set become a test rather than an opinion, and it is why the replay harness belongs in the foundation rather than bolted on later.

The engine keeps three notions of time apart so that replay stays stable. The command sequence orders the journal and never consults a wall clock. The game day is a value inside the state, advanced only by a command. The real-world clock that decides when a scheduled event fires lives outside the kernel entirely, as a policy layer, so that a replay re-reads what the scheduler once did rather than re-deciding it. An engine that asked the operating system for the time mid-reduction could never replay to the byte, so it never does.

Everything downstream is a set of reducers bolted onto this kernel and a set of commands written to this journal. The published protocol is a typed contract over exactly those commands and the events they emit, which is why the wire surface can grow epic by epic while the v1 baseline never has to move.

2 · Big Bang

Universe generation, deterministic from a seed: the same seed and the same settings produce an identical universe, sector for sector and warp for warp. The entire map derives from one recorded seed-and-settings tuple stored with the game instance, which serves fidelity and replayability at once, since the world can always be regenerated rather than stored. A game runs from a single bang until an operator chooses to re-bang, and the game's age in days is a first-class, player-visible fact.

The universe is a directed graph of numbered sectors, a thousand of them by default, each with one to six outgoing warps and the occasional one-way edge. That directedness is where the navigation game lives: a sector's exits need not include the way you came in. From it fall the named structures a pilot learns to read, the dead ends whose only exit doubles back, the tunnels of two-warp sectors, the bubbles of a hundred sectors behind a single mouth. Generation is not a naive scatter. It must guarantee full traversability, defined as strong connectivity of the directed graph, so every sector can reach every other; it must keep FedSpace internally connected; and it must hold the whole map inside a bounded diameter, the maximum course length, measured as the eccentricity from sector one.

Onto that topology the generator places the fixed landmarks, and it must seat them before it scatters random warps so that no configuration is too small to hold them. FedSpace occupies sectors one through ten as the Federation-protected safe zone. Sol sits at sector one as the inexhaustible colonist source and one of three Class 0 ports, the others being Alpha Centauri and Rylos. StarDock, the single Class 9 port, carries the telltale signature of six warps out and seven or more in, and anchors the Major Space Lanes that thread Sol, StarDock, Rylos, and Alpha Centauri together. Ferrengal, the Ferrengi homeworld, takes a random sector. Ordinary ports scatter across a configured fraction of the map by a per-class weighting, placed as position and class only, so that their stock, production, and prices can be seeded later when trade comes online.

Because the whole thing is a pure function of a seed, it is testable standalone as graph invariants, long before a single ship flies through it: assert strong connectivity, assert the bounded diameter, assert the landmarks landed, and the universe is proven sound.

3 · Walking skeleton

The first playable moment, and the thinnest vertical slice that deserves the name. It brings up a Connect-RPC server, a NIP-42 authenticated session, NIP-51 whitelist admission, and the smallest verb set that constitutes play: look at the sector you are in, move to an adjacent one, spend the turn that movement costs, and subscribe to the stream of events the world emits. With those four verbs a player connects and flies the universe for the first time.

It is also where sovereign identity stops being an architecture diagram and becomes a login. A player is a Nostr key they hold themselves; admission to a game is a whitelist of those keys; and because identity is a portable keypair rather than a server-side account, it travels with the player across every client that will ever speak the protocol. The session that authenticates here is the same one every later verb rides.

This epic does almost nothing, and it is the pivot of the whole plan. It is the point at which the deterministic kernel and the generated universe first meet a live connection and a real pilot, the point at which the thing becomes dogfoodable, and therefore the point after which every epic can be judged by flying rather than by reasoning. Small as it is, everything above it in the graph depends on it.

4 · Knowledge and computer

The exploration ladder made real, in two halves. The first is the knowledge model: a strict separation between the universe's ground truth and what a given player has actually observed. A sector you have flown, a port you have docked, a warp you have traversed become part of your known universe; everything else stays dark. The map a pilot reasons over is their projection of the world, not the world itself, and the fog that projection leaves is the whole texture of exploration.

The second half is the shipboard computer, the instrument that turns that accumulated knowledge into decisions. It plots the shortest route between two sectors while honoring an avoid list; it dumps zero-turn connectivity; it lists the traders, planets, and corporations you know of; it shows your deployed mines and fighters; and it exposes the Computer Interrogation Mode reports, the machine-format adjacency and port records that the original's tool ecosystem was built to parse. Alongside it come the scans: a density scan reads the total mass of each adjacent sector and flags anomalies for no turns, and a holographic scan reads the full contents of adjacent sectors for one. The fixed density weights, planet five hundred, port one hundred, ship forty, mine ten, fighter five, limpet two as an anomaly, beacon one, are what let a pilot invert a raw density back into a guess at what is actually out there.

There is a deeper reason this epic exists in the shape it does. In the original, a stable machine-readable interface was added precisely so that external tools would not have to scrape the human screens; in twarp that machine format is not a bolt-on, it is the protocol itself, and the ANSI screens are views over it. This epic is where that principle first pays off, because it is where the information surfaces become typed queries and streams rather than text to be parsed. It turns a graph you can move through into a universe you can learn.

5 · Ports and trading

The game's heart, and the epic that turns a knowable universe into an economy worth flying. There are three commodities, Fuel Ore, Organics, and Equipment, and eight trading port classes distinguished entirely by their buy-and-sell signature across those three. Two adjacent ports form a trading pair when each sells what the other buys, and so the scattered ports of the map resolve into a lattice of routes, the buy-low sell-high circuits that are the point of the whole exercise.

Each port carries a live economy rather than a fixed price list: a productivity, a current stock, a percent of maximum. Prices ride a curve, so a lightly-traded commodity rises in value while a heavily traded one falls, and a depleted port both pays worse and haggles less flexibly. Stock regenerates daily toward maximum. Trade itself is not a menu but a negotiation: the port opens with a quote marked off its true price, counteroffers converge it, an offer beyond the tolerance band ends the session with the negotiated goods consumed and no trade, the classic penalty for greed, while a frivolous offer merely re-prompts without cost. How well a pilot haggles pays experience, and closing the connection mid-negotiation abandons the line rather than escaping it.

The special ports complete the commerce surface. The three Class 0 ports sell holds, fighters, and shields on a seven-day price cycle, the daily re-equip that keeps a pilot flying. StarDock, the one Class 9, fields the full facility row: the Federation Shipyards, where buying a ship trades in the old one under the rule that the yard takes the hull and everything aboard and hands back a bare new model; the Stellar Hardware Emporium and its device catalog; and the 2nd National Galactic Bank, with its deposit cap, its player-to-player transfers, and no interest. For traders who take the evil path, the same ports open a rob-and-steal menu once alignment falls far enough. The generated universe finally names its ports from the flavor pool, and with all of this in place the actual game arrives around the move-and-look loop.

6 · Turns and maintenance

The epic that makes the world a persistent place rather than a session. Its first half is the turn economy, the original's defining scarcity: a fixed daily allotment, and every meaningful action drawing against it. A warp costs the ship's turns-per-warp, which runs from two to fifteen by hull, so a fast light freighter and a lumbering interdictor pay very differently for the same journey; docking costs one; a holographic scan costs one; density scans and computer queries cost nothing. Unused turns do not bank at the boundary, which turns ship choice into a real trade between mileage and capacity. The overnight tax completes the economy: a good-aligned trader who ends the day carrying more than a threshold in loose credits loses a tenth of it, while bank deposits and evil-aligned traders are exempt. It is the rule that taught every trader to dock, deposit, and log off.

Its second half is the daily maintenance pass, the original's Extern. Rather than a separate program run against the data files while the board sits idle, twarp models it as a journaled command like any player verb, enqueued by the scheduler and applied by the same deterministic reducer that applies a warp or a haggle. There is no down state to run it against, because the world is the journal. The pass advances the game day, regenerates every port toward maximum, resets every trader's turns, and applies the tax, and it is the single place where all of the game's daily housekeeping accretes. The later epics fill the rest of its duty roster: FedSpace cleanup and the Major Space Lane sweep, cloak-failure rolls, planet production and colonist growth, citadel construction progress, planet collisions, bust clearing, Ferrengi and alien upkeep, inactive-player deletion, and daily log rotation.

Because the pass is driven by a real-world clock and the kernel is not allowed to know wall time, the scheduling lives outside the deterministic core as a policy layer, and replay re-reads what the scheduler once did rather than re-deciding it. A server that was down when a day boundary passed owes exactly one catch-up pass on boot, not one per missed day, so a dormant world does not accrue debt while it sleeps. And a client's event cursor survives a restart, because the event history is rebuilt from the journal at boot. This is the epic after which the game runs itself, with no operator required to turn the crank.

7 · Combat and deployables

The epic that makes the universe dangerous. Combat in TradeWars is deterministic, not diced: outcomes follow odds arithmetic, and the random texture lives in mine-detonation rolls and NPC behavior rather than in the exchange of fighters. The fighters an attacker needs to break a defender scale with the ratio of their odds, and a ship is destroyed outright once the attacker commits past its safety rating, the product of its fighters-plus-shields and its odds. A large assault is not one blow but a sequence of waves, each capped by the hull's maximum-per-attack stat, so the biggest warships trade fire over several rounds.

Entering a hostile sector runs a fixed order of events. A limpet mine may attach silently. Armid mines each roll to detonate, roughly half of them going off for about twenty points of damage apiece, chewing through shields into fighters into hull. Shielded planets fire quasar cannons in order. Then the sector's fighters resolve as exactly one of three kinds: offensive fighters attack at once, defensive fighters pose a challenge to attack, retreat, or surrender, and toll fighters demand a few credits per fighter or a fight. Around that core sit the deployables and devices that let a pilot shape the board: fighters set to a disposition, armid and limpet mines, the mine disruptor that clears mines from an adjacent sector, the photon missile that suppresses a target sector's mines, fighters, and quasars for a wave and forces cloaked ships to decloak, the corbomite device that retaliates against a killer from beyond a ship's own destruction, the atomic detonator, and the marker beacon. Warping blind into an occupied sector without one of your own fighters present fuses the ship.

When a ship dies, the pilot pods. Self-destruction drops the pod in the ship's tracked previous sector; being killed by another player runs a safe-path walk that carries the pod away from the killer toward open space. A pilot gets two pods in a day, and a third death, or a death in a Scout or the pod itself, means dead until the next day. Cloaking hides a ship as a mere density anomaly but carries a small daily chance of failure. Kills move experience and alignment, weighted by the victim, and killing Ferrengi pays a Federation bounty regardless of where a trader stands. This is also where the maintenance pass takes on its combat housekeeping, the Major Space Lane sweep and the FedSpace tow, and the quiet universe stops being safe to sleep in.

8 · Planets and citadels

The first epic that builds downward, off the sector graph and onto a planet's surface. Planets come into being by Genesis Torpedo, which blooms a new world in almost any sector up to a per-sector cap; the planet's class rolls from base weights that skew ever harder toward barren gaseous worlds as a sector fills. Terra, at sector one, is the inexhaustible source of colonists, who are ferried out in cargo holds and seeded onto new worlds to work them.

A colonized planet is a small factory. Its colonists are assigned across Fuel Ore, Organics, and Equipment production at class-specific ratios, so an Earth-like world and a glacial one earn their keep very differently, and output follows a bell curve that peaks when a planet is stocked to half its maximum population, growing below that line and dying off above it. Planets convert a share of that production into fighters, turning a worked world into a standing garrison. On top of the planet rises the citadel, a six-level ladder where each level unlocks a capability: the treasury and overnight docking at level one, the combat control computer that lets planet fighters defend at planet odds at level two, the quasar cannon at three, the drive that can TransWarp the whole planet between sectors at four, the shield generator at five, and the interdictor that pins ships in the sector at six. Construction is not instant; it consumes colonists as labor, stockpiled commodities as materials, and calendar days.

The surface adds its own verbs: land and claim a world, jettison or take colonists and cargo, move fighters and shields between planet and ship. A planetary transporter, installed at a citadel and paid from the ship's own funds, beams a trader and their ship together to a sector within range. An atomic detonator can end a planet entirely, once its colonists are dead. And because worlds are alive, this epic hands the maintenance pass its planetary chores: colonist growth and die-off toward the optimum, daily production and fighter output, citadel construction progress, and the collision risk that a sector packed past its planet cap runs each night as an unstable planetary mass.

9 · Corporations and comms

The epic that turns parallel solo players into a society. A corporation forms between players of compatible alignment, up to five to a company, under a CEO who holds real powers: the corporate memo, the password, the ejection of a member with their assets stripped and relocated, and the purchase of the Corporate FlagShip. Assets marked corporate, the ships exchangeable in citadels, the planets, the fighters, the mines, are recognized by every member where a personal asset answers only to its owner, and co-located members can pass fighters, shields, and credits between them. A corporation is the game's unit of trust, and therefore its unit of betrayal.

Around it comes the whole communications layer, which the original delivered as displays a pilot polled and which twarp delivers as typed streams. Subspace radio carries channel messaging; a Federation comm-net serves lawful commissioned traders; player-to-player mail, corporate memos, tavern announcements, and beacon text all become first-class messages. The daily log is the game-wide event feed, carrying kills, photon launches with their origin sectors, fighter contacts, and tows, and a pilot's own deployed fighters report the contacts they witness, a distributed sensor net spread across the sectors a trader holds. As push streams over the protocol, these are what make a populated universe feel inhabited rather than merely occupied.

This epic is cheap relative to the two that flank it, and its place in the sequence is deliberately soft: if the sociality of many players together proves to matter sooner than the depth of planetary industry, it can move earlier without disturbing anything downstream.

10 · NPCs and factions

The epic that lets the universe act on its own, through three non-player factions. The Federation governs FedSpace and the Major Space Lanes and enforces its law, no deployables in the safe zone, no attacks on protected traders, and it patrols in Imperial StarShips flown by named officers: one summoned magically to any violation and impossible to trap, others who patrol the open map and can be penned behind a fighter-blocked warp, since a Federal will not pass through a sector holding a player's fighter. The Federation hunts down evil-aligned owners of the Imperial StarShip wherever it finds them.

The alien traders are NPC pilots with their own experience and alignment, listable alongside players, drifting the map on a small chance per processing tick and refusing to enter any sector a player's fighters hold. The Ferrengi are the raider faction, themed on greed and based out of the defended homeworld Ferrengal. They travel in groups to ambush weakly defended ships, extort tribute from those who surrender, and hold grudges, mounting revenge hunts against pilots who cross them; they fly their own assault traders, battle cruisers, and dreadnoughts, and their numbers regenerate daily toward a cap. Killing them pays a Federation bounty regardless of a trader's alignment and moves that alignment sharply toward the light.

This faction work is placed deliberately late, because the rules here are the hardest to pin down from the surviving record and some of the constants have to be recovered from the original binaries rather than read from a manual. Slotting it after the systems that can be verified by flying keeps the reconstruction from blocking playable progress, and lets the recovery run in parallel with the earlier epics.

11 · Flagship client

The native, protocol-first client: the ANSI terminal experience that renders CP437 and the classic screens for players who want the original presentation. What makes it a first-class citizen rather than a nostalgia skin is that it is built entirely on the published schema. The terminal look is one consumer of the typed events, not the source of truth, which inverts the original arrangement where automation had to scrape screens that were drawn for people.

Because every client speaks that same published schema, a thin CLI harness, itself a bot speaking the protocol, can drive play in the flagship's place. That is not a testing convenience so much as the founding premise proving itself: a published contract is what makes automated play a first-class feature instead of a screen-scraping tier bolted on from outside. The client sits early in the dependency order, because it needs only trading to be real, and the harness that stands in for it is dogfooding the headline feature every day it runs.

12 · Operations

The epic that makes twarp a service other people can play rather than a program that runs on one workstation. It delivers the game as running infrastructure: a NixOS module, a production deployment, and the lifecycle administration that bangs a universe into being, tends it while it runs, and retires it when its time is done. This is the operational frame around everything the earlier epics built, the difference between a world that runs on a developer's desk and one that stays lit for a population of pilots.

It also holds the last seat at the maintenance pass, the cleanup of inactive players and the proper disposal of their estates, alongside the administrative machinery that keeps a long-lived game healthy. It comes last not because it matters least but because it is the frame a finished game is mounted in, and there has to be a game worth keeping up before the machinery that keeps it up earns its place.

The whole arc

Read top to bottom, the plan runs from a deterministic kernel with no rules to a deployed universe others can inhabit, sequenced so that each epic makes the next flight better rather than completing a subsystem for its own sake. That is the itinerary. The rest of this log is the flight record: each epic in its own entry, with the mechanics it lands, the flight that proves it, and the places the historical record ran thin and a rule had to be reconstructed.