Star System Explorer
A procedural generator for scientifically-plausible star systems, with a real-time orbital
visualiser, a multi-system starmap, and a full astrodynamics engine for flying your own spacecraft —
efficient transfers or hard burns, with fuel, time, relativity and hazard all accounted for. Built
for science-fiction tabletop RPGs, and for anyone who marvels at how the real physics fits together.
Join the Discord for discussion, feedback, bugs and suggestions.
There is a tutorial video as well, but it is well out of date:
the ideas still hold and almost every screen in it has changed since. Read
GettingStarted.md for the current account.
Table of Contents
What is it for?
This tool was built to enhance science-fiction tabletop role-playing games. It isn't a perfect
simulation — it aims to be "close enough" for an RPG, while leaning on real astronomy and exoplanet
science wherever it can, so the worlds it produces feel like places rather than stat blocks. Crank
the sliders and it will still try to keep you on the plausibility rails; open the Newton panel on
any body and it will show you its full working.
It has been "vibe-coded" over many months across several AI coding assistants — every new model has
moved it forward. The physics, however, is calibrated against the real solar system: Sol is the
oracle the engine is regression-tested against.
A note on your data. The application runs in your browser and your campaigns are stored only in
your local browser storage — nothing about a campaign is sent to a server, and to move your work to
another browser or device you download the file. Three things do leave the machine, and it is worth
saying so plainly: searching for a star by name queries the SIMBAD service live, a Traveller
subsector import fetches from travellermap.com (both carry what you typed, not your campaign), and
the hosted site records one anonymous visit event per browser per day through Vercel Web Analytics,
keeping a single timestamp in your browser under sse-analytics-last-sent so it does not count you
more often than that. Player views connect peer-to-peer between your device and your players'.
What's new in V3.1
Everything you already do still works and your saved starmaps still load. V3.1 is about scale:
bigger structures, bigger views, and a place to share it all.
Megastructures. Space elevators, planetary toruses and orbital rings, ringworlds, Dyson spheres
and swarms, massive energy collectors and a battle station — seven types, placed like any other
object from the Megastructures tab on Add Construct, drawn to scale in 2D and 3D, and obeying the
physics rather than sitting on top of it. A swarm dims its star and every world's temperature
follows; the habitable zone and the frost lines move with the light. Each type's own dials — coverage,
density, where the tether's counterweight rides — move the numbers as you drag them. A hard
requirement greys a row and says why; an amber note advises and never refuses.
Docking. Ships dock at an elevator's stations at low, middle and geostationary height, on a ring's
rim or on a hull, and ride round with the structure from then on. The planner prices the approach —
nothing at the geostationary dock, several km/s at the low levels, over a thousand on a Niven ring's
rim — and turns a wrong-way arrival around, charging for it in the plan rather than hiding it. Every
screen agrees on where a docked ship is, because it is worked out once in the engine.
The Explorers site. Share a map at explorers.starsystemx.com,
browse other people's, and open a shared map here in one click with no download and no import step.
Copy any star, system, planet or ship from a map page and paste it into your campaign — with the
cartographer credited automatically, in your campaign and in the attributions file inside your saves,
and the whole chain named if it has passed through several hands.
Cut, copy and paste, anywhere. Right-click any world, moon, station or ship for Copy, Cut and
Paste. It moves the whole branch, it works between systems and between tabs, and undo treats a paste
as one step.
Size comparison. Every object on your map at true relative size, side by side, ordered by size,
mass, name or orbit — rings drawn to their real extent and at the planet's own tilt, black holes
showing their event horizon and bending what is behind them, and anything too small to draw honestly
shown as a dot with its real size rather than puffed up. Click anything to centre it. It is a player
view too, on both the system and the starmap.
Binaries that behave. A pair orbits its shared centre properly — opposite sides at every instant,
one period, split by mass — a binary imported from a file arrives as two stars, a body can be moved
to a new host by hand without jumping, and the Lagrange points are real places ships can hold at and
leave from.
Stars named properly. A star catalogued in metallic-line (Am) notation classifies from its
hydrogen lines instead of leaking the raw string as a class of its own, and a star that jets or sheds
a shell now shows it inside its own system in the 3D views rather than only on the map. A photosphere
burns white at its centre and keeps its colour at the limb, as a real one does.
Break physics on purpose. An Overrides tab lets you set what the physics would not, and labels it
as an anomaly rather than pretending.
Time on a real footing. The calendars are tied to one anchor — a genuine stake in the sand — so
they agree with each other and with a real date, instead of each carrying its own correction.
Magnetic fields you can see. A world's magnetosphere is drawn from its own physics — on the flat
system map as a GM view option, and in 3D as a player-view setting (off by default, and among
the things Low Power turns off). Two shades, and they mean different things: the shaded part is the
region that actually shields an atmosphere, the pale wash is the full extent with its downwind tail.
The size is a real pressure balance of the field against the stellar wind, so Mercury's stands a
couple of radii off and Jupiter's dwarfs everything — and the aurora oval follows from the same
number, sitting near a world's pole exactly when its bubble is large. A world with no field draws
nothing, which is the point of looking.
A sky that is right. The constellation sky is no longer drawn mirror-imaged: a star entered at its
real right ascension and declination now sits where a photograph puts it. The 2D system map zooms out
fifty times further than it did, so a distant binary companion fits on screen. And hovering a star on
the starmap summarises what is in the system without your opening it.
Quieter machinery. A memory gauge in the rail with an automatic crash save, a transit left running
no longer filling memory, a low-power switch that turns down the two things that actually cost
frames, a view that stops redrawing frames nothing could have changed, interface skins including a
light one and an amber-phosphor terminal, floating controls that remember where you put them and can
be docked together, a construct you export importing back, a liquid you invent reaching the gas
editor, and the phone layout given a proper audit.
What's new in V3
V3 is a ground-up rebuild of what a world is and of what your table sees. The headlines:
Player views — the companion app, built in. SSE serves its data live to your players' own
devices. You design what they see as a preset — text list, document, 2D map or the full 3D
system — and dress it with fonts, colours, filters, transitions and your own letterhead. Six presets
ship with it: The Guide (hopelessly colourful, DON'T PANIC), a clean Datapad, a ship's
Console, a green-phosphor CRT Terminal, a 3D Holo Table, and an overhead Projection that
follows the GM's camera and can be dropped onto a greenscreen for OBS. Everything obeys the same
redaction rules as the printed reports, and it updates live as you play. It replaces the old Field
Guide and Projector Mode outright.
A rewritten physics engine. What a world is made of decides everything else: density,
temperature, atmosphere and cloud decks, oceans and ice, magnetism, geology, the radiation it throws
out and the colour you actually see. Interiors are a metal/rock/carbon/ice/gas makeup that density
falls out of; liquids layer as subsurface oceans, surface seas and cloud decks; albedo is derived and
feeds back into the greenhouse; magnetic strength and geometry come from a conductive-layers dynamo
model. The Newton panel shows the working at every step.
The light that reaches the ground. A star's spectrum is filtered by the air and the cloud decks
above it, so what lands on the surface is not what left the star. That light sets the colour of the
land, the sea and the sky, and decides what colour plants would be to grow under it. The physics
pages draw the curve rather than describing it.
Stand on the surface. Every world has a Surface view: its own ground, sky and light as you
would find them standing on it. A red dwarf's noon does not look like ours — and it answers how far
your players can see, and how far a lamp carries, in metres rather than in adjectives.
Life is a tag too. What lives on a world — microbes, fungi, plants, animals, or something that
builds cities — is described the same way everything else is, and it shows on the planet: vegetation
spreads inland from the coast, in a colour worked out from the light that actually reaches it.
Stars properly classified. A star's type is read from its position — the letter and number
from its temperature, the luminosity class from its size at that temperature — rather than from how
bright it looks, so a supergiant is a supergiant and not a dwarf that happens to share its colour.
Antares imports as the red supergiant it is. Every type is named in plain words with a famous
example, luminosity and ionising output are kept apart because they are different things, and a star
whose numbers break physics is kept and labelled rather than refused.
Import the real sky. Build a starmap straight from the astronomy catalogues: the real stars near
you at their true three-dimensional positions, with their confirmed planets — every star in the
region, not only the planet hosts — and, if you want them, plausible worlds filled in around the
rest, tagged so you can always tell what is real. The two bundled starmaps are built this way.
Starmaps have depth, and stars look like stars. Systems carry a z-axis, so distances are true in
three dimensions; if you prefer a flat map, everything still works exactly as it did in 2D. Stars are
drawn sharp and true to class, with jets, flares and size by luminosity, and grouped systems hold
together at every zoom. Behind them you can pin your own map — a sector map or your empire's
borders — so it holds its place against the stars as you pan and zoom.
Everything is a tag. One tagging system throughout: the physics emits tags, you add your own,
override the ones you disagree with, and choose which reach your players. (V2's separate Points of
Interest and Constructs of Interest are gone; everything they did is a tag with a category.)
3D ships. Constructs can carry a real hull — upload a GLB, STL or OBJ, or use one of the six
public-domain NASA craft that ship with the app — shown as a turntable in the info block and as a
real craft on the 3D map, with a drive plume scaled to how hard it is burning.
Undo and redo. Every step is named, the last twenty survive a reload, and none of it leaves the
room in a shared map.
A fresh face for the GM view. Six interface skins (including a colour-blind-friendly one and a light one) and a
skin editor to make your own; click any unit to swap it, and every reading of that kind on that body
type follows, with your players inheriting your choice.
Bring your worlds in. Traveller, Universe Sandbox and SpaceEngine imports, unified onto one
generator, with the same four flavour dials filling out every system.
Plus the long tail: eclipse times on every moon, weather and lightning, aurorae, stellar flares and
the dose they deliver, a Memory panel and a diagnostic bundle for when something goes wrong, and
several hundred smaller changes. See the changelog for every one, build by build,
and GettingStarted.md for how to use them.
Features
- Procedural and hand generation. Grow a system from a calibrated HR-diagram star pick, with four
dials — metallicity, disc mass, dynamical history and rarity — each carrying a green/amber/red
band saying how unusual that setting is without ever forbidding it. Or place bodies anywhere by
hand: new planets bind to the dominant gravitational influence under your cursor, and the picker
offers the types that are actually viable at that orbit, with every gate a switch you can turn off.
- Starmap. A pan-and-zoom map of many systems in three dimensions, with two bundled examples
built from real astronomy, proper binary and trinary hierarchies, square/hex/subsector/Traveller
grids, snap-to-grid, your own image pinned behind the stars, independent Display/Actual time
controls, and data-driven editable calendars.
- Real-sky import. Four region presets or a centre and radius of your choosing, drawn from the
NASA Exoplanet Archive and SIMBAD, into a new map or into one you already have.
- Traveller integration. Import whole subsectors from travellermap.com,
or enter systems by UWP; a dedicated UWP block shows population, starport and political data.
Traveller mode (Settings → Starmap) aligns everything to hexes. Companion stars are placed by
the same planner the generator uses, because the sector format carries no companion orbits.
- Import from Universe Sandbox and SpaceEngine. Drop a
.ubox save or a .sc export into the
New system wizard and it converts into a playable system — bodies, orbits, composition and
atmospheres come across, and SSE derives the rest of the physics. A mass slider controls how many
small bodies to bring in, and an Import Review shows anything SSE derived differently from the
source, with one-click copy.
- Constructs and infrastructure. Place ships and stations anywhere — low orbit to deep space to a
planetary surface — each with tracked mass, crew, power, fuel, engines, cargo and sensors, and
optionally a real 3D hull. A rich template library ships (hard sci-fi outposts, The Expanse,
Aliens, Mothership); load, refit and save your own.
- Transit and interstellar planner. Lambert-solver transfers for local hops and system-wide
journeys, plus interstellar travel with Realistic, Massless, Relativistic and Jump models. Journeys
schedule against Display Time and execute as time advances; intercepts target live in-transit
position and velocity; a stress graph flags G-forces and radiation.
- Autopilot. Standing orders for NPC ships — Mine / Transport / Patrol / Explore / Escort — with
per-ship character, smart tag-driven routing, self-refuelling, and a full Ship's Log. See the
in-app .
Integrating with a virtual tabletop
SSE can appear inside another application as a live, redacted view of your campaign. This is early,
and this section describes what exists rather than what is planned.
Mappadux — free, and built alongside this — works today: your starmap
and systems appear on the table, live, as a StarMap map kind.
Two hosted routes make that possible, and a host app that wants to do the same uses them:
/bridge is a hidden discovery frame. A host app embeds it, and it asks the GM's SSE tab in
the same browser "who is here", relaying the answer to its parent over postMessage. Frames carry
{ns: 'sse2-bridge', v: 1}; the parent sends hello and ensureRemote, and the bridge answers
ready, announce, gone, ok or error — and forwards unsolicited announces, which is how a
host's "open SSE, then auto-resume" flow completes. It is read and relay only. It exposes the
starmap's identity and its player-view names — what anyone holding the session id could learn
anyway — and can ask the GM tab to start hosting. It cannot read the campaign and cannot change
anything.?embed=1 on a player view strips the surrounding chrome so the view sits cleanly in a frame,
and accepts {ns: 'sse2-embed', v: 1} commands from its parent — ping, and setPreset to switch
between presets on one warm iframe without a reload.
Underneath, discovery uses the same broadcast plumbing the player views do: REQUEST_HELLO,
ANNOUNCE, REQUEST_REMOTE and SYNC_HEARTBEAT. Two things are worth knowing before you build
against it. Parent origins are allowlisted exactly (src/lib/embedOrigins.ts) — Mappadux's
domains plus localhost for development — so a new host app has to be added there before it can drive
an embedded surface; a wildcard would hand a discovery surface to any page that framed us. And
BroadcastChannel is partitioned inside a third-party iframe by top-level site, so a cross-site
host cannot hear the SSE tab over it and must discover over PeerJS with a known session id, with the
first pairing always a pasted player link. Local development never shows this, because two localhost
ports are one site.
Foundry VTT and Owlbear Rodeo shims are wanted and not written. If you run either, come and say so on
the Discord — the design notes live in docs/dev/vtt-integration-design.md.
Players see one change from all of this: the LIVE/OFFLINE pill on a player view goes OFFLINE when the
GM stops sharing, where it used to stick.
Reading a save, and knowing what came with the app
Two things exist for a program that opens a .sse.zip without running SSE.
bundleFormat is an integer, the first line of starmap.json/system.json inside the archive.
It says which layout the file uses, so a reader can parse it or refuse politely. It is not the
app version and does not move when the app does — only when the archive's layout changes. Two
canonical archives are checked in at tests/fixtures/creator-hub-*.sse.zip and pinned byte for byte,
so a parser can be tested against real saves rather than against a description of one.
/shipped-content.json is what the app publishes about itself: its calendars, tag categories,
star and planet pictures, starter spacecraft models, and its gases, liquids and fuels. It exists so a
consumer can tell what came with the app from what a creator made themselves, without keeping its own
copy of those lists and slowly getting them wrong. It is rebuilt from the real files on every release
and the test suite refuses to pass if it has gone stale — which means anyone bumping the version
here must run npm run manifest after the bump, before the build.
Usage
Generating a system
- On first load, create a new starmap, load one of the bundled examples, or import a region of the
real sky.
- To grow a system, right-click empty space and choose Add System Here: pick your star or stars
on the HR diagram, then set the age and the four character dials.
Interacting with the starmap
- Pan/zoom with drag and wheel (pinch on touch); Reset View fits all systems.
- Add System — right-click empty space. Add System near here… — right-click a system, to
place one by bearing, elevation and distance.
- View System — click a star. Link Systems — right-click a star, choose Start Link, then
click another.
- Grid — Settings → Starmap → Snap grid: None, Square, Hex, Subsector hex or Traveller hex.
Traveller tools
- Enable Traveller mode under Settings → Starmap to align the map to hexes.
- Bulk import — right-click the background, choose Add Traveller Map SubSector Here, search a
sector (e.g. "Spinward Marches") and pick a subsector.
- Manual UWP — right-click a hex, choose Add Traveller UWP Here, and enter the UWP (e.g.
A788899-C).
AI descriptions
You can usually enable this for free: sign up at OpenRouter, create an API
key, and pick a free model.
- Settings → System → LLM Settings — paste your OpenRouter key and choose a model (free models
are listed first).
- Select a body → Description & Notes → Expand with AI → set notes, style, tags and length →
Generate → Accept & Close.
Saving and loading
- Everything autosaves to this browser. Use File → Download / Upload on the starmap, or the
system view's File menu for individual systems. Saving to a file is the only real backup.
- Export a Player-Safe version to share a spoiler-free copy.
Getting Started
For users
Open https://starsystemx.com/ — the live app. For the newest features ahead of release there is a
beta channel at https://beta.starsystemx.com/; while it is in active development there is no
guarantee beta saves stay forward-compatible. A full walkthrough lives in
GettingStarted.md.
For developers
npm install # install dependencies
npm run dev # dev server at http://localhost:5173
Architecture and design notes for contributors live under docs/dev/; the physics
reference is in-app at /physics, and the tag model is in
docs/tags-guide.md and
docs/classification-and-tags.md.
How this project is run
SSE is developed by one person coordinating a dozen parallel AI coding sessions, and the
scaffolding that keeps that sane is in the open: docs/process-templates/
holds the playbook, the shared-board template and the session-start prompts. It grew out of
necessity as the codebase did - V2 got hairy in the rush, and this is what brought it back under
control for V3. Every rule in it was paid for by a real incident. Take it, adapt it.
Building
npm run build # production build
npm run preview # preview the production build
Changelog
For the full release history and version notes, see changelog.md.
Attributions
This project is a collaborative effort of scientific research, community creativity, and open-source
assets.
Special Thanks & Community
- Community Systems: Huge thanks to @Athena, @Mafro & @malize from the SSE Discord for
contributing example star systems.
- Accrete.js: A special thanks to Mitch Anderson for permission
to use his Accrete.js code. The experimental
accretion generator it powered has moved out of this app and into a project of its own,
System Lab, where it can grow at its own pace.
- Scientific Lineage: That work was in turn built on the foundational work of: Stephen H. Dole,
Carl Sagan, Richard Isaacson,
Martyn Fogg,
Matt Burdick, Jim Burrows &
Ian Burrell.
Astronomy Data
- NASA Exoplanet Archive, operated by the California Institute of Technology under contract with
NASA under the Exoplanet Exploration Program — the confirmed-planet set behind the real-sky import
and the bundled starmaps. A snapshot ships with the app.
- SIMBAD, operated at CDS, Strasbourg, France — star
identification and astrometry; star-name resolution queries it live.
- S-star orbital elements: Gillessen et al. 2017, refined by the GRAVITY Collaboration.
Visual & Media Credits
These three lists must agree, and two of them had already drifted apart. The canonical one is
now src/lib/io/shippedCredits.ts, which the ATTRIBUTIONS.md written into every save reads — that
is the copy that has to be right, because it is the one that leaves the machine with the work. The
About panel in the app and the list below are the other two; four entries were missing here and have
been restored. If you add or replace a shipped asset, change the table and check all three.
License
This project is licensed under the GNU General Public License v3.0.
