Gravitational Forces

Darksun models gravity through layered terms so you can scale fidelity to the mission.

Primary Body Gravity

• Newtonian point-mass acceleration using the body’s gravitational parameter (μ).
• Sampled from CelestialBodyProvider, which resolves mass properties at the simulation epoch.
• Works in both inertial (ECLIPJ2000) and body-fixed frames; the integrator always stores state in inertial coordinates.

Spherical Harmonics

• J2 and J3 zonal terms model oblateness and pear-shape effects when those coefficients are present in the solar system catalog.
• CelestialBodyRegistry keeps those coefficients attached to each body and GravitationalSolver adds the perturbation automatically—no runtime toggle is required.
• To change harmonics you must update the catalog entry (or provide alternate datasets) and restart the simulation so every cache refreshes under the new coefficients.

Third-Body Perturbations

• Gravity from every registered body (e.g., Sun, Moon) is added each step to capture inter-body interactions.
• GravitationalSolver.computeAccelerationCentralBodyRelative samples all available bodies and applies the indirect term that removes the central-body acceleration.
• Body selection is driven by the registry configuration; there is currently no automatic distance-based pruning, so keep the catalogue lean when performance is a concern.

Sphere of Influence (SOI) Transitions

• Canonical SOI radius defaults to Laplace’s approximation r_soi = a (m / M)^{2/5}, where:
  • a – semi-major axis of the secondary,
  • m – secondary mass,
  • M – primary mass.
• SOIManager applies hysteresis (SOIConfig.hysteresis) so spacecraft grazing the boundary do not oscillate between bodies.
• On transition:
  1. Position and velocity are re-centred: r_new = r_old + r_from - r_to (likewise for velocity).
  2. The propagator swaps in the new body’s gravitational parameter and perturbation flags.
  3. Downstream consumers see the central-body change and request fresh orbit data on their next propagation cycle.
• Disable transitions entirely for patched-conic studies by setting disableSOITransitions in SOIConfig.

Use the SOI overlays in the 3D scene to validate boundary tuning before running long propagations.