Celestial Catalogues

Darksun combines static metadata with live ephemerides so every subsystem shares a coherent view of the solar system.

Ephemeris Sources

Source	Implementation	Description	Typical Use
Astronomy Engine	CelestialBody.updateFromAstronomyEngineDirect	Samples solar-system ephemerides from the astronomy-engine library.	Sun and major bodies with high-fidelity built-in ephemerides.
Canonical Elements	CelestialBody.updateFromCanonicalElements	Propagates osculating elements with a Kepler solver (plus optional J2 drift baked into the elements).	Canonical planets and moons defined in the solar system catalog.
Barycentric Displacement	CelestialBody.applyBarycentricDisplacement	Applies barycentric offsets after the primary and secondary have been updated.	Pluto–Charon style systems or binary asteroids.
Static / Anchored	CelestialBody.updateStaticBody	Keeps the body fixed in its reference frame, applying only orientation updates.	Ground stations, Lagrange-point markers, visual props.

Bodies pick the appropriate branch at runtime based on their catalog entry. There is no automatic fallback to sampled tables; every source is chosen explicitly in the catalog data.

Body Metadata Profiles

Profile	Typical Fields	Behaviour
Primary	gravitationalParameter, radius, j2/j3, atmosphere, soiRadius	Defines SOI hierarchy, drag layers, and harmonics.
Satellite	parentId, defaultEphemeris, optional drag/SRP overrides	Inherits parent environment; supports altitude-dependent toggles.
Procedural	render.disabled, surfaceProcedural, optional collision mesh	Generates placeholder physics without art assets.
Reference	isReferenceOnly, custom frame transform	Zero-mass helpers for overlays and targeting.

Extending the Catalogue

1. Register the body – Add a new entry to the solar system catalog (for now, apps/api/data/physics-bodies.json + apps/api/data/render-bodies.json) and reseed the database. CelestialBodyRegistry instantiates everything from the API dataset at startup.
2. Provide orbital data – Supply osculating elements for the canonical solver or reference an astronomy-engine body. Numeric ephemeris files are not currently consumed directly.
3. Configure physics hooks – Optional: define J2/J3, drag models, SRP multipliers, and SOI overrides in the catalog entry. These propagate automatically through CelestialBodyProvider.
4. Wire visuals – Attach texture assets, LOD meshes, and ring parameters in the render catalog (typically Vercel Blob URLs or paths resolved via VITE_TEXTURE_BASE_URL) if the body should appear in the R3F scene.

The registry caches resolved states each simulation tick, so new bodies become available across the propagator, ground-track visualisations, analytics exports, and mission planning heuristics after a reload.