Planetarium

The mode with no ship. What it is for, why it is not the galaxy map, and the one rule that keeps it from becoming a second game.

---

The one idea

The planetarium is a view of the same universe, not a mode with its own rules.

Every other mode is about a ship: where it is, what it can reach, what that costs. The planetarium removes the ship entirely. There is no fuel, no heat, no Δv, nowhere you cannot go and nothing you can break. You point a camera at something and look at it.

That sounds like a sandbox and it is not. It is a reading room for the same data the game is built on — the real catalog, the real orbits, the real physical parameters — and it exists because this project has one asset no competitor has: a sky that is derived from measurements rather than painted, and which is therefore worth examining rather than merely flying through.

Space Engine is the reference, and the debt is worth stating plainly. What is different here is that the planetarium and the flight simulation are the same running world: you can leave a ship in orbit of Mars, spend ten minutes on Saturn's rings, and come back to the ship where the running simulation puts it. Equal canonical inputs produce the same state hash with or without that camera visit. There is no "load a different mode".

✅ Built. Camera — in orbit and standing on the ground — catalog with folds and class filters, orbit traces, labels, the body record, composed shots, dockable panels, touch. What is not built is listed at the bottom, along with the astronomy nothing has measured yet.

The optional guide

The Guide is a closed-by-default workspace panel: a voice picker and three controls, Start, Pause, and End. Opening the panel loads the guide; ordinary Planetarium use creates no cloud session. The ordinary scene and its controls remain available when the cloud guide is disabled.

The guide is a friendly astronomy nerd: congenial, curious, and happy to share a historical surprise. It speaks in one voice. GPT Live listens and speaks, and delegates the thinking to GPT-6 Astra, which sees the current view, holds the tool inventory, composes a tour on the spot, and paces it with the browser's clock (ADR-0042). It introduces itself by voice name and says what the visitor can ask for. There is no backstage director, no separate speech model, no authored itinerary, and no plan panel. The visitor chooses when to enable voice and sees an AI voice disclosure; microphone mute and pause are separate controls.

A tour is a series of beats, and the browser is the metronome. The backend names where it is heading, the observatory travels, and when the arrival receipt comes the backend narrates what is actually on screen and declares how long to linger; the browser waits for the words to be spoken, reading the remote audio track, and then for the quiet look, and then prompts the next stop. When the visitor asks about several things that can be shown — a planet's moons, a system's planets — the guide visits each in turn and keeps its words about the object on screen.

A question holds the current view. A changed destination supersedes pending work, and a correction spoken during a non-blocking move is delegated at once. Manual camera input takes the camera, and a late model result cannot replace the view the visitor chose. The observatory executes every movement through its existing camera controls and photographic clock; the backend may ask for several records at once but for only one move per turn, so the camera cannot thrash. Gentle finite orbits, approaches, pullbacks, and reveals continue during narration and stop when the visitor takes over or interrupts. The simulation continues according to its own inputs.

Application records supply measurements and scene truth. For observed Solar System objects, the models use their own established astronomy and historical knowledge to explain why a place is interesting. Ordinary model context is the current view, nearby subjects, available actions, and requested raw measurements; a fact reaches the backend as a raw quantity and unit, not as a cooked blurb. Projected worlds are identified as projections; missing measurements keep their reasons. The guide separates an object's properties from what this camera can currently see. It sends no screenshots or continuous video. Image-based questions and requested composition help remain deferred.

This is an explicit Planetarium exception to the game's voice direction. It explains the record without telling the visitor what to feel. The cloud service is a password-gated private alpha; provider access, listening quality, and deployed acceptance require their own verification. ADR-0041 records the execution boundary — the bounded inventory, the receipts, the revisions — and ADR-0042 the one-voice shape; hosting describes admission and operation.

---

The rule that keeps it honest

The planetarium never writes canonical state.

Not the clock, not the ship, not an entity, not a save. It moves a camera and reads. The engineering form of that rule is packages/devtools/src/observatory.ts, which produces a presentation eye and has no verb that mutates anything — and the test that guards it compares world.stateHash() before and after a session of flying around.

Two things follow, and both are load-bearing:

🎮 Designer's Note: The second one is the whole reason this rule is stated in the bible rather than left as an implementation detail. The moment the planetarium can scan, survey or bank anything, the survey game has a free mode that plays it for you.

