6.5 KiB
Systems
This document describes the shared/data/systems.json schema and the units used throughout.
Overview
Each entry in systems.json defines a solar system in the galaxy. Systems are loaded by the backend and used to build the simulation world. The galaxy position, star properties, planet orbits, asteroid fields, and resource nodes are all authored here.
Top-Level Fields
| Field | Type | Unit | Description |
|---|---|---|---|
id |
string | — | Unique identifier, referenced by scenario, factions, routes |
label |
string | — | Display name |
position |
[x, y, z] |
light-years (ly) | Position in the galaxy map. Used directly for inter-system distances and FTL transit time. Sol is at [18.2, 0.02, -11.8] ly, Helios at [0, 0, 0]. |
stars |
array | — | One entry per star. Single-star systems have one element; binary systems have two. See stars section below. |
stars
Each star is an explicit object. Single-star systems have one entry; binary systems have two. Binary stars orbit the barycenter using the same orbital fields as planets.
| Field | Type | Unit | Description |
|---|---|---|---|
kind |
string | — | Classification: "main-sequence", "blue-white", "white-dwarf", "brown-dwarf", "neutron-star" |
color |
string | — | Hex color of the star body |
glow |
string | — | Hex color of the star's halo/corona |
size |
float | km | Radius of the star. Sol = 696,340 km |
orbitRadius |
float | km | Distance from system barycenter. 0 for single stars or the primary in a simple system. |
orbitSpeed |
float | rad/s | Angular velocity around barycenter. 0 for static stars. |
orbitPhaseAtEpoch |
float | degrees | Starting angle. |
asteroidField
Defines the decorative asteroid belt for the system.
| Field | Type | Unit | Description |
|---|---|---|---|
decorationCount |
int | — | Number of decorative asteroid meshes to scatter |
radiusOffset |
float | km | Base orbit radius of the belt from the system center |
radiusVariance |
float | km | Random spread around radiusOffset |
heightVariance |
float | km | Vertical (Y-axis) spread of the belt |
Sol's belt (422,000,000 km base) maps to the real asteroid belt between Mars and Jupiter. Helios and Perseus use much smaller values since their orbits are scaled differently.
resourceNodes
Each node is a mineable location in the system.
| Field | Type | Unit | Description |
|---|---|---|---|
sourceKind |
string | — | Type of node. e.g. "asteroid-belt" |
angle |
float | radians | Angular position in the orbit around the anchor |
radiusOffset |
float | km | Orbit radius around the anchor celestial |
inclinationDegrees |
float | degrees | Orbital inclination of the node's orbit |
anchorPlanetIndex |
int? | — | 0-based index into planets array. If absent, anchored to the system center |
oreAmount |
float | — | Starting ore amount in the node |
itemId |
string | — | Item ID of the mined resource |
shardCount |
int | — | Number of individual shards the node splits into |
planets
Planets are defined with real Keplerian orbital elements. All angular values use the same epoch for consistency.
| Field | Type | Unit | Description |
|---|---|---|---|
label |
string | — | Display name |
planetType |
string | — | Classification: "terrestrial", "desert", "barren", "gas-giant", "ice-giant" |
shape |
string | — | Mesh hint: "sphere" or "oblate" |
moons |
array | — | Explicit moon definitions. See moons section below. |
orbitRadius |
float | AU | Semi-major axis in Astronomical Units. Converted to km at runtime using 1 AU = 149,597,870.7 km |
orbitSpeed |
float | rad/s (orbital sim seconds) | Angular velocity. Earth = 0.11 rad/s. Derived from Kepler's third law: 0.11 / sqrt(r³) where r is in AU |
orbitEccentricity |
float | — | Orbital eccentricity (0 = circular) |
orbitInclination |
float | degrees | Inclination relative to the ecliptic plane. Converted to radians at runtime |
orbitLongitudeOfAscendingNode |
float | degrees | Longitude of the ascending node (Ω). Converted to radians at runtime |
orbitArgumentOfPeriapsis |
float | degrees | Argument of periapsis (ω). Converted to radians at runtime |
orbitPhaseAtEpoch |
float | degrees | Mean anomaly at epoch (initial angular position). Converted to radians at runtime |
size |
float | km | Radius of the planet. Earth = 6,371 km, Jupiter = 69,911 km |
color |
string | — | Hex color |
tilt |
float | radians | Axial tilt |
hasRing |
bool | — | Whether to render a ring system |
moons
Each moon is an explicit celestial — a docking target in the simulation, just like a planet.
| Field | Type | Unit | Description |
|---|---|---|---|
label |
string | — | Display name |
size |
float | km | Moon radius |
color |
string | — | Hex color |
orbitRadius |
float | km | Orbit radius around the parent planet |
orbitSpeed |
float | rad/s | Angular velocity. Negative = retrograde (e.g. Triton). |
orbitPhaseAtEpoch |
float | degrees | Initial angle |
orbitInclination |
float | degrees | Inclination relative to the planet's equatorial plane |
orbitLongitudeOfAscendingNode |
float | degrees | Longitude of the ascending node |
For generated systems, moons are procedurally derived from the planet's size and label (seeded hash). Explicitly authored systems (Sol) define their moons directly.
Orbit Speed Formula
orbitSpeed = 0.11 / sqrt(orbitRadius³)
Where 0.11 is Earth's angular speed in orbital-sim-seconds per radian, and orbitRadius is in AU. This gives each planet the correct relative orbital period.
Orbital sim time runs at a configurable multiplier relative to real time (SimulatedSecondsPerRealSecond), so the absolute speed only matters in relation to other planets, not to wall-clock time.
Unit Summary
| Concept | Unit |
|---|---|
| Galaxy positions | light-years (ly) |
| Star / planet / moon sizes | km |
| Asteroid field radii | km |
| Resource node radii | km |
| Moon orbit radius | km |
| Planet orbit radius | AU (converted to km at runtime) |
| Planet / moon / star orbit speed | rad / orbital-sim-second |
| Orbital angles (inclination, ascending node, periapsis, phase) | degrees (converted to radians at runtime) |
| Resource node angle | radians |
| Resource node inclination | degrees |