Physics stepping and spatial queries

Trace fixed solver steps, incremental body synchronization, assembly topology, continuous collision, and spatial query acceleration.

Asterune synchronizes instance state into a Rapier physics world, advances that world in fixed substeps, and writes resulting poses back to instances. Assembly membership, spatial queries, and rendered interpolation have their own caches and clocks. Changing a part therefore affects more than its next solver pose.

The execution scheduler determines when world simulation runs. The physics layer decides which bodies this host simulates and how much fixed physical time each invocation advances. Dedicated servers, clients, and solo hosts use the same physical representation with different authority.

Solver time and fixed script ticksCopy link

The rigid-body solver uses a timestep of 1 / 240 seconds. Each simulation call adds nonnegative elapsed time to an accumulator capped at 0.25 s. The solver runs complete substeps until less than one timestep remains. A long stall therefore discards excess accumulated time instead of producing an unlimited catch-up loop.

The script fixed clock is separate. Its rate defaults to 240 ticks per second and clamps to 1 through 240. It runs at most 32 ticks per frame, then caps its remaining accumulator to one script tick. A lower script tick rate can contain several 240 Hz physical substeps. These limits apply to different accumulators: the 32-tick limit does not replace the solver's 0.25 s cap.

With fixed-tick listeners, the execution schedule surrounds each tick with FixedPreSimulation and FixedPostSimulation. Controllers and world physics advance between those phases. Without that path, the solver can consume several substeps within one variable-frame simulation invocation. Script timing APIs are described in the timing guide.

Each solver substep clears accumulated forces and torques, applies gravity fields, body movers, buoyancy, and force-based constraints, then advances winches and servos. Rapier receives 8 solver iterations, 4 additional friction iterations, and a maximum of 4 continuous-collision substeps. Contact capture runs after each physical substep, preserving transitions within a frame that contains several steps.

Incremental body synchronizationCopy link

Body synchronization follows the instance arena's part-mutation log. It sorts and deduplicates changed IDs, then compares each part's mutation revision with its solver entry. An unchanged revision avoids reconstructing synchronized state. If the retained log cannot describe all changes, synchronization scans current parts and removes stale bodies.

Different mutations require different updates. Transform, velocity, collision group, and collision-enabled changes can update existing bodies or colliders. Changes to size, primitive shape, geometry, anchoring, ownership mode, material, massless state, physical properties, or engine type rebuild the body. Rebuilding also marks dependent joints for synchronization.

The body's type follows its role:

Remote bodies retain collision presence without receiving local dynamic simulation. Their incoming pose and velocity are pinned before stepping. Ownership therefore changes the local solver representation, rather than only changing which outgoing packets contain a part. The protocol and handoff rules are covered in Prediction and reconciliation.

A collider can remain present as a sensor when it does not provide solid response. Solid contacts and sensor intersections feed contact tracking through different narrow-phase paths. Collision groups are synchronized independently when their interaction matrix revision changes.

Assemblies and articulated mechanismsCopy link

Assembly construction uses union-find over rigid physical links. Each connected rigid group becomes an assembly record with a root and member list. The root prefers an anchored member when the group contains one; among eligible members, it selects the greatest mass and breaks ties by the smaller instance ID. Massless members contribute zero mass to this selection.

A second union-find joins assemblies connected by articulated links. That produces mechanisms while preserving separate rigid assembly membership. An anchored assembly marks its connected mechanism as grounded. A hinge joins rigid assemblies into a mechanism without merging their rigid membership.

An assembly is not represented as one merged Rapier body. Individual parts keep body entries, and joints enforce their physical relationships. Assembly records support grouping and ownership, while the solver still has bodies and joints for the connected parts. This distinction matters when assessing the cost of a large welded or articulated model.

The assembly cache follows mutation revisions and topology. Position and velocity updates refresh member data without requiring the same regrouping as a changed link, member set, anchoring state, or root-selection mass. Incremental membership changes can patch existing groups; a full build remains the fallback when cached topology cannot describe the change.

Attachment frames, motors, and force limitsCopy link

Constraint bindings resolve participating parts and attachment-local frames before reaching the solver. The binding must have the attachments required by its mode. One-attachment alignment can target the world; a two-body joint needs both parts. Disabled or incomplete bindings do not create an active constraint.

Joint definitions are compared with existing definitions. Changing participating bodies or local frames replaces the corresponding solver joint. Winch length is retained across compatible synchronization, so rebuilding a definition does not restart a running winch at its original length.

Servos update their target velocity every physical substep. The controller computes a velocity toward the target, caps it by the configured speed, and lets the joint motor apply its force or torque limit. A target is therefore a request to a bounded motor, rather than a direct assignment of the resulting body pose. Rope winches similarly advance a retained length toward their target and update the joint's driving terms.

Force-based alignment and velocity constraints compute against body mass or inertia. Kinematic and fixed participants contribute no dynamic inverse mass. The effective mass of both participants determines how a requested motion becomes force. Legacy body movers also apply bounded proportional and damping terms before each substep.

Collision geometry, tunneling, and sleepingCopy link

Rendered geometry and solver geometry share a source without requiring the same representation. Explicit collision geometry takes precedence. Otherwise, anchored baked meshes use a recognized convex surface when possible, then a triangle mesh fallback. Dynamic baked meshes use their convex hull. Geometry colliders are cached by scale and anchored state, with up to 8 retained entries per source.

Continuous collision detection (CCD) depends on travel during one physical step. The initial test includes both linear speed and angular speed multiplied by a bounding radius. Travel greater than one quarter of the smallest body dimension requires a continuous treatment. This includes a rotating thin rod whose center barely moves.

Hard swept CCD is selected when linear motion alone crosses that threshold and travels more than 0.5 studs per step. Other qualifying motion uses soft CCD with a prediction distance twice the estimated combined linear and rotational travel. Ordinary slow bodies use neither path. The distinction avoids paying for swept CCD on every rotating or moderately moving object.

Dynamic bodies can sleep. Their linear threshold is 0.4, their angular threshold scales inversely with body radius, and their sleep delay is 0.5 s. Sleep state reduces active solver work; it does not remove the collider from the world.

Before stepping, containment checks restore nonfinite or escaped dynamic bodies to a finite recorded position. The world bound is 1,000,000 studs per axis. Finite linear speed is capped at 20,000 studs per second, and angular speed at 2,000 radians per second. These guards bound invalid or runaway solver state; they are separate from game-defined movement validation.

Contact material and event stateCopy link

Friction and elasticity use weighted averages of both contacting materials. For a coefficient c with weights w, the solver hook computes (w1 * c1 + w2 * c2) / (w1 + w2). If both weights sum to zero, the coefficient is zero. The hook writes those coefficients into each solver contact rather than relying only on Rapier's default material combination.

Contact capture canonicalizes each pair by instance ID and compares the sorted current set with the previous set. Entered and exited contacts produce lifecycle events; continuing contacts retain geometry for contact queries. Sensor intersections also participate in contact state, although they apply no solid response. Event delivery occurs outside the low-level solver step through the world execution schedule.

Solver broad-phase pairsCopy link

The solver broad phase separates fixed scenery from moving colliders. Fixed colliders use a spatial index; moving colliders retain their existing pairs with scenery and query that index when their swept bounds change. The broad phase emits additions and deletions by comparing the previous and current sorted candidate lists. Moving a fixed collider also checks the mover index, so editing scenery can create or remove pairs without waiting for every mover to change.

Mover-to-mover work remains in Rapier's multi-region sweep-and-prune broad phase. The engine's moving bounds also remain in packed loose entries rather than rebuilding a spatial hierarchy at every substep. Soft-CCD prediction expands a mover's query reach using its velocity and prediction limit. These candidate pairs still require narrow-phase geometry tests before becoming contacts.

Query indexes outside the solverCopy link

World raycasts, overlaps, and shape casts use an instance-derived query index. This index can answer queries independently of whether a physical substep has just run. The first query after a relevant topology or part revision refreshes its bounds; further queries reuse the same index until that key changes.

The index separates queryable and nonqueryable parts into two spatial trees. Normal queries traverse the queryable tree. An explicit exhaustive path can also traverse the other tree before applying its own filters. Include or exclude ancestry, collision groups, and collision-response filtering remain per-query tests after spatial candidate selection.

Each tree combines a settled quad bounding-volume hierarchy with a packed list of changed bounds. A moved leaf leaves the hierarchy and enters the loose list. Unchanged bounds stay settled. When loose entries or removed hierarchy leaves exceed max(128, part_count / 16), the tree rebuilds. Queries test both sets, so changed objects remain visible before that rebuild.

Ray traversal orders intersected bounds by entry distance and shortens its remaining bound after a closer exact hit. Overlap queries first gather bounds, then test actual primitive or mesh geometry. Broad-phase intersection alone is not a positive shape-overlap result. Nonfinite query bounds fall back to candidate enumeration instead of silently trusting invalid spatial bounds.

Terrain supplies a separate chunk-surface collider cache, described in Terrain surfaces and chunk updates. Character collision uses a local spatial grid and swept motor, described in Character movement and navigation.

Presentation interpolationCopy link

The renderer does not overwrite solver state to smooth physical movement. The physics layer records a part's pose before the most recent batch of substeps and retains the batch's substep count. Presentation blends that pose toward the resulting instance pose using the remaining physical time and any host-held lag. Rotation uses normalized spherical interpolation.

The blend accounts for the whole recorded batch while presenting approximately one physical substep behind simulation. A frame that advances no substeps continues the preceding blend. Anchored parts and movements exceeding 64 studs bypass this interpolation, allowing a large relocation to appear at its assigned pose instead of sweeping through the intervening world.