From scene to simulation, physics, and rendering.

How A3D handles ownership, simulation scheduling, rigid-body physics, and rendering.

Ownership

Division of responsibilities.

Application is A3D's default top-level owner, owning the active Scene and the Runner that drives it.

Scene is the central container for simulation state. It owns the node graph and scene content — including meshes, physics bodies, materials, lights, and cameras — along with the major systems that operate on them: VisualWorld, PhysicsWorld, and InputContext.

VisualWorld drives the rendering stack, PhysicsWorld delegates rigid-body simulation to Bullet, and InputContext provides polling and mapping of platform input. The node graph hierarchically organizes all scene content.

Runner is responsible for advancing the Scene without owning it, keeping simulation scheduling separate from scene lifetime and state ownership.

Application is provided as the default application host, but Runner and Scene can also be embedded directly into arbitrary application frameworks.

PhysicsWorld

Physics configuration & simulation

backend: PhysicsWorldProxy → Bullet
Node

Simulation

Fixed simulation, variable host rate.

Runner decouples host updates, rendering, and physics/simulation timing. Each host update measures elapsed time, processes application and input work, then schedules zero, one, or up to a configured maximum number of fixed-duration simulation steps. Physics and application simulation therefore see a stable timestep even as frame timing varies. Once the scheduled steps are complete, rendering observes the latest completed simulation state and a frame is presented.

Catch-up is bounded: if the host falls behind, Runner performs only a limited number of simulation steps rather than allowing an ever-growing backlog. Excess accumulated time is discarded and recorded. Pause, single-step, reset, and the simulation clock and step count are handled by the scheduler itself rather than being left to the application.

Within each simulation step, execution follows a defined order. Queued pre-step work runs before application callbacks and physics, while post-step work runs afterward. This gives application code predictable places to modify and observe simulation state, while keeping physics updates and other step-sensitive changes from occurring at arbitrary points in the cycle.

  1. Application update
  2. Update input
  3. Step
  4. Render
  5. Present

Step scheduling

Host delta
16.67 ms
Fixed step
8.33 ms
Scheduled
2 steps
Catch-up
≤ 8 steps

One simulation step

  1. Queued pre-step commands
  2. sceneWillStep callback
  3. Rigid-body step
  4. Queued post-step commands
  5. sceneDidStep callback

Physics

Physics powered by Bullet.

Physics is integrated directly with the scene graph. A Node may own a PhysicsBody, which references a shareable PhysicsShape. As nodes enter or leave the active scene, their bodies are added to or removed from the scene's PhysicsWorld automatically.

PhysicsBody instances are automatically maintained by the PhysicsWorld as their nodes are added to or removed from the scene. Public physics types delegate through internal proxies to Bullet, keeping backend-specific types out of the public object model.

Body types

Static · Kinematic · Dynamic

Collision shapes

Convex hull · Concave decomposition · Primitive

Rendering

Turning a scene into a frame.

VisualWorld coordinates rendering for the active scene. Each frame, scene traversal gathers the visible cameras, lights, meshes, materials, and transforms into an immutable snapshot needed to render the frame. This keeps the mutable scene graph as the application-facing model while giving rendering a stable set of inputs. The gathered state is then resolved to graphics resources and converted into backend-oriented render packets. Packets are sorted by pipeline state before execution, reducing unnecessary graphics-state changes. Those packets are consumed by Renderer, which owns OpenGL/WebGL execution through the active RenderContext. The result is a staged pipeline from scene representation to extracted frame state to GPU work, rather than rendering logic being embedded throughout scene objects.