---

The camera

Two arms, and which one holds the camera is a question with one answer: the orbit arm above 1.5 radii, the surface arm below it. They meet exactly, with no band that is both or neither.

Targeting

Orbiting and targeting are separate. The Camera panel names the body the camera orbits and lets the viewer target another body in that system. For example, orbit Earth and target Luna. The camera follows the pair's orbital plane and changes its distance with their separation, keeping both centers at their composed positions in the eye during time warp. Their rotation, illumination, and apparent sizes still change. Frame both bodies fits the pair inside the lens; drag and dolly remain available for composition.

Clearing the target preserves the camera pose. Navigating to another body or standing on a surface clears tracking. The minimum safe orbit distance takes precedence when a pair contracts enough to approach the surface. Targeting belongs to the observatory and never moves a ship or changes canonical state.

In orbit

Three numbers — azimuth, elevation, distance — around a chosen target. Not a free 6-DoF camera, and that is a decision rather than a limitation.

A free camera is what a flight mode is for. Orbiting a subject is the only model in which "look at Jupiter" has an unambiguous answer, it is what makes the mode usable with one finger on a phone, and it removes the failure every free-fly space browser has: being lost, at an unknown scale, pointed at nothing.

The keys are the defaults, and every one of them is rebindable — ux § controls. The Camera panel prints the live chord beside each control rather than a key written into a label.

Looking is an offset on the aim, and it persists until the pose is replaced. The orbit arm aims at the target's center by construction, so without an offset there is no way to look at a limb, at a moon beside a disk, or at the sky at all. A focus, a frame, Home, a composition and a picture each replace the pose and recenter the head; a drag, a dolly and leaving the mode do not — so a viewer who turned to look at Io beside Jupiter is still looking at Io after the wheel. On the ground the offset is the heading and the pitch, which the stance already holds.

Two ways in, because there are two kinds of hand. The secondary button always drags the look and suppresses the context menu on the sky and nowhere else. L and a switch make the primary drag and the arrow keys look instead, which is the only way in on a phone and with a keyboard alone.

A drag moves the picture by the pixels dragged, at any lens. The sensitivity is the lens's own pixel angle, so the ground under the pointer follows the pointer. A constant radians-per-pixel swings the frame through three of its own field-widths at 8× zoom, which is a gesture nobody can aim.

Zoom, dolly and framing are three acts, and the Camera panel has three controls. Zoom multiplies the focal length: it magnifies and changes no parallax, so the limb does not turn and the moons do not shift against the disk. A dolly moves the camera and changes all of that. Framing is a solve — the standoff that makes the subject fill a stated fraction of the frame at whatever lens is fitted, which is what F and Frame run. It solves rather than restores: nothing stores the fill a viewer dollied to, so the control is labeled for the act it performs.

One control cannot describe all three without saying something false about two of them — "the subject stays the same size" is a claim about the solve alone, and a panel that prints it under a lens slider is describing a coupling nobody can wire, because a lens change does not move a camera. ADR-0017 is the object that keeps the three apart, and ADR-0018 is the panel they are operated from.

Distance is logarithmic everywhere. The range this camera covers is from a kilometer above a moon to a hundred light years — nineteen decades. Interpolated linearly, a fly-to spends 99.9% of its time in the last decade and reads as a cut; every zoom is a multiply and every transition eases over log(distance). The same trap ADR-0010 documents for a cinematic approach, met again at a larger scale.

Zoom-out is capped absolutely, not relative to the target. A radius-relative ceiling puts Luna's at 0.003 ly and a star's at 0.3 ly, so "zoom out until the neighboring stars appear" — the single most planetarium-shaped gesture there is — would work at a star and refuse at a moon, for a reason no player could infer.

Fly-to is a move, not a cut

Selecting a new target keeps the orbit angles and moves only the distance. The camera travels; it does not teleport. Two reasons: resetting the angles on every click reads as the interface reasserting itself over the player, and the traveling is the thing worth seeing — a fly-to from Earth to Proxima that took no time would have taught nothing about four light years.

On the ground

The orbit arm stops at 1.5 radii and is right to: half a radius up is where a planetarium stops showing you a world and starts showing you ground with no horizon in it. What that clamp also costs is the ability to inspect a surface, because terrain only exists below the floor the camera cannot go under — and flying a ship at a mountain is a canonical change, a physics problem and several minutes.

