PhysicsProvider

PhysicsProvider is an internal system that conditionally wraps scene content in Rapier physics. It consists of two components:

• PhysicsGate — wraps World children in Rapier's <Physics> when a physics config is provided.

• PhysicsBodyWrapper — wraps an Actor in Rapier's <RigidBody> when the Actor has a physics prop.

You do not need to use these directly — they are used internally by World and Actor.

How It Works #

PhysicsGate (used by World) #

1. When a World has a physics prop, PhysicsGate lazy-loads @react-three/rapier via dynamic import().

2. If the import succeeds, children are wrapped in <Physics> with the configured gravity, timestep, interpolation, and debug settings.

3. If @react-three/rapier is not installed, a console warning is logged and children render without physics.

PhysicsBodyWrapper (used by Actor) #

1. When an Actor has a physics prop and a PhysicsContext is available, the Actor's group is wrapped in <RigidBody>.

2. In 2D mode, Z translation and X/Y rotation are auto-locked.

3. Collision callbacks (onCollisionEnter, onCollisionExit) are mapped to Rapier's event system.

4. A RigidBodyRefContext is provided so usePhysics can access the body.

Lazy Loading #

Rapier is loaded dynamically at runtime:

• Not installed — warning logged, children render normally.

• Loading — children render without physics until the module resolves.

• Loaded — <Physics> and <RigidBody> wrappers activate.

This means @react-three/rapier is a true optional dependency — your bundle doesn't include it unless you install and use it.

Install #

pnpm add @react-three/rapier

Context API #

Two internal contexts are exposed for advanced use:

usePhysicsContext() #

Returns PhysicsContextValue | null. Contains:

useRigidBodyRef() #

Returns RefObject<RapierRigidBody> | null. Used internally by usePhysics to access the rigid body instance.

Type Definitions #

See Types for WorldPhysicsConfig, ActorPhysicsProps, RigidBodyType, and PhysicsColliderType.