/r3f-physics

name: r3f-physics
description: Add Rapier rigid bodies, colliders, forces, sensors, and joints to React Three Fiber. Use for collision-driven movement and simulation; use animation guidance for purely visual motion.

React Three Fiber physics

Check installed Fiber, React, and Rapier versions. Rapier 2 targets Fiber 9 / React 19; older projects need their compatible package line. Keep rendering and simulation ownership separate.

Falling and clickable body

Mount beneath Canvas with lighting. Physics loads WASM asynchronously; include Suspense. Cuboid collider arguments are half-extents, unlike BoxGeometry's full dimensions.

import { Suspense, useRef } from 'react'
import { CuboidCollider, Physics, RigidBody, type RapierRigidBody } from '@react-three/rapier'

function FallingBox() {
  const body = useRef<RapierRigidBody>(null)
  return (
    <RigidBody ref={body} position={[0, 2, 0]} colliders="cuboid" restitution={0.2}>
      <mesh name="physics-box" onClick={() => body.current?.applyImpulse({ x: 0, y: 3, z: 0 }, true)}>
        <boxGeometry />
        <meshStandardMaterial color="coral" />
      </mesh>
    </RigidBody>
  )
}

export default function Example() {
  return (
    <Suspense fallback={null}>
      <Physics timeStep={1 / 60}>
        <FallingBox />
        <RigidBody type="fixed" colliders={false}>
          <CuboidCollider args={[4, 0.25, 4]} position={[0, -0.25, 0]} />
          <mesh position={[0, -0.25, 0]}>
            <boxGeometry args={[8, 0.5, 8]} />
            <meshStandardMaterial color="slategray" />
          </mesh>
        </RigidBody>
      </Physics>
    </Suspense>
  )
}

Bodies and colliders

• Dynamic bodies respond to forces. Fixed bodies represent static surfaces. Position-kinematic bodies use `setNextKinematicTranslation/Rotation`; velocity-kinematic bodies use linear/angular velocity setters.
• Set initial transforms on RigidBody. Do not animate a simulated mesh's position in `useFrame`; the physics world remains authoritative and interpolation can overwrite it.
• Prefer simple colliders or compound convex shapes. Use trimesh mainly for static concave environments; a hull closes holes and cannot preserve arbitrary concavity.
• Set `colliders={false}` when supplying complete manual colliders, otherwise automatic colliders may be added as well. Collider sizes/transforms must match world scale; use debug rendering to inspect them.
• Choose collider density/mass consistently and avoid accidental duplicate mass from overlapping auto/manual colliders.
• For many repeated bodies, InstancedRigidBodies reduces rendering overhead, not the cost of simulating each body. Keep instance keys/transforms stable.

Forces and simulation time

• An impulse is a one-time momentum change. A force persists until reset; repeated `addForce` calls accumulate. Do not add the same continuous force every render frame without an explicit force-management strategy.
• Use `useBeforePhysicsStep` for input/forces that must align with simulation ticks. If a controller owns all user forces on a body, it can reset and reapply them per tick; coordinate with other force sources before resetting.
• Kinematic targets should advance on physics steps. Teleporting with `setTranslation` is different from kinematic movement and can bypass expected collision response.
• Prefer a fixed timestep for stable behavior. `timeStep="vary"` trades predictability for variable stepping; multiplying values by render delta does not make the physics deterministic.
• For demand rendering, use `Physics updateLoop="independent"` so active bodies can request renders. A sleeping world should not force unnecessary rendering.
• Let bodies sleep; explicitly wake them when applying actions that need it. Enable CCD for fast/small bodies when tunneling warrants its cost.

Events, sensors, and joints

• Sensors report intersection enter/exit without contact response. Use sensor intersection events rather than expecting ordinary collision events.
• Collision groups require compatible membership/filter masks on both colliders. Use `interactionGroups` instead of hand-building masks unless the format is needed.
• Collision payloads may lack a rigidBodyObject for standalone colliders. Inspect the other collider/body safely; do not assume every hit is a named mesh.
• Follow the installed Rapier callback restrictions. In contact-filter hooks, cache body state before the step rather than querying it during Rust's borrowed simulation state.
• Joints connect body refs using local anchors and axes, not world coordinates. Check the hook's exact tuple shape for fixed, revolute, spherical, spring, or rope constraints.
• Read [controlled motion and joints](references/controllers.md) for a step-aligned kinematic platform and correctly aligned hinge.
• A collision-aware character controller is separate from moving a mesh or setting a dynamic body's position. Use the installed Rapier character-controller API and test stairs/slopes/grounding.
• Restoring a world snapshot requires matching body creation/handle relationships; it is not a generic way to swap arbitrary scenes beneath existing React refs.

Verify

Check resting contact, collider alignment, impulses, sleeping/waking, and different render frame rates. Test sensor enter/exit, fast-body tunneling, and Strict Mode remounts for the paths used.

Sources

• [React Three Rapier](https://github.com/pmndrs/react-three-rapier), [API reference](https://pmndrs.github.io/react-three-rapier/).
• [Rapier rigid bodies](https://rapier.rs/docs/user_guides/javascript/rigid_bodies), [colliders](https://rapier.rs/docs/user_guides/javascript/colliders), [character controller](https://rapier.rs/docs/user_guides/javascript/character_controller).