So there is a second arm. Five numbers about a point on the ground — latitude, longitude, height, heading, pitch — against the orbit arm's three about a point in space. Its ceiling is half a radius, which is the orbit arm's floor, and a stance is nullable rather than a mode flag beside the orbit state, so the two cannot disagree about where the camera is.

Three of its rules are decisions rather than details:

• Height is above the ground under you, never above the datum — and it is the ground you can see. Terrain dips below the datum as often as it rises above it, so a height above the datum puts the camera underground on any peak and a kilometer up in any basin, which is the one thing a control called altitude must never do. What it stands on is drawnSurfaceRadius rather than the contact test's: the two are up to 1.25 m apart, and a two-meter stance measured against the radius a ship lands on sits 0.4 m over the plain in one place and inside a crater rim in the next. The ship keeps the other one — physics may not read a term the renderer is free to change. ADR-0021.
• The scrub is logarithmic, for the reason distance is, and worse: the band is 2 m to 3,186 km on Earth. Linearly, the approach, the low pass and the landing all live in the last pixel, so the control that exists to reach two meters would be the one control that cannot.
• The default pitch tracks the horizon, acos(r / (r + h)). From 400 km that is 19.79° below level, so a camera held level at the top of a descent is a picture of empty sky. The small-angle √(2h/r) is 2.6% wrong there and grows.

The keys fly the stance. W, A, S and D along the heading, E and Q up and down, Shift for fast — the ship's own translation letters, which is deliberate, since the two contexts are never live together. The speed is 0.8 of the height a second with a four-meter floor, the scrub's logarithm again: a run two meters up, highway speed at a hundred meters, kilometers a second at the orbit floor. The flight is a presentation motion the observatory applies in its own per-frame sample, beside the fly-to ease, so it can no more write the world than a drag can. There is no walker here; the avatar is the player's, in play, and steps out beside a landed ship. On foot.

Entering is a cut or a drop, and which one is the caller's. The site buttons cut: this arm is the instrument a plate is captured through, and an ease means every capture waits an unspecified number of frames for a filter to settle before the picture is the picture. The drop is the other intent — a figure dragged onto the world, and eight seconds of ballistic entry down to where it lands, ending level with the horizon and facing the star. Two verbs, because arriving somewhere and photographing it are two acts. ADR-0034.

Where you can stand is found, not authored. A seeded world has no place names, and typing coordinates into a sphere lands on the same undifferentiated mid-slope every time. A beam search over the body's own field finds four — the highest ground, the lowest, where the land crosses the sea, and the steepest — and two more are chosen for the renderer rather than for the geology: the corner where three faces of the addressing cube meet, and the pole, where the east/north basis is singular. A survey of interesting ground would never wander into either. Because they are derived, "the highest ground on this world" is still the interesting place after the generator changes, and a latitude written down last month is not.

A launch from the pointer chooses a landing site. Dragging the figure holds one end of a spring rope under the pointer. An upward and inward launch curves toward the world under gravity; its contact chooses the surface marker. The rope flexes as the hand moves, while both endpoints remain pinned. Releasing lands the camera at that marker. Aiming outside the disk keeps the held end visible beside the world, where the curve is easiest to read.

Orbit traces and labels recede during the gesture and descent, then return. The control names the release action while aiming, reports height and progress during descent, and offers a return to orbit. Pointer cancellation and lost capture leave the camera in orbit. Reduced motion shows the equilibrium curve and shortens the camera transition. ADR-0036 records the aiming model and its limits.

---

The tools

Everything is a panel, and every panel is dockable — see ux.

The split between Camera and View is by what a control changes. A layer changes pixels the scene does not own — names, traces, the ship — and the camera changes the picture itself. That is also why glare is a lens channel and not a layer: what an aperture does to a bright source is a property of the instrument, and at zero it is the sky with no optics in front of it.

The camera's own readings — range, altitude, how much of the frame the subject fills, the two orbit angles — are not in the object panel. They are facts about where you are standing rather than about the thing being looked at, and on a page about Mars they read as a debugger. They are on the Camera panel, beside the lens they describe.

