OHAO · Implementation Monograph

Monograph · 11 · Physics

11

Systems · full depth

Physics

Chapter contract

Simulation as a pluggable service: factory → backend → world step → component write-back → optional TLAS dirty. Rendering never steps Jolt itself.

Backend factory

createPhysicsBackend(preferred)
  1. If Jolt compiled and preferred is jolt/auto/empty → try JoltPhysicsBackend
  2. On exception → log and fall through
  3. Else / always available: NullPhysicsBackend (no-op, no crash)
Why null backend

Headless CI or machines without physics still run the renderer. “Microservice” isolation: physics failure must not take down the engine.

IPhysicsBackend surface

Abstract API covers: rigid body lifecycle, transforms, velocities, forces, sleep, shapes, CCD, 16-layer collision matrix, raycast/overlap/shape cast, contact callbacks (thread-safe queue), constraints (fixed/point/hinge/slider/cone/distance/six-DoF), heightfields, character controller. Handles are uint32_t with INVALID sentinels.

World config & state machine

PhysicsWorldConfig: gravity (default −9.81 y), timeStep 1/60, maxSubSteps, multithreading, sleeping, CCD, debug flags, maxBodies/constraints. Scene constructor builds a world and initializes with settings.

States: STOPPED · RUNNING · PAUSED · STEPPING. Hosts call play/pause/step/stop (and GDScript facades mirror this).

Step workflow

PhysicsWorld::step(dt)
  1. If not running/stepping, return
  2. Accumulate time; for each substep:
  3. Force registry: gravity, springs, drag, volumes, fields…
  4. Backend integrate contacts / constraints
  5. Drain contact begin/persist/end events to listeners
  6. Write transforms back to RigidBody / PhysicsComponent / actors
  7. Optional profiler / debug draw data

Bodies, shapes, layers

Types: dynamic, static, kinematic. Shapes: box, sphere, capsule, cylinder, triangle mesh, heightfield. Layers 0–15 (DEFAULT, STATIC, CHARACTER, TRIGGER, PROJECTILE, …) with pair enable/disable. CCD for fast movers. Mass, friction, restitution, damping, gravity scale.

Forces & constraints

Force generators register on bodies each step (not one-shot impulses only). Constraints build mechanisms: doors (hinge), ragdolls, vehicles. Motors, limits, breakable joints for gameplay.

Character & queries

Capsule character controller with ground state classification. Queries: raycast closest/all, sphere/box overlap, shape casts — layer masks filter results. Grab/throw helpers sit above springs/constraints in higher-level APIs.

Sync to scene / GPU

After physics, before render
  1. Actor world matrices updated from bodies
  2. Deferred draws use new model matrices automatically if upload path reads components each frame
  3. RT: TLAS instances need update/rebuild if transforms moved — trunk favors static BLAS; dynamic policy is host responsibility
backend_factory.cppJolt or null
physics_backend.hppFull contract
jolt/jolt_backend.*Production impl
world/physics_world.*Step · state
forces/*Generators
components/physics_component.*Actor bind

Design units in this module

Each card is a focused design page (what / how / why + sources). Full tree: Sitemap.

backend

Backend plugin

IPhysicsBackend, factory, null fallback, Jolt.
world

PhysicsWorld

Config, state machine, step, body registry.
bodies

Bodies & shapes

RigidBody, all shape types, factory, PhysicsComponent.
forces

Force generators

Registry, gravity, spring, drag, volumes, fields, presets.
materials-phys

Physics materials

Friction/restitution style materials.
math-constants

Physics math & constants

Shared scalars, clamp helpers, math utils.
debug

Force debugger

Debug visualization hooks.