Planning a Flight in the Game

The Planning Flow

Every path into the planner ends the same way: a draft, compiled on a private solver stack, landing in the craft's mission list. The chart follows one Transfer from the right-click to the ship flying it.

Ube boxes are the comparison; mantis is the pick; orange is the commit. The dashed loop is why a comparison can never describe a mission that is no longer on screen.

Walking Through It

1. Three ways in, one draft

The craft's right-click menu carries Transfer ▸ and Intercept ▸, each a submenu over the one number the verb needs — a capture altitude (Low 400 km, Medium 5,000 km, High 50,000 km) or a closing distance (1, 10, 100 or 1,000 km). Plan mission and Replace mission open the planner without a target, and the top bar's Missions button opens it on a craft picker.

Whichever way it opens, the planner starts a draft in the nearest start mode the craft allows: from the craft (nothing flown yet — the craft's own orbit at the instant the mission starts, read off the ship rather than off the launch state craft.json authors), queue after the current mission (the new one starts from where that one ends, tanks as it left them), or replace now (cut the current mission at the clock). And the game drops to Real time: a queued or replacing draft, and every option it compiles, starts from "now" — at 36h/s a 20-second comparison would describe a ship thirty simulated days in the past.

2. Pick a target on the map

A targeting verb arms a crosshair. The next click is a pick, judged before anything is authored: a Transfer needs a body the compiler can target; an Intercept needs a craft circling the same body as the planner's own, and a refused pick names both bodies and stays armed. Asteroids are refused for now — the compile stack cannot resolve one. A pick that lands authors the steps (Transfer → Capture, or a single Intercept) and starts the comparison straight away.

3. Compare the options

The planner never prices a choice with an estimate. Each option is a real compilation — several run at once, each on its own private compile stack, at below-normal thread priority and up to a cap of four that leaves two cores for the game and the OS — routed through the same entry point Accept will use — so an option compiled from a queued start begins from the predecessor's recorded end state, exactly as the committed mission will. A preview creates no record, bakes nothing into the store and moves no craft.

4. See them, pick one

As each option lands it gets a row in the panel and a trace on the map. Pressing a row or clicking a trace does the same thing: the option's settings are written into the draft's step, and it turns mantis on every map.

The rows are a table, and each carries four figures: what the option costs, how long until it departs, how long the trip takes once it starts, and the date it arrives. A candidate is chosen on all four at once, and four figures across as many as twelve candidates only compare when they line up in columns — which is why the comparison is a table rather than the strip of labelled buttons it was for two rounds. The columns are fractions of the panel's width, so dragging the side panel wider spreads them instead of clipping.

The rows are ordered by arrival, soonest first. That is the question a comparison is asked, but it can only be answered by an option that has landed — before that there is no arrival to sort by. So the sort runs over the landed rows only; anything still solving keeps its compile order below them, and an option that failed sinks to the bottom, dimmed, rather than disappearing: a row that vanished would read as one that was never tried. One consequence is worth knowing: an option that lands can appear above the row you were reaching for.

5. Accept & Fly

Accept compiles the draft for real — the full screen dims under the solar-system wait animation until it lands — and the result becomes a mission record in the craft's list. The scheduler decides which of a craft's missions owns it at each instant; the executor replays that mission's compiled trajectory against the sim clock. If the compile has something worth saying (a best-effort capture, a burn the tanks cannot pay for), the planner stays up and says it; otherwise it steps aside onto the mission it just made.

How the Options Are Built

This is the part most worth understanding before adding options, so it is spelled out step by step.

The two axes

A Transfer's candidates vary exactly two authorable knobs — nothing a mission author could not write into craft.mission.json by hand:

Knob	Values	What the compiler does with it
profile	Efficient / Fastest / Torch	Efficient flies the minimum-energy arc; Fastest trades propellant for an earlier arrival, gated so the single capture burn still fits its pass. Torch is the partial brachistochrone: inject into the earliest arc whose injection alone costs at most 40% of the tank, coast, turn over late in the cruise with a required burn re-planned as its own leg down to the arrival speed the Efficient arc would have, then capture. Offered only to a craft with more than 15 km/s of budget, and always last.
throttlePercent	each rung of the Main drive ("100%", "50%")	On a constant-power drive the rung is the efficiency lever — the DFD gives 13.66 kN at 6,000 s or 6.83 kN at 12,000 s — so every rung is a candidate, the step's authored rung first. A drive whose rungs share one Isp (a chemical engine's 25/50/75/100 throttle) has no Power axis: its steps change how long a burn takes, not the flight. The note under the table names the thrust and Isp a row's percentage stands for.
windowAuto	off ("soon") / on ("window")	Off: scan departures across the step's own horizon. On: first locate the classical departure window with the window finder (searching up to 1,600 days for a candidate), then solve inside it. Declined for a craft orbiting the Sun — there is no departure planet to phase against.

