Physics answers a different question#
Rendering asks how an object looks. Physics asks where it can move and how it responds to forces. A visible chair can have a much simpler collision shape than its rendered mesh. A trigger can detect a crossing without blocking motion at all. PhysicsWorld owns body state and collision objects. Scene holds a body handle, desired kinematic motion, and render-visible transforms. QubicEngine’s reference design uses a physics adapter so a mature solver can supply contacts and constraints without leaking its internal pointers into scene files.
A body meets a floor This illustration uses canvas. The explanation below describes the same process.
A fixed timestep#
Integrators advance position and velocity over a time interval. Large or varying intervals can change collision behavior and numerical stability. Application accumulates elapsed time and runs PhysicsWorld in fixed increments, such as a configured 1/60 second. A cap prevents a long pause from creating an unlimited catch-up loop. The cap and resulting time policy should be visible in diagnostics. Rendering interpolates the previous and current body poses. It cannot create new collision accuracy between those states. A kinematic controller may use swept collision queries to prevent passing through thin objects; interpolation alone cannot prevent tunneling.
Find possible collisions, then prove them#
The broad phase uses spatial bounds or a dynamic tree to identify candidate pairs. The narrow phase tests the actual collision shapes and generates contact information. Collision layers filter unrelated pairs early. A solver applies constraints and impulses to those contacts, then integrates the bodies. Convex shapes are efficient for dynamic bodies. Complex triangle meshes are often appropriate for static environments, with restrictions determined by the chosen solver. Continuous collision detection, sleeping, and constraint settings are explicit body or world policies rather than universal switches that cost nothing.
Implementation: ownership and update order
// Reference update flow. Each call belongs to a named system.
controller.ConsumeRootMotion(animation.rootDelta);
physics.ApplyKinematicTargets(controller.targets);
physics.Step(fixedDeltaSeconds);
scene.ApplyDynamicBodyTransforms(physics.completedPoses);
scene.ResolveWorldTransforms();The physics adapter defines Step and completedPoses. Step owns solver state and completes its internal dependencies before publishing poses. Dynamic bodies write their transforms to Scene; Scene does not overwrite them with an independently integrated position in the same tick. A teleport explicitly changes body state and wakes it when required.
Triggers, events, and synchronization#
Trigger enter/stay/exit events are queued after a completed simulation step. Consumers can request scene changes, but they do not destroy solver objects while contact iteration is using them. Defer deletions to a safe update boundary. An entity generation check protects events that outlive their target. Audio and animation consume collision and movement events after the authoritative state is known. The renderer sees interpolated body poses through RenderWorld. This keeps GPU extraction independent of the physics library’s locks and allocation rules.
Measure and debug#
The useful counters are candidate pairs, active bodies, narrow-phase tests, solver iterations, and simulation duration. Label them as native measurements only when collected from the native runtime. More bodies do not necessarily mean more cost if most are sleeping; a dense pile may cost more than many isolated movers. Objects falling through a floor can indicate a large step, thin geometry, a wrong collision layer, or unsupported shape pairing. Jitter can come from conflicting transform authorities or extreme mass ratios. Scale mismatches affect collision margins and gravity expectations. Draw collision shapes and contacts alongside the rendered scene before changing solver parameters. Explore frame scheduling for the simulation/render distinction, and scene ownership for transform authority.