RigidBodyOptions
physics/rigid-body.types.ts:183Construction options for a RigidBody. A body needs at least one collider — supply exactly one via RigidBodyOptions.collider, or several via RigidBodyOptions.colliders. Providing neither throws ErrorCode.PHYSICS_NO_COLLIDER.
The body is seeded from the host WorldObject's position and
rotation at attach time, so place the object before adding the component.
Velocities, impulses, and sizes are all in pixel units.
Properties
angularDamping?: number Angular damping — a drag that bleeds off spin over time. 0 (the default)
means no drag.
angularVelocity?: number Initial angular velocity, in radians per second. Defaults to zero.
ccd?: boolean Enables continuous collision detection, which stops fast-moving bodies
from tunnelling through thin geometry at the cost of extra work. Defaults
to false.
collider?: ColliderOptions A single collider for the body. Shorthand for a one-element
RigidBodyOptions.colliders. Provide this or colliders, not both.
colliders?: readonly ColliderOptions[] Multiple colliders making up a compound body. Provide this or collider.
gravityScale?: number Per-body multiplier on the world's gravity. 1 (default) is normal
gravity, 0 makes the body float, negative values invert it.
linearDamping?: number Linear damping — a drag that bleeds off linear velocity over time. 0
(the default) means no drag.
linearVelocity?: PointPrimitive Initial linear velocity, in pixels per second. Defaults to zero.
lockRotation?: boolean When true, prevents the body from rotating (it stays upright no matter
the contacts). Common for top-down characters. Defaults to false.
onCollisionEnd?: CollisionListener Called once when this body stops touching another body it was previously in contact with, with a CollisionEvent describing the other party. Useful for un-applying something a RigidBodyOptions.onCollisionStart did — leaving a trigger zone, ending an overlap highlight.
Like RigidBodyOptions.onCollisionStart, supplying this enables collision reporting for the body, and the callback runs under the same error isolation and timing guarantees.
onCollisionStart?: CollisionListener Called once when this body begins touching another body, with a CollisionEvent describing the other party. This is the primary gameplay hook for contact reactions — a bullet despawning on impact, an enemy taking damage, a trigger volume firing.
Opting in
Supplying this (or RigidBodyOptions.onCollisionEnd) is what enables collision reporting for the body: the engine flips Rapier's collision-event flag on the body's colliders. A body with no listener generates no events and costs nothing — so the static walls a projectile hits do not need a listener; only the projectile does. Rapier reports a pair as soon as either collider opts in.
Sensors vs. solid contact
The hook fires for both kinds of overlap: solid bodies physically colliding and a sensor collider (ColliderOptions.isSensor) passing through another collider without pushing it. A fast projectile is typically a sensor so it registers the hit without knocking its target around.
Error handling and timing
The callback runs during the body's own update phase and is wrapped in the
world's standard per-component error isolation: if it throws, the failure
is routed through World.reportError (or the world's onError
handler) and the rest of the tick continues. See CollisionEvent
for the guarantees about transform state and object lifetime at call time.
type?: RigidBodyType The body's simulation behaviour. Defaults to 'dynamic'. See
RigidBodyType.