jbourdon/space-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: improved visualisation and x4 data import

Browse Source
This commit is contained in:
Jonathan Bourdon
2026-03-18 20:58:17 -04:00
parent 358122a74a
commit f98c47a8a7
45 changed files with 32840 additions and 1482 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
docs/SYSTEMS.md Normal file
View File

@@ -0,0 +1,136 @@
# 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 |