The candidates are the product of the enabled knobs, compiled in a fixed order — Efficient, soon; Efficient, window; Fastest, soon; Fastest, window; then Torch's — cheapest question first, so the option most authors want fills in first. That is the order they are compiled in, and the order the table shows until they start landing; from then on the landed rows re-order themselves by arrival. An Intercept has no knobs the compiler distinguishes, so it has one candidate, there to draw and price the close.

An orbit change is drawn before it is compiled. Authoring a ChangeOrbit puts three rings on the map around the craft's central body: the orbit it is on now in grey, the orbit the burn would produce in purple, and the circular orbit the step would finish on as a dotted ring — with a KSP-style widget on the burn node whose handles edit the burn itself, prograde and retrograde along the direction of travel, radial out and in along the frame radius. Pull prograde and the far side rises. The number in the form follows the drag and the drag follows the number when it is typed, and the step still authors one circular altitude: the apsis opposite the node, which is where the circularisation happens. The form gains the craft's present orbit in words above the box — 300 km × 300 km around Mars, period 1h 52m — because "400" means nothing on its own: it is a raise from a parking orbit and a deorbit burn from a capture. A burn asking for escape, or for the ground, is cut back to the last one that closes and says so.

An orbit change gets a comparison of its own. A ChangeOrbit reads one profile word, BiElliptic: instead of the Hohmann's two burns, swing the apoapsis out to four target radii, raise the periapsis onto the target from out there, and bring the apoapsis back down — three burns, cheaper than the Hohmann only when the target radius is more than 11.94 times the starting one, by a percent or two, for an order of magnitude more time. That is a trade to show rather than pick, so a first-step orbit change far enough for it is compared as a pair, "Hohmann" and "Bi-elliptic". Measured for Kestrel, 300 → 50,000 km at Mars (ratio 14.5): 1,817 m/s arriving on day 14.5 against 1,819 m/s on day 0.8, and the better circle of the two. Two things that first compile taught: the burn at the far apoapsis is a large multiple of the 82 m/s orbital speed there by design and must stay one burn (split into thirteen small kicks a revolution apart, solar perturbation at a third of Mars's sphere of influence undid it), and a manoeuvre spanning a dozen days has to aim its burns against the planet's velocity now, not at the start of the course.

What a Torch buys, measured. Petasos → Mars, 5,000 km capture, at the epoch: injection 7,972 m/s on day 240, turnover 5,526 m/s at 90% of the cruise taking the arrival excess from 10,081 to 4,681 m/s, insertion 3,872 m/s — 17,487 m/s and a capture on day 574, where Efficient costs 4,639 m/s and arrives on day 1,243 and Fastest spends ~32 km/s and never captures. A true brachistochrone would need ~360 km/s on her 22.8 km/s tank, which is why the profile is that shape bounded by the tank rather than the thing itself. Three facts from the measurement shaped it: the turnover aims at the Efficient arc's arrival rather than at the flyability gate (which admits 21 km/s on her drive and would never fire, leaving a 10 km/s insertion that loses 1,500 m/s to sweeping past periapsis); it is a re-planned leg, not a pure retrograde shed (a 3.4 km/s shed at mid-cruise dropped the arc below Mars's orbit); and later is better — the same tank gets the arrival to 8.4 km/s from mid-cruise and 6.0 from 85% of it, so the solver tries several turnover points and keeps the earliest arrival that is slow enough.

The window knob is left out when the compiler is certain to decline it. Two refusals can be read off the mission's shape before anything is compiled: the Transfer is not the first step (a chained leg starts mid-cruise, with no origin to phase against), or the craft orbits the Sun (no planetary departure body). In either case the "window" candidates would be bit-identical repeats of the "soon" ones, so the set is two candidates rather than four, and the note under the table carries the compiler's own sentence — window not compiled: windowAuto ignored: no planetary departure body ('Sun') — so a short table reads as a decision rather than a fault. These two are the only duplicates predicted; the sentences are the compiler's (shared through WindowNotes), not paraphrases.

