The boundaries behind Avara3D's simulation and rendering loop.

This page highlights the decisions that control lifetime, host time, simulation mutation, render-data flow, physics synchronization, and platform execution. The API reference records exact contracts; the Janus demo shows them running.

01 / Ownership and boundaries

Lifetime is centralized without making scheduling own scene state.

Application owns both the active Scene and the Runner that drives it. Runner retains a non-owning Scene&, separating update policy from ownership of simulation state.

Scene retains the root hierarchy and owns independently replaceable visual, physics, and input systems. The important classes are introduced through these responsibilities rather than repeated as a catalog.

02 / Host updates and simulation

Host updates are variable-rate. Simulation advances through fixed-duration boundaries.

Each Runner update samples host time, calls variable-rate application work, updates platform and input state, executes zero or more bounded fixed steps, and then renders the completed state.

  1. 01Application updateVariable-rate policy
  2. 02Poll eventsWindow + platform
  3. 03Update inputState + callback
  4. 04Schedule0…N fixed steps
  5. 05RenderCompleted state
  6. 06PresentSwap buffers

Bounded fixed-step scheduling

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

Pause, explicit single-step, resettable simulation time, and discarded-time accounting remain part of the scheduler rather than ad hoc demo behavior.

One simulation step

  1. Pre-step commands
  2. sceneWillStep
  3. Bullet step + contacts
  4. Post-step commands
  5. sceneDidStep

Commands originating from input or UI are moved into explicit simulation boundaries. Each queue is exchanged before execution, so work enqueued by a running command waits for a later step.

03 / Rendering architecture

Scene representation is extracted before the graphics backend is touched.

VisualWorld coordinates the frame, but scene objects are not submitted directly as graphics commands. Gathering extracts visible state, packetization converts it into backend-oriented work, and Renderer owns OpenGL/WebGL execution.

  1. Begin frame
  2. Application frame callback
  3. Pre-traversal
  4. Gather + packetize
  5. Render packet
  6. End frame + present

04 / Scene and physics integration

A3D keeps its scene-facing rigid-body model above Bullet and makes transform authority explicit.

A Node owns its PhysicsBody; bodies may share PhysicsShape objects. Public A3D types delegate through proxy interfaces, allowing Bullet to implement worlds, bodies, and shapes without becoming the public object model.

Static

Scene placement establishes fixed collision geometry.

Kinematic

Application-driven Node transforms move the Bullet body.

Dynamic

Bullet simulation updates the Node through the motion-state bridge.

Collision shape

Explicit or derived from primitive, convex-hull, or concave scene geometry.

Exact axis, transform, angle, scale, time, and viewport rules live in Coordinate and Transform Conventions.

05 / Other design details

Smaller systems that follow the same preference for explicit boundaries.

Native + web

One application model, two host loops.

Application::Run↓
while (update())emscripten main loop

Native builds block in the host loop; web builds install the same update path into the browser. Visibility changes suspend the simulation clock so hidden-page time does not become catch-up work.

Runtime instrumentation

Timing is built into the frame lifecycle.

ApplicationPhysicsEngine CPURender CPURender GPUFrame

Runner also records step counts, simulation time, discarded catch-up time, contacts, body types, and collision-shape inventory for the live statistics overlay.

Hit testing

Viewport query → broad phase → exact geometry.

  1. Logical point
  2. World segment
  3. Scene traversal
  4. Mesh-local segment
  5. Element AABB
  6. Triangle test

Search modes return any, closest, or all near-to-far hits. Bounds-only queries can stop before the two-sided Möller–Trumbore triangle stage.

Scene importing

glTF becomes ordinary A3D scene state.

glTF / GLB→fastgltf→GlTFImporter→Scene + Nodes

Import options independently select meshes, materials, cameras, and lights. Imported hierarchy and transforms enter the same representation used by programmatically assembled scenes.

Reference and proof

Continue from design intent into exact contracts or running application code.

Open demo source API reference Conventions