Simulation Core Concepts

Darksun runs a continuous physics simulation underneath the user interface. Understanding how the simulation loop operates will help you make sense of time warp, worker updates, and the data you see in each window.

Time & Epochs

• Epoch – Simulation time is represented in UTC milliseconds (epochMs). By default, the initial epoch is the current system time when the app boots.
• Simulation Clock – The clock advances either in real time (1×) or at an accelerated / decelerated rate controlled by time warp.
• Pausing – When paused, the clock is frozen but the UI remains interactive. Tooling such as the mission planner can enqueue manoeuvres without a ticking clock.
• Jumps – You can jump to a specific epoch from the timeline or mission planner. Darksun propagates all spacecraft forward or backward to the requested time, ensuring continuity.

Propagation Pipeline

1. Input Collection – The UI and mission planner broadcast commands (time delta, manoeuvre execution, state updates) to the physics worker.
2. Integration – Each spacecraft runs through the propagator configured in mission settings (RK45, IAS15, DP87, etc.). Integrators pull forces from the active acceleration model.
3. Event Detection – Specialised detectors catch sphere-of-influence transitions and surface collisions; derived products (altitude extrema, eclipse factors) are computed separately from the recorded trajectory.
4. State Sanitisation – Results are normalised into consistent coordinate frames, validated, and pooled to minimise garbage collection.
5. Streaming Back – The worker posts snapshots to the UI thread. The store updates caches (spacecraft, orbits, ground tracks) and notifies windows via Zustand selectors.

Time Warp & Cadence

• Adaptive Step Planner – The propagator adjusts internal step sizes based on tolerance settings. Higher warp rates only change how frequently snapshots are sent back; the solver maintains numerical accuracy.
• Cadence Controller – Ensures that even at high warp, the UI keeps receiving updates at a cadence appropriate for smooth visuals and event timing.
• Determinism – Given identical initial conditions and mission plans, the simulation is deterministic; user interactions do not introduce randomness.

Coordinate Frames

Frame	Usage	Notes
ECLIPJ2000	Default scene and orbital data	Right-handed ecliptic frame at J2000.
TNW (Radial-Transverse-Normal)	Relative manoeuvre planning, visualisation of burns	Computed per spacecraft.
Planet-fixed	Groundtrack & surface features	Uses celestial body rotation models and ephemeris.

Conversions are handled by the CoordinateFrameService. For custom tools, prefer using existing helpers rather than rolling your own transformations.

Need a deeper dive? See Reference Frames for axis diagrams, recommended use cases, and conversion utilities.

Solar System Modelling

Darksun’s simulation worker constructs the active solar system by combining registry metadata with live ephemerides. Each tick, the CelestialBodyProvider samples the requested bodies and hands position, velocity, orientation, and environmental parameters to the propagator and renderer queues.

Ephemeris Sources

Source	Provided by	Description	Typical Use
Astronomy Engine	CelestialBody (astronomy-engine path)	Samples built-in heliocentric ephemerides for major solar-system bodies.	Sun and primary planets.
Canonical Keplerian	CelestialBody (canonical branch)	Propagates osculating elements defined in the catalog via a Kepler solver.	Canonical moons and custom bodies.
Barycentric Displacement	CelestialBody.applyBarycentricDisplacement	Applies barycentric offsets after primaries and satellites are updated.	Pluto–Charon scale systems.
Static / Anchored	CelestialBody.updateStaticBody	Keeps a body fixed in a parent frame with rotation only.	Ground stations, frame anchors, visual props.

Bodies select one of these paths from their definition. The current implementation does not ingest external JSON/SPICE tables automatically.

Celestial Body Archetypes

Archetype	Behaviour	Key Configuration Fields
Primary	Defines SOI, rotation, atmosphere, harmonics, and texture assets.	gravitationalParameter, radius, j2, j3, rotation block.
Satellite	Inherits from a parent primary and can override environment metadata.	parentId, defaultEphemeris, optional drag/SRP overrides.
Procedural / Synthetic	Generated on the fly for tooling (e.g., transfer targets) without full visual assets.	render.disabled, surfaceProcedural, optional collision mesh.
Reference Frame Anchor	Zero-mass helpers used for navigation overlays (Lagrange points, ground stations).	isReferenceOnly, optional custom frame transforms.

For each archetype, the provider hands the worker a fully resolved state expressed in ECLIPJ2000 and the planet-fixed frame, so downstream services do not need to care about the original data representation.

Update Cycle

1. The UI requests any newly visible bodies when windows (e.g., groundtrack, solar system map) mount.
2. The worker samples ephemerides on the simulation clock, applying rotational models and atmospheric layers.
3. The OrbitCache and visual subsystems consume the resulting states to update path rendering, SOI volumes, and lighting.

Extending the Solar System

1. Register the body – Add an entry to the solar system catalog (currently apps/api/data/physics-bodies.json + apps/api/data/render-bodies.json) and reseed the database with identifiers, the desired ephemeris source, and environmental metadata.
2. Provide orbital data – Supply osculating elements (semi-major axis, eccentricity, inclination, RAAN, argument of periapsis, mean anomaly) or reference an astronomy-engine body in the definition.
3. Configure physics hooks – Optional: define J2/J3, drag model coefficients, SRP area multipliers, and SOI radius overrides. These propagate through CelestialBodyProvider automatically.
4. Wire visuals – Attach texture assets, LOD meshes, and ring parameters in the render catalog if the body should render in the R3F scene.

Because the simulation worker resolves all bodies through the same provider, new entries become available everywhere: propagator force models, groundtrack projections, analytics exports, and mission planning heuristics.

Precision & Tuning

• Tolerance Controls – Available under Settings → Simulation. Lower values increase precision at the cost of computation time.
• Perturbations – Adjust the catalog entries or switch to the two-body only debug mode (AccelerationModel.setTwoBodyOnly(true)) when you need a simplified force model; there is no per-mission toggle in the UI yet.
• State Sanitiser – Guards against NaNs, invalid energy states, and out-of-bounds positions. If a propagation diverges, the sanitiser flags the spacecraft for operator attention.

Data Accessibility

• Snapshots – Capture complete spacecraft states, orbit segments, and event lists. Consumed by the timeline, orbit graphs, and mission planner.
• Derived Metrics – Altitude extrema, collision distances, visibility windows, delta-v budgets, and thrust schedules are computed on the worker and streamed as ready-made datasets.
• History vs Cache – Recent history is retained in memory for quick scrubbing. Long-term logs can be exported via the telemetry toolkit.

With the simulation basics in mind, continue to the physics section for a deeper look at the force models and numerical methods used inside the propagator.