From candidate to compile

1. Borrow the draft. The candidate's knobs — only the axes the set varies — are set on the draft's step, the mission definition is emitted, and the step is put back. A candidate never owns a copy of the draft — a copy would be one more thing that could drift from the mission on screen.
2. Route by start mode. From-the-craft candidates compile from the craft's own orbit at the draft's start instant; queued and replacing candidates hand over intent only and compile from the chained state, exactly as Accept will.
3. Read the result. Δv is the sum of every burn; departure is the first burn; flight time is the last burn; the arrival orbit is quoted only when the final orbit is framed on a body and the Capture phase did not fail. A candidate that compiled but fell short anywhere is labelled best-effort, not hidden.
4. Bake it. The compilation goes through the same bake the mission store uses, so a candidate on the map and an accepted course are one geometry.
5. Fold duplicates. A candidate that flew the same flight as an earlier one — Δv within 1 m/s, departure and arrival within an hour, the same capture within a kilometre, or failed for the same reason — is folded into it. The survivor's label drops the knob that made no difference.

What that produces, measured

Most of the time the four shapes are not four flights. The duplicates are bit-identical, not merely close. Measured at the 2056 epoch with the planner's default step (window finder on, 800-day scan) and a 5,000 km capture:

Craft → target	Efficient, soon	Efficient, window	Fastest, soon	Fastest, window	Offered
Petasos → Mars starts orbiting the Sun	4,639 m/s	4,639 m/s	18,597 m/s, no capture	18,597 m/s, no capture	2: "Efficient", "Fastest"
Anabasis → Venus Earth orbit	9,102 m/s	9,678 m/s	9,102 m/s	9,678 m/s	2: "Soon", "Window"
Aether → Mars Earth orbit	5,130 m/s	4,893 m/s	32,239 m/s, no capture	23,177 m/s, no capture	4

Two things fall out of those numbers. First, the knobs are sometimes inert and sometimes not, in ways that depend on the craft and the target — which is why duplicates are folded after compiling rather than predicted, with the single exception above, where the compiler's refusal is a fact about its inputs rather than a guess about its outputs. A rule that guessed would one day hide a real option. Second, the cost of a comparison is dominated by the solver, not the count: Petasos's four compiles took 20 s (two, now that her window twins are not compiled: 10 s) and Aether's 13 s, but Anabasis's took 411 s.

How Candidates Reach the Map

A compiled mission is stored relative to its central body, in days from its start. Everything drawn is derived from that one record — the accepted courses and the candidates share the geometry, and differ only in how they are coloured.

One compiled record, three renderings. The candidates ride every path an accepted course does, which is why an option on the map looks exactly like the course it would become.

The colour language

Colour	Means
Azure	An accepted course, the part still ahead of the clock
Orange	The segment under the clock right now
Gray	Already flown
Ube	A compiled option nobody has picked. No playhead, so one colour end to end — the one deliberate exception to "colour says where the clock is"
Mantis	The option the draft holds. Drawn last, so it sits on top

Labels and clicks

Each candidate wears its Δv halfway along its trace by length — the stretch that is most clearly this option, away from the departure and arrival ends every option shares — in its own ube or mantis. A caption that would overprint another steps down a line. A click on a caption, or within 16 pixels of a trace, chooses that option exactly as its row would. On the main map this is a rung in the click ladder: below planets and ships, above accepted courses, and it leaves the selection alone, because clearing the selected ship would close the planner with it.

Potential Improvements

Grouped by what they would buy. None of these exist yet.

More, and better, options

Faster comparisons

Reading the map

Done since this list was written: the Power rung is an axis (above); the two predictable window duplicates are no longer compiled; candidates compile in parallel, each on its own private stack, with landings handed back one per frame; the note quotes the compiler's own window field rather than parsing it out of the phase's log line — the window; TCM@454. misquote is gone; the Torch profile (above) is the brachistochrone-shaped option a fusion craft can afford; and a far orbit change compares the Hohmann against the bi-elliptic.

Reach

Going Deeper

• Missions — the mission JSON and the compiler the planner drives
• UX Design — the side panel and view-model architecture the planner lives in
• Ships — the fleet the planner plans for