The two arms are two sections of one panel, not two panels. The camera is in exactly one of them at a time, so a panel per arm is a panel that is entirely disabled whenever the camera is in the other — nine dead controls under a heading reading "in orbit". Descending is a camera act either way: Orbit carries the pose above the floor, Ground carries the sites, the descent and the heading below it, and only one of the two is drawn.

The navigator

Sol is a hundred and twenty-nine bodies, and a flat list of them in issue order is not something anybody browses twice. Three controls, and each answers a question a list cannot.

The list is windowed: only the rows in the scroll viewport exist, and the rest is a tall empty box the scrollbar measures. At fifty light years the survey answers with fourteen hundred systems, and reconciling every one of them against a fresh array twice a second — beside the render loop — was the stutter. The derivations were never the cost; React was.

The folds. One line per system, expanded where the camera is. The default is re-derived from the target on every render rather than stored — a set of open addresses freezes it, so flying to Proxima would leave Sol as the expanded one. What is stored is the set of systems the reader has changed.

The classes. Six chips: stars, planets, moons, dwarfs, asteroids, comets. Turning off the rubble is the single most useful press in the panel. An empty selection means everything, because a filter whose worst state is an empty list that looks exactly like a failed survey is a control with a trap in it. A star whose own class is off stays when something under it survived, and a moon stays when its planet was the thing removed — and a promoted moon sorts by where its parent was, or nine rocks orbiting at a kilometer appear above Mercury.

The radius. 5, 10, 25 or 50 light years. A search ignores it and reaches the whole index, because "what is near me" and "what is called this" are different questions and only one of them can run per keystroke.

And the search ranks rather than filters. The catalog's own index is exact, then prefix, then substring over normalized keys, which is right for an address and short of what a search box owes a person: proxmia found nothing, centauri alpha found nothing, and europa found nothing because the index is stars. The navigator matches over every designation the catalog holds and every body the world has generated, tolerating one error per term and any word order, and it lights the characters that matched so a reader can see why a row answered. A typed address still resolves first.

The neighborhood rail is the part a list cannot be. Proxima at 4.24 ly and Sirius at 8.6 ly are two rows differing by a numeral and the factor of two never lands; on a scale it lands in 28 px. The dots are real stars at real distances in their real colors — art puts a star's color on the list of things this game may not invent — and clicking one flies the camera there. The scale is √r: a survey's volume grows as r³, so linearly the whole neighborhood piles into the left tenth, and logarithmically the observer's own zero has nowhere to go.

The catalog dialog

The navigator answers "where is the thing I can name". The catalog answers the other question a reading room exists for — what is out there like this — and it is not a lookup at all.

There is nothing to index. A system is a pure function of its seed, which is what makes the universe streamable without storing generated systems, and it means the only way to know whether a star has a world with a sea is to build the system and look. So the search is a sweep: every system inside the radius is generated and tested, on the worker pool, and the rows arrive while it is still running.

Every clause reads a field the record already carries — the host's spectral class, the body's class, its air, its sea, its rings, its habitable zone, its landability, its moons. Nothing is a tag invented for searching, so a result is a claim about the world the generator makes rather than about a label somebody attached to it. "Sea" rather than "water", because the generator's answer is whether the ground temperature admits a liquid, and on a cold world that liquid is methane.

The five yes/no clauses are three-state. A switch cannot say the difference between "I do not care whether it has air" and "I want the ones with none", and both are searches somebody runs — the airless worlds are where the sharp horizons are.

It is a dialog rather than a panel because it takes seconds rather than keystrokes, and a panel that took four seconds inside a dock column would look broken. The count says how far along it is against how many systems there are, there is a Stop, and the nearest thousand are kept with the rest counted: "rocky, within 150 light years" is 37,929 systems and over a hundred thousand bodies, and a list is not a place to put them. ADR-0035.

Presets

The dock offers three quick shots and opens the full library at /planetarium/presets. This is a child route: the planetarium, camera, and photographic clock stay mounted beneath it. The dialog has Included, Saved, and Current view tabs. Composition tools and galaxy views are collapsed in the dock until requested.

Current view captures the camera, orbit anchor, target, photographic time, full lens and camera processing when the tab opens. Name and save it, copy its JSON, copy a link, or download its file. Recapture refreshes the shot from the view behind the dialog. Saved holds rename, replace, share, delete, and undo controls. It accepts a JSON file or pasted JSON and exports saved shots or the combined library.

