Physics backend summary
← Back to docs · Architecture · Decisions · Previous: Protocol core · Next: Grid services
Change: openspec/changes/physics-backend. Status: complete and accepted
(all tasks in sections 1 to 5 of tasks.md are ticked).
What was built
A physics engine for the region simulator, split in two crates:
welkin-physicsdefines thePhysicsSceneandPhysicsActortraits and holds all behaviour that does not depend on a solver. No engine types appear in the trait signatures.welkin-physics-rapierimplements the traits on Rapier 0.36.1 (rapier3d, Apache-2.0, pure Rust). It takes collision geometry fromaurora-prim.
The server is authoritative: viewers send control input and extrapolate from
the position, velocity and rotation values the server sends. The engine is
therefore invisible on the wire, and compatibility depends on update layout,
update conditions and plausible values (see design.md).
Spike and GO decision
The spike (spike-results.md, commit 4f6ec64) found that Rapier 0.36.1
covers heightfield, triangle mesh, convex hull and compound colliders, CCD,
shape casts and a serde snapshot round trip. The result was GO.
- Rapier is Z-up, matching OpenSimulator.
- It handles the ubODE step of 1/54.5454 s without trouble.
aurora-primand Rapier share a compatibleparry3d, and trimesh and convex hull colliders built from Aurora box and sphere geometry behave correctly (commits841fb59,01ce38e; Rapier bump1cd81b6,83ed653).- The replay harness (
osim-conform physics-spike,e0ffbe7) matched synthetic box-drop data with a maximum error of 0.20 m and box-rest data with about zero error. - The trajectory recorder (
b86cb0e,3c66df8) exists in C# and Rust, but scenes were not recorded from a live C# OpenSim, because no C# toolchain was available. The spike therefore validated the harness and the engine's features, not full parity against recorded ubODE runs. The larger scenes in the design's go/no-go list (100-box stack, 2,000 bodies, vehicles on recorded paths) have no automated test in the repository.
Jolt stays the documented fallback behind the same trait; it was not needed.
Components
Trait abstraction and null backend
PhysicsScene and PhysicsActor live in crates/welkin-physics/src/lib.rs.
null.rs is a backend that stores state and does no simulation, used for
tests of code above the trait (e41e8ec).
Rapier backend
crates/welkin-physics-rapier/src/lib.rs (2e1f10b2). Changes to actors are
marked dirty and pushed to Rapier in flush_dirty before each step.
- Prims and linksets: a linkset is one compound body; shape types are prim, convex and none.
- Terrain: a Rapier heightfield collider replaced the first cuboid stand-in
(
84bd16e). - Collisions: collision events, volume detect and top colliders (
e0528f5). - Raycasts: ray, box, sphere and plane probes with filter flags.
- Materials: friction, restitution, density and gravity multiplier are
synced in
flush_dirty(73b1052). - Snapshot and restore:
snapshot,restoreand JSON variants (snapshot_json,restore_json), mapping onto region save and restore (c78921a).
Engine-independent behaviour
These modules sit in welkin-physics, above the trait, so a change of
solver does not touch them.
vehicle.rs: the LSL vehicle model ported fromODEDynamics.cs. Vehicles are linear and angular motors with friction timescales, hover, banking and vertical attraction, applied as forces each step (27fc319).avatar.rs: the avatar controller ported fromODECharacter.cs, a force-driven capsule rather than Rapier's kinematic controller, so walking, flying, jumping and sitting keep the feel viewers expect (a5b0eed). This departs from the spike's mitigation note, which suggested the kinematic controller;design.mddecision 2 supersedes it.behaviors.rs: move-to-target, hover, buoyancy, look-at, and applied force, torque and impulse (09db884).keyframe.rs: keyframed motion (fb7d1f4).
Network parity
terse_update.rs: the change thresholds and rate limits fromSceneObjectPartandScenePresence, so a Rust region sendsImprovedTerseObjectUpdateunder the same conditions as C# (a3d2c24). The object update encoders themselves are inwelkin-msg(7241c49).tests/smoothness_check.rs: checks that walking, flying, vehicle and falling-object update streams do not produce snapping jumps when extrapolated (fb8a150). This is a test-level check; no live Aurora Viewer session is recorded in the repository.
Test coverage
23 tests pass in the two crates (cargo test -p welkin-physics -p welkin-physics-rapier), not the 20 first reported:
| File | Tests |
|---|---|
crates/welkin-physics/src/terse_update.rs | 15 |
crates/welkin-physics/tests/smoothness_check.rs | 5 |
crates/welkin-physics-rapier/tests/spike_aurora_colliders.rs | 3 |
The Rapier backend, vehicle, avatar, behaviour and keyframe modules have no unit tests of their own; they are covered only indirectly. This is the main gap to close before the region simulator depends on them.
Risks carried forward
- Vehicle feel will differ from ubODE. Tolerances and per-region tuning parameters are still to be set against recorded C# trajectories.
- Rapier is pre-1.0; the version is pinned and Rapier types stay out of the trait.