PhysicsWorld

The world-scoped owner of the physics simulation: a thin, opinionated arcade2d façade over a Rapier World. Add one to a World and every RigidBody component in that world registers its body and colliders here, gets integrated under gravity, and collides against its peers.

Physics is opt-in — the engine does not auto-attach a PhysicsWorld the way it does a Scene or the input samplers. Register one through the world's component factory, and call initPhysics first (Rapier is WebAssembly and must be initialised before any of its objects exist).

The frame pipeline (why bodies don't lag the render)

Getting the order of "apply input → step → read back → draw" right is the whole game with a physics integration. The engine ticks each world in three phases — pre-update, update, post-update — and within every phase the world-scoped components (this one) run before the object-scoped ones (RigidBody, graphics). This PhysicsWorld slots the simulation step into that schedule so the result is correct regardless of the order components were added to their objects:

1. PhysicsWorld.onPreUpdate (world, runs first) — drains a fixed-timestep accumulator and calls Rapier's step() zero or more times, advancing the sim using the forces and velocities set during the previous frame's update phase.
2. RigidBody.onPreUpdate (object, runs right after) — copies each simulated body's transform back onto its host WorldObject (position, rotation). Because this happens in pre-update, the host transform is settled before any gameplay or rendering code reads it.
3. gameplay onUpdate (object) — controllers read the fresh host position and influence bodies through RigidBody methods (applyImpulse, velocity, …). Those calls reach Rapier immediately; their effect appears after the next frame's step.
4. graphics onPostUpdate (object) — the existing AbstractGraphics transform-sync copies the host position into the display object. Since step 2 already ran, the visual is never a frame behind the simulation.

This is the standard fixed-timestep ("FixedUpdate") pipeline: inputs set this frame are integrated next frame — a single, imperceptible frame of latency — in exchange for an ordering that has no hidden dependency on component registration order.

Units

Everything at this surface is in the engine's pixel space. Gravity is pixels/second², body positions are the same pixels as WorldObject.position, and collider sizes are pixels. Internally the PhysicsWorldOptions.pixelsPerMeter option is fed to Rapier's lengthUnit so the solver stays numerically stable at that scale without any coordinate conversion leaking into your game code.

Collision events

After each step this component drains Rapier's contact-event queue and fans the results out to the bodies involved. A RigidBody subscribes by supplying RigidBodyOptions.onCollisionStart / RigidBodyOptions.onCollisionEnd; those callbacks fire during the body's own update phase (so transforms are already settled) with a CollisionEvent naming the other party. Bodies without a listener generate no events and incur no per-frame cost — see RigidBodyOptions.onCollisionStart for the opt-in rules and the sensor-vs-solid distinction.

import { Game, initPhysics, PhysicsWorld } from '@arcade2d/engine';

const game = await Game.bootstrap({ canvas: { fill: 'window' } });
await initPhysics();

const world = game.createWorld({
  components: (world) => ({
    physics: () => new PhysicsWorld(world, { gravity: { x: 0, y: 980 } }),
  }),
});