Included shots use the same validated JSON format as personal shots. Each has a thumbnail captured through the renderer. Selecting a built-in writes /planetarium?preset=earthrise, with that shot's ID. A custom link starts with shot=2 and flattens the picture into named query parameters: seed, label, address, time, framing.state.azimuth, lens.zoom, processing.mode, and the remaining fields. Version 1 links retain their legacy Enhanced defaults. Text is ordinary URL-escaped text; numbers keep their full precision. Adding save=1 opens the restored view with the save dialog and a suggested name. Opening a link never saves to the library automatically.

Presets contain no cinematic scripts. Enterprise portraits belong to Cinema. Layers remain the viewer's choice. Saved shots stay in this browser until exported or shared.

The Time panel's Set date editor accepts UTC; Now selects the current date and time. Both hold that instant independently of the ship simulation. A preset opens paused at its saved time. Play, warp, and keyboard commands advance the photographic clock. Reset returns to the simulation clock. The local readout, UTC editor, camera anchor, body positions, surface, orbit traces, and Object panel describe the same instant.

The format and time boundary are specified in ADR-0033.

Names

A label is the difference between "a bright dot" and "Sirius", and it is the single feature that turns a rendered starfield into a planetarium. Drawn in the DOM over the tone-mapped frame, thinned greedily so a system seen from outside is a sky rather than a list, and the leader ends on the body's limb so a name never covers the thing it names.

A label layer is not a boolean. Eighteen names is right for a system and wrong for a planet with two moons, so the density is a three-step — 8, 18, 40 — rather than a constant or a slider. And the thinning is greedy by screen size, which means from far enough out Sol's ninety-two asteroids and comets are the same handful of pixels as Mercury and take the slots in whatever order the scene lists them: a sky captioned with six provisional designations and no planets. Minor bodies are therefore a switch of their own. A dwarf planet is not in that class, for the same reason its orbit is drawn.

Names behind a solid body are removed before decluttering and picking. The visibility test follows the camera-to-body ray in physical coordinates, so radius-dependent render compression cannot bring a hidden moon's name in front of its planet. A candidate never occludes its own name.

Orbit traces

Affordable here for a reason specific to this engine: orbits are analytic (ADR-0006), so a whole period is 96 closed-form evaluations rather than 96 integration steps that would drift off the body they belong to.

Four rules, every one of which the naive version gets wrong in a way that only shows on screen:

• A trace is relative to its primary, re-anchored to now. Sampling a moon's absolute position over one of its months also sweeps the planet through a twelfth of its year, so the trace comes out as an open corkscrew.
• A trace starts where the body is. It is drawn as a tail behind the subject, and a curve that is geometrically right but phase-shifted is invisible until somebody looks at the tail.
• Traces are contextual, and rubble is not context. What is drawn is the subject's siblings and the things going round it. Everything at once, in a system seen from inside, is a dozen ellipses edge-on — a fan of near-straight lines that says nothing. That was written when a star's children were eight planets; Sol has sixty-seven now, and drawn all at once they are a hundred and twenty-nine lines with the subject somewhere behind them. So an asteroid, a comet or a dwarf planet's orbit is drawn when it is the subject or goes round it, and the planets stay — "where is this relative to the planets" is the question a planetarium exists to answer, and eight ellipses answer it. Scope: all is the deliberate way to ask for the cage — from outside a system it is the picture, the whole architecture of the place at once, and from inside it is a fan of edge-on lines. Which is why it is a switch a reader throws rather than the default, and why it is a field on the presentation stance rather than component state: the frame loop reads it.
• Sample in eccentric anomaly, not in time. By Kepler's second law a near-parabolic body spends nearly all of its period near aphelion, so equal steps in time put nearly all the samples in the same place. At e = 0 the two are identical and nobody notices; C/2020 F3 (NEOWISE) is 0.99913, and its ninety-six samples were sixty-nine years apart with the two bracketing perihelion at 38 AU on opposite sides. The trace was a flat-ended lens through the middle of the Sun, and whenever the comet was near perihelion it was nowhere near its own orbit line. M = E − e·sin E is Kepler's equation run forwards and needs no solver; the same ninety-six points then walk the ellipse at nearly constant arc length.

The sampled points define an analytic ellipse. Visible arcs are subdivided against a quarter-pixel chord target, with a fixed 4,096-segment budget, while arcs outside the viewport are culled. The buffer is reused while the curve and solid silhouettes each move less than 0.05 pixels. This keeps a wide view cheap and a close view smooth without another period of Kepler evaluations.

Solid bodies clip the traces at their silhouettes and surfaces before the remaining directions reach the GPU. Foreground transits stay visible. The same ellipsoids hide labels, including axial tilt and polar flattening; measured axes approximate irregular silhouettes. This avoids relying on compressed depth to order objects of different radii.

The light, in the photographer's terms

Full, gibbous, half, crescent, rim — the same vocabulary the flight harness's camera bookmarks use, over the same solver, so the two cannot disagree about what "gibbous" means. Each is solved against where the star actually is now, so a phase means the same thing at any point in a planet's year.

---

Mobile

The planetarium is the mode that works on a phone, and the first one that does.

Piloting on a touchscreen is a design problem this project has not solved and should not pretend to. Looking is not: one finger orbits, two pinch, a tap focuses, and the panels become a bottom sheet with a tab strip. Every panel is reachable; no panel is exclusive to the desktop.

Docking is deliberately not offered on a phone. "Left" and "right" have no meaning on a 390 px screen, so a drag that moved a panel between zones would be a gesture with an invisible effect — worse than no gesture. The panel set is still the same stored layout, so a workspace arranged on a desktop and opened on a phone keeps its panels and rotating a tablet back restores the columns.

The presets carry the weight on touch. A phone has one finger and no keyboard, so a picture or a composition is the only way to reach a framing that would otherwise take a drag, a pinch and a phase solve — and a thumbnail is the only way to say which framing it is without a caption a phone has no room for. L and the Camera panel's switch are the same rule one level down: with no secondary button, making the drag look has to be a control.

---

The URL is the document

/planetarium?at=g:milky-way/s:SOL/b:5 opens on Jupiter. The address bar is rewritten on every focus, so it always describes what is on screen, and that makes a view a thing you can send someone.

The address is the same string generation, saves, logs and the console all use (ADR-0004) — there is no second identifier for "a place in the planetarium". The search box accepts everything ir.goTo accepts, through the same resolver, because a search box with its own vocabulary would be a second addressing scheme in one build.

---

What this is not

It is not the galaxy map. The galaxy map is a gameplay instrument on the canopy: route planning, jump range, fuel, filters about your survey status, and a horizon of knowledge. It answers "where can I get to and what will it cost". The planetarium answers "what is out there and what does it look like", has no route planner and no notion of range, and is not drawn on any surface inside the ship because there is no ship.

They will share a catalog index and nothing else.

It is not photo mode. Photo mode is entered from the Canopy console during play, keeps the ship, and exports an image stamped with the address. The planetarium has no ship to be in.

---

Not built

Filters over the catalog are ✅ built — by class and by survey radius in the navigator, and by what a world is in the catalog dialog. What is not built is the half of galaxy's set that is about the player's own survey, and that half is deliberately absent: looking at Vega is not going there, and a mode with no ship has nothing to filter by.

---

The record that is not filled in yet

The object panel draws a row for every field a planetarium is expected to carry, including the ones nothing has measured — muted, marked no data, with the reason attached. ADR-0014 is the argument for that; this is the list, and the engineering half of each reason.

The panel's copy is written in the universe's voice — "no magnetometer has been flown through it", never "the generator does not produce one". The galaxy is real, projected means the ship's computer worked a world out from its star's parameters rather than anybody having flown there (galaxy), and a mode whose whole subject is that the sky is not a program may not tell a reader that it is. A test greps every reason for the vocabulary that would break it.

On a body

On a star

Every one of these is a row on screen today. Filling one in is a two-line diff — the label and its place in the group do not move — and pendingCount in the panel's header is the count going down. There is no separate ledger to keep in step; this table is about sources, and the rows themselves are generated by the code that draws them.

---

Related

• modes — where this sits among solo, online and the persistent universe
• ux — the shell, the routes and dockable panels
• galaxy — the two in-game maps this is deliberately not
• cinema — the other mode with no ship
• ADR-0011 — routes, modes and who owns the camera
• ADR-0014 — why an unmeasured field is a row rather than an omission