react-three-rapier

To implement advanced behaviors like one-way platforms or custom sensor logic, use physics hooks to filter collision and intersection pairs.

Filter Contact Pairs

useFilterContactPair controls how collisions are processed. The callback must return:

• rapier.SolverFlags.COMPUTE_IMPULSE (1): Process the collision normally.
• rapier.SolverFlags.EMPTY (0): Ignore the collision.
• null: Let other hooks or default behavior decide.

Note: The first hook that returns a non-null value wins.

Filter Intersection Pairs

useFilterIntersectionPair controls sensor intersections. The callback must return:

• true: Allow the intersection.
• false: Block the intersection.

Note: The first hook that returns false blocks the intersection.

Critical Constraint: Avoid Aliasing Errors

You cannot access rigid body properties (e.g., translation(), linvel()) directly inside these hooks because they run during the physics step. You must cache the required state in useBeforePhysicsStep and access the cached values within the filter hooks.

Implementation Requirements

You must explicitly enable the hooks on the collider using collider.setActiveHooks(rapier.ActiveHooks.FILTER_CONTACT_PAIRS) or FILTER_INTERSECTION_PAIRS.

import { 
  useRapier, 
  useBeforePhysicsStep,
  useFilterContactPair 
} from "@react-three/rapier";

const OneWayPlatform = () => {
  const platformRef = useRef<RapierRigidBody>(null);
  const ballRef = useRef<RapierRigidBody>(null);
  const colliderRef = useRef<RapierCollider>(null);
  
  const bodyStateCache = useRef(new Map());
  const { rapier } = useRapier();

  // 1. Cache state BEFORE the step to avoid Rust aliasing errors
  useBeforePhysicsStep(() => {
    if (platformRef.current && ballRef.current) {
      bodyStateCache.current.set(ballRef.current.handle, {
        position: ballRef.current.translation(),
        velocity: ballRef.current.linvel()
      });
    }
  });

  // 2. Use cached data to filter collisions
  useFilterContactPair((collider1, collider2, body1, body2) => {
    const ballState = bodyStateCache.current.get(body1);
    if (!ballState) return null;

    if (ballState.velocity.y < 0 && ballState.position.y > 0) {
      return rapier.SolverFlags.COMPUTE_IMPULSE;
    }
    return rapier.SolverFlags.EMPTY;
  });

  // 3. Enable hooks on the collider
  useEffect(() => {
    colliderRef.current?.setActiveHooks(rapier.ActiveHooks.FILTER_CONTACT_PAIRS);
  }, []);

  return (
    <>
      <RigidBody ref={platformRef} type="fixed">
        <CuboidCollider ref={colliderRef} args={[5, 0.1, 5]} />
      </RigidBody>
      <RigidBody ref={ballRef} position={[0, 3, 0]}>
        <CuboidCollider args={[1, 1, 1]} />
      </RigidBody>
    </>
  );
};

Joints are used to restrict the motion of one RigidBody in relation to another. In react-three-rapier, joints are implemented as hooks that take two RigidBody refs and a configuration array. Each joint hook returns a RefObject containing the raw reference to the underlying Rapier joint instance, allowing you to interact with it directly (e.g., configuring motors).

Available joint types include:

• Fixed: Keeps two bodies fixed together.
• Spherical: A ball-and-socket connection (e.g., for arms or chains).
• Revolute: A hinge connection (e.g., for doors or wheels).
• Prismatic: A sliding connection (e.g., for pistons).
• Rope: Limits the maximum distance between two bodies.
• Spring: Applies a force proportional to the distance between two bodies.

const WheelJoint = ({ bodyA, bodyB }) => {
  const joint = useRevoluteJoint(bodyA, bodyB, [
    [0, 0, 0],
    [0, 0, 0],
    [0, 0, 0]
  ]);

  useFrame(() => {
    if (joint.current) {
      joint.current.configureMotorVelocity(10, 2);
    }
  }, []);

  return null;
};

Rapier's return types (vectors and quaternions) are not directly compatible with Three.js. @react-three/rapier provides helper functions vec3, quat, and euler to perform these conversions quickly.

While reading values requires these helpers, you can set values (like translation or rotation) directly using Three.js types.

import { RapierRigidBody, quat, vec3, euler } from "@react-three/rapier";
import { useRef, useEffect } from "react";

const Scene = () => {
  const rigidBody = useRef<RapierRigidBody>(null);

  useEffect(() => {
    if (rigidBody.current) {
      const position = vec3(rigidBody.current.translation());
      const quaternion = quat(rigidBody.current.rotation());
      const eulerRot = euler().setFromQuaternion(
        quat(rigidBody.current.rotation())
      );

      // While Rapier's return types need conversion, setting values can be done directly with Three.js types
      rigidBody.current.setTranslation(position, true);
      rigidBody.current.setRotation(quaternion, true);
      rigidBody.current.setAngvel({ x: 0, y: 2, z: 0 }, true);
    }
  }, []);

  return (
    <RigidBody ref={rigidBody}>
      <mesh>
        <boxBufferGeometry />
        <meshStandardMaterial />
      </mesh>
    </RigidBody>
  );
};

You can perform direct physics operations on a RigidBody by accessing its underlying Rapier instance via a ref. The library exports RapierRigidBody and RapierCollider as type aliases for the underlying Rapier objects.

Common operations include:

• applyImpulse: A one-off push.
• addForce: A continuous force.
• applyTorqueImpulse: A one-off torque rotation.
• addTorque: A continuous torque.

For a full list of methods, refer to the Rapier documentation.

import { RigidBody, RapierRigidBody } from "@react-three/rapier";
import { useRef, useEffect } from "react";

const Scene = () => {
  const rigidBody = useRef<RapierRigidBody>(null);

  useEffect(() => {
    if (rigidBody.current) {
      // A one-off "push"
      rigidBody.current.applyImpulse({ x: 0, y: 10, z: 0 }, true);

      // A continuous force
      rigidBody.current.addForce({ x: 0, y: 10, z: 0 }, true);

      // A one-off torque rotation
      rigidBody.current.applyTorqueImpulse({ x: 0, y: 10, z: 0 }, true);

      // A continuous torque
      rigidBody.current.addTorque({ x: 0, y: 10, z: 0 }, true);
    }
  }, []);

  return (
    <RigidBody ref={rigidBody}>
      <mesh>
        <boxBufferGeometry />
        <meshStandardMaterial />
      </mesh>
    </RigidBody>
  );
};

When you need many identical physics objects, use <InstancedRigidBodies />. This component wraps a single Three.InstancedMesh and attaches an individual RigidBody to each instance.

Key features:

• Accessing instances: Use a ref to get an array of RapierRigidBody objects. You can then call methods like .applyImpulse() on specific indices or loop through all of them.
• Initial state: Provide an array of InstancedRigidBodyProps to the instances prop to set initial positions, rotations, and scales.
• Compound shapes: Use the colliderNodes prop to pass an array of collider components (e.g., [<BoxCollider />, <SphereCollider />]) that will be applied to every instance.

import { InstancedRigidBodies, RapierRigidBody, BoxCollider, SphereCollider } from "@react-three/rapier";

const COUNT = 500;

const Scene = () => {
  const rigidBodies = useRef<RapierRigidBody[]>(null);

  const instances = useMemo(() => {
    const items: InstancedRigidBodyProps[] = [];
    for (let i = 0; i < COUNT; i++) {
      items.push({
        key: "instance_" + Math.random(),
        position: [Math.random() * 10, Math.random() * 10, Math.random() * 10],
        rotation: [Math.random(), Math.random(), Math.random()]
      });
    }
    return items;
  }, []);

  return (
    <InstancedRigidBodies
      ref={rigidBodies}
      instances={instances}
      colliders="ball"
      colliderNodes={[
        <BoxCollider args={[0.5, 0.5, 0.5]} />,
        <SphereCollider args={[0.5]} />
      ]}
    >
      <instancedMesh args={[undefined, undefined, COUNT]} count={COUNT} />
    </InstancedRigidBodies>
  );
};