Novolis Docs
novolis-physics / ARCHITECTURE.md

Architecture

Force-first textbook physics

dotnetphysicssimulationnovolis

Novolis.Physics is modular: small NuGet packages with a shared force-first loop for game-style simulation, plus specialized stacks where a monolithic pipeline is a poor fit.

Canonical pipeline

flowchart LR
  FM[IForceModel]
  SP[SimulationPipeline]
  INT[IIntegrator]
  FM --> SP
  SP --> INT
// One fixed step: sum forces, then integrate.
total += force.Evaluate(body, environment, timeSeconds);
body = integrator.Step(body, in total, dtSeconds);

Caller responsibilities:

  • Advance simulation time yourself (timeSeconds + dt each step).
  • Own environment values (PointMassField, meshes, atmosphere data).
  • Use `FixedStepAccumulator` to turn variable frame time into fixed physics steps.

Package dependency graph

Novolis.Math.Geometry
  └── Abstractions
        ├── Motion, Gravity, Aerodynamics, Collision.Simple
        ├── Ballistics (+ Collision.Simple)
        └── Orbits
              Novolis.Physics (meta) → all product packages
PackageResponsibility
AbstractionsIForceModel, IIntegrator, IStaticWorld, state samples
MotionSimulationPipeline, rigid-body integrator, fixed-step helper
GravityPoint-mass and patched-conic IForceModel
AerodynamicsAtmosphere density + simple lift/drag
Collision.SimpleStatic mesh BVH queries; sphere sweep integrator
BallisticsProjectile state, drag, queries, optional facade
OrbitsCentral-body leapfrog (parallel stack, not SimulationPipeline)
Astroly/pc/AU ↔ meters unit bridges (no catalogs or jump graphs)

Four integration styles

Not every feature uses the pipeline. Pick the style that matches the problem:

StyleWhenEntry types
PipelineArbitrary forces on rigid bodies or projectilesSimulationPipeline, IForceModel, IIntegrator
Ballistics facadeQuick cannon with −Y gravity + optional dragProjectileBallisticSimulation
Collision integratorSphere in a static mesh with contactBvhStaticSphereIntegrator, IStaticWorld
OrbitsLong two-body tests, SoA leapfrogCentralOrbitSimulator, LeapfrogCentralBodySoA

See INTEGRATION.md for decision tables and limitations (especially mesh sweeps).

Coordinates and units

  • Right-handed 3D; +Y is up.
  • Gravity and ballistics use −Y for uniform gravity.
  • SI-style units unless noted: meters, seconds, kilograms, newtons.
  • PointMassField stores GM (m³/s²), not separate mass and G.

Related documents