@react-three/rapier 2.1.0 → 2.2.0

package/dist/declarations/src/components/Physics.d.ts

@@ -1,5 +1,5 @@
 import type Rapier from "@dimforge/rapier3d-compat";
-import { Collider, ColliderHandle, RigidBody, RigidBodyHandle, World } from "@dimforge/rapier3d-compat";
+import { Collider, ColliderHandle, RigidBody, RigidBodyHandle, SolverFlags, World } from "@dimforge/rapier3d-compat";
 import React, { FC, ReactNode } from "react";
 import { Matrix4, Object3D, Vector3 } from "three";
 import { CollisionEnterHandler, CollisionExitHandler, ContactForceHandler, IntersectionEnterHandler, IntersectionExitHandler, RigidBodyAutoCollider, Vector3Tuple } from "../types.js";
@@ -21,6 +21,14 @@ export type WorldStepCallback = (world: World) => void;
 export type WorldStepCallbackSet = Set<{
     current: WorldStepCallback;
 }>;
+export type FilterContactPairCallback = (collider1: ColliderHandle, collider2: ColliderHandle, body1: RigidBodyHandle, body2: RigidBodyHandle) => SolverFlags | null;
+export type FilterIntersectionPairCallback = (collider1: ColliderHandle, collider2: ColliderHandle, body1: RigidBodyHandle, body2: RigidBodyHandle) => boolean;
+export type FilterContactPairCallbackSet = Set<{
+    current: FilterContactPairCallback;
+}>;
+export type FilterIntersectionPairCallbackSet = Set<{
+    current: FilterIntersectionPairCallback;
+}>;
 export interface ColliderState {
     collider: Collider;
     object: Object3D;
@@ -69,6 +77,16 @@ export interface RapierContext {
      * @internal
      */
     afterStepCallbacks: WorldStepCallbackSet;
+    /**
+     * Hooks to filter contact pairs
+     * @internal
+     */
+    filterContactPairHooks: FilterContactPairCallbackSet;
+    /**
+     * Hooks to filter intersection pairs
+     * @internal
+     */
+    filterIntersectionPairHooks: FilterIntersectionPairCallbackSet;
     /**
      * Direct access to the Rapier instance
      */
@@ -161,14 +179,6 @@ export interface PhysicsProps {
      * @defaultValue 4
      */
     numSolverIterations?: number;
-    /**
-     * Number of addition friction resolution iteration run during the last solver sub-step.
-     * The greater this value is, the most realistic friction will be.
-     * However a greater number of iterations is more computationally intensive.
-     *
-     * @defaultValue 4
-     */
-    numAdditionalFrictionIterations?: number;
     /**
      * Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration.
      * Increasing this parameter will improve stability of the simulation. It will have a lesser effect than

package/dist/declarations/src/hooks/hooks.d.ts

@@ -17,6 +17,74 @@ export declare const useBeforePhysicsStep: (callback: WorldStepCallback) => void
  * @category Hooks
  */
 export declare const useAfterPhysicsStep: (callback: WorldStepCallback) => void;
+/**
+ * Registers a callback to filter contact pairs.
+ *
+ * The callback determines if contact computation should happen between two colliders,
+ * and how the constraints solver should behave for these contacts.
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_CONTACT_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `SolverFlags.COMPUTE_IMPULSE` (1) - Process the collision normally (compute impulses and resolve penetration)
+ *   - `SolverFlags.EMPTY` (0) - Skip computing impulses for this collision pair (colliders pass through each other)
+ *   - `null` - Skip this hook; let the next registered hook decide, or use Rapier's default behavior if no hook handles it
+ *
+ * When multiple hooks are registered, they are called in order until one returns a non-null value.
+ * That value is then passed to Rapier's physics engine.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterContactPair } from '@react-three/rapier';
+ * import { SolverFlags } from '@dimforge/rapier3d-compat';
+ *
+ * useFilterContactPair((collider1, collider2, body1, body2) => {
+ *   // Only process collisions for specific bodies
+ *   if (body1 === myBodyHandle) {
+ *     return SolverFlags.COMPUTE_IMPULSE;
+ *   }
+ *   // Let other hooks or default behavior handle it
+ *   return null;
+ * });
+ * ```
+ */
+export declare const useFilterContactPair: (callback: (collider1: number, collider2: number, body1: number, body2: number) => number | null) => void;
+/**
+ * Registers a callback to filter intersection pairs.
+ *
+ * The callback determines if intersection computation should happen between two colliders
+ * (where at least one is a sensor).
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_INTERSECTION_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `true` - Allow the intersection to be detected (trigger intersection events)
+ *   - `false` - Block the intersection (no intersection events will fire)
+ *
+ * When multiple hooks are registered, the **first hook that returns `false` blocks** the intersection.
+ * If all hooks return `true`, the intersection is allowed.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterIntersectionPair } from '@react-three/rapier';
+ *
+ * useFilterIntersectionPair((collider1, collider2, body1, body2) => {
+ *   // Block intersections for specific body pairs
+ *   if (body1 === myBodyHandle && body2 === otherBodyHandle) {
+ *     return false;
+ *   }
+ *   // Allow all other intersections
+ *   return true;
+ * });
+ * ```
+ */
+export declare const useFilterIntersectionPair: (callback: (collider1: number, collider2: number, body1: number, body2: number) => boolean) => void;
 /**
  * @internal
  */

package/dist/declarations/src/index.d.ts

@@ -2,7 +2,7 @@ export * from "./types.js";
 export type { RigidBodyProps } from "./components/RigidBody.js";
 export type { InstancedRigidBodiesProps, InstancedRigidBodyProps } from "./components/InstancedRigidBodies.js";
 export type { CylinderColliderProps, BallColliderProps, CapsuleColliderProps, ConeColliderProps, ConvexHullColliderProps, CuboidColliderProps, HeightfieldColliderProps, RoundCuboidColliderProps, TrimeshColliderProps, ColliderOptionsRequiredArgs } from "./components/AnyCollider.js";
-export type { PhysicsProps, RapierContext, WorldStepCallback } from "./components/Physics.js";
+export type { PhysicsProps, RapierContext, WorldStepCallback, FilterContactPairCallback, FilterIntersectionPairCallback } from "./components/Physics.js";
 export type { MeshColliderProps } from "./components/MeshCollider.js";
 export { Physics } from "./components/Physics.js";
 export { RigidBody } from "./components/RigidBody.js";
@@ -10,6 +10,6 @@ export { MeshCollider } from "./components/MeshCollider.js";
 export { InstancedRigidBodies } from "./components/InstancedRigidBodies.js";
 export * from "./components/AnyCollider.js";
 export * from "./hooks/joints.js";
-export { useRapier, useBeforePhysicsStep, useAfterPhysicsStep } from "./hooks/hooks.js";
+export { useRapier, useBeforePhysicsStep, useAfterPhysicsStep, useFilterContactPair, useFilterIntersectionPair } from "./hooks/hooks.js";
 export * from "./utils/interaction-groups.js";
 export * from "./utils/three-object-helpers.js";

package/dist/react-three-rapier.cjs.dev.js

@@ -580,6 +580,98 @@ const useAfterPhysicsStep = callback => {
   }, []);
 };
 
+/**
+ * Registers a callback to filter contact pairs.
+ *
+ * The callback determines if contact computation should happen between two colliders,
+ * and how the constraints solver should behave for these contacts.
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_CONTACT_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `SolverFlags.COMPUTE_IMPULSE` (1) - Process the collision normally (compute impulses and resolve penetration)
+ *   - `SolverFlags.EMPTY` (0) - Skip computing impulses for this collision pair (colliders pass through each other)
+ *   - `null` - Skip this hook; let the next registered hook decide, or use Rapier's default behavior if no hook handles it
+ *
+ * When multiple hooks are registered, they are called in order until one returns a non-null value.
+ * That value is then passed to Rapier's physics engine.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterContactPair } from '@react-three/rapier';
+ * import { SolverFlags } from '@dimforge/rapier3d-compat';
+ *
+ * useFilterContactPair((collider1, collider2, body1, body2) => {
+ *   // Only process collisions for specific bodies
+ *   if (body1 === myBodyHandle) {
+ *     return SolverFlags.COMPUTE_IMPULSE;
+ *   }
+ *   // Let other hooks or default behavior handle it
+ *   return null;
+ * });
+ * ```
+ */
+const useFilterContactPair = callback => {
+  const {
+    filterContactPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  React.useEffect(() => {
+    filterContactPairHooks.add(ref);
+    return () => {
+      filterContactPairHooks.delete(ref);
+    };
+  }, []);
+};
+
+/**
+ * Registers a callback to filter intersection pairs.
+ *
+ * The callback determines if intersection computation should happen between two colliders
+ * (where at least one is a sensor).
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_INTERSECTION_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `true` - Allow the intersection to be detected (trigger intersection events)
+ *   - `false` - Block the intersection (no intersection events will fire)
+ *
+ * When multiple hooks are registered, the **first hook that returns `false` blocks** the intersection.
+ * If all hooks return `true`, the intersection is allowed.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterIntersectionPair } from '@react-three/rapier';
+ *
+ * useFilterIntersectionPair((collider1, collider2, body1, body2) => {
+ *   // Block intersections for specific body pairs
+ *   if (body1 === myBodyHandle && body2 === otherBodyHandle) {
+ *     return false;
+ *   }
+ *   // Allow all other intersections
+ *   return true;
+ * });
+ * ```
+ */
+const useFilterIntersectionPair = callback => {
+  const {
+    filterIntersectionPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  React.useEffect(() => {
+    filterIntersectionPairHooks.add(ref);
+    return () => {
+      filterIntersectionPairHooks.delete(ref);
+    };
+  }, []);
+};
+
 // Internal hooks
 /**
  * @internal
@@ -708,7 +800,6 @@ const Physics = props => {
     allowedLinearError = 0.001,
     predictionDistance = 0.002,
     numSolverIterations = 4,
-    numAdditionalFrictionIterations = 4,
     numInternalPgsIterations = 1,
     minIslandSize = 128,
     maxCcdSubsteps = 1,
@@ -724,6 +815,24 @@ const Physics = props => {
   const rigidBodyEvents = useConst(() => new Map());
   const colliderEvents = useConst(() => new Map());
   const eventQueue = useConst(() => new rapier3dCompat.EventQueue(false));
+  const filterContactPairHooks = useConst(() => new Set());
+  const filterIntersectionPairHooks = useConst(() => new Set());
+  const hooks = useConst(() => ({
+    filterContactPair: (...args) => {
+      for (const hook of filterContactPairHooks) {
+        const result = hook.current(...args);
+        if (result !== null) return result;
+      }
+      return null;
+    },
+    filterIntersectionPair: (...args) => {
+      for (const hook of filterIntersectionPairHooks) {
+        const result = hook.current(...args);
+        if (result === false) return false;
+      }
+      return true;
+    }
+  }));
   const beforeStepCallbacks = useConst(() => new Set());
   const afterStepCallbacks = useConst(() => new Set());
 
@@ -748,7 +857,6 @@ const Physics = props => {
   React.useEffect(() => {
     worldProxy.gravity = vector3ToRapierVector(gravity);
     worldProxy.integrationParameters.numSolverIterations = numSolverIterations;
-    worldProxy.integrationParameters.numAdditionalFrictionIterations = numAdditionalFrictionIterations;
     worldProxy.integrationParameters.numInternalPgsIterations = numInternalPgsIterations;
     worldProxy.integrationParameters.normalizedAllowedLinearError = allowedLinearError;
     worldProxy.integrationParameters.minIslandSize = minIslandSize;
@@ -756,7 +864,7 @@ const Physics = props => {
     worldProxy.integrationParameters.normalizedPredictionDistance = predictionDistance;
     worldProxy.lengthUnit = lengthUnit;
     worldProxy.integrationParameters.contact_natural_frequency = contactNaturalFrequency;
-  }, [worldProxy, ...gravity, numSolverIterations, numAdditionalFrictionIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
+  }, [worldProxy, ...gravity, numSolverIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
   const getSourceFromColliderHandle = React.useCallback(handle => {
     var _collider$parent;
     const collider = worldProxy.getCollider(handle);
@@ -803,7 +911,8 @@ const Physics = props => {
         callback.current(world);
       });
       world.timestep = delta;
-      world.step(eventQueue);
+      const hasHooks = filterContactPairHooks.size > 0 || filterIntersectionPairHooks.size > 0;
+      world.step(eventQueue, hasHooks ? hooks : undefined);
 
       // Trigger afterStep callbacks
       afterStepCallbacks.forEach(callback => {
@@ -994,7 +1103,9 @@ const Physics = props => {
     afterStepCallbacks,
     isPaused: paused,
     isDebug: debug,
-    step
+    step,
+    filterContactPairHooks,
+    filterIntersectionPairHooks
   }), [paused, step, debug, colliders, gravity]);
   const stepCallback = React.useCallback(delta => {
     if (!paused) {
@@ -1812,6 +1923,8 @@ exports.interactionGroups = interactionGroups;
 exports.quat = quat;
 exports.useAfterPhysicsStep = useAfterPhysicsStep;
 exports.useBeforePhysicsStep = useBeforePhysicsStep;
+exports.useFilterContactPair = useFilterContactPair;
+exports.useFilterIntersectionPair = useFilterIntersectionPair;
 exports.useFixedJoint = useFixedJoint;
 exports.useImpulseJoint = useImpulseJoint;
 exports.usePrismaticJoint = usePrismaticJoint;

package/dist/react-three-rapier.cjs.prod.js

@@ -580,6 +580,98 @@ const useAfterPhysicsStep = callback => {
   }, []);
 };
 
+/**
+ * Registers a callback to filter contact pairs.
+ *
+ * The callback determines if contact computation should happen between two colliders,
+ * and how the constraints solver should behave for these contacts.
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_CONTACT_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `SolverFlags.COMPUTE_IMPULSE` (1) - Process the collision normally (compute impulses and resolve penetration)
+ *   - `SolverFlags.EMPTY` (0) - Skip computing impulses for this collision pair (colliders pass through each other)
+ *   - `null` - Skip this hook; let the next registered hook decide, or use Rapier's default behavior if no hook handles it
+ *
+ * When multiple hooks are registered, they are called in order until one returns a non-null value.
+ * That value is then passed to Rapier's physics engine.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterContactPair } from '@react-three/rapier';
+ * import { SolverFlags } from '@dimforge/rapier3d-compat';
+ *
+ * useFilterContactPair((collider1, collider2, body1, body2) => {
+ *   // Only process collisions for specific bodies
+ *   if (body1 === myBodyHandle) {
+ *     return SolverFlags.COMPUTE_IMPULSE;
+ *   }
+ *   // Let other hooks or default behavior handle it
+ *   return null;
+ * });
+ * ```
+ */
+const useFilterContactPair = callback => {
+  const {
+    filterContactPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  React.useEffect(() => {
+    filterContactPairHooks.add(ref);
+    return () => {
+      filterContactPairHooks.delete(ref);
+    };
+  }, []);
+};
+
+/**
+ * Registers a callback to filter intersection pairs.
+ *
+ * The callback determines if intersection computation should happen between two colliders
+ * (where at least one is a sensor).
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_INTERSECTION_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `true` - Allow the intersection to be detected (trigger intersection events)
+ *   - `false` - Block the intersection (no intersection events will fire)
+ *
+ * When multiple hooks are registered, the **first hook that returns `false` blocks** the intersection.
+ * If all hooks return `true`, the intersection is allowed.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterIntersectionPair } from '@react-three/rapier';
+ *
+ * useFilterIntersectionPair((collider1, collider2, body1, body2) => {
+ *   // Block intersections for specific body pairs
+ *   if (body1 === myBodyHandle && body2 === otherBodyHandle) {
+ *     return false;
+ *   }
+ *   // Allow all other intersections
+ *   return true;
+ * });
+ * ```
+ */
+const useFilterIntersectionPair = callback => {
+  const {
+    filterIntersectionPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  React.useEffect(() => {
+    filterIntersectionPairHooks.add(ref);
+    return () => {
+      filterIntersectionPairHooks.delete(ref);
+    };
+  }, []);
+};
+
 // Internal hooks
 /**
  * @internal
@@ -708,7 +800,6 @@ const Physics = props => {
     allowedLinearError = 0.001,
     predictionDistance = 0.002,
     numSolverIterations = 4,
-    numAdditionalFrictionIterations = 4,
     numInternalPgsIterations = 1,
     minIslandSize = 128,
     maxCcdSubsteps = 1,
@@ -724,6 +815,24 @@ const Physics = props => {
   const rigidBodyEvents = useConst(() => new Map());
   const colliderEvents = useConst(() => new Map());
   const eventQueue = useConst(() => new rapier3dCompat.EventQueue(false));
+  const filterContactPairHooks = useConst(() => new Set());
+  const filterIntersectionPairHooks = useConst(() => new Set());
+  const hooks = useConst(() => ({
+    filterContactPair: (...args) => {
+      for (const hook of filterContactPairHooks) {
+        const result = hook.current(...args);
+        if (result !== null) return result;
+      }
+      return null;
+    },
+    filterIntersectionPair: (...args) => {
+      for (const hook of filterIntersectionPairHooks) {
+        const result = hook.current(...args);
+        if (result === false) return false;
+      }
+      return true;
+    }
+  }));
   const beforeStepCallbacks = useConst(() => new Set());
   const afterStepCallbacks = useConst(() => new Set());
 
@@ -748,7 +857,6 @@ const Physics = props => {
   React.useEffect(() => {
     worldProxy.gravity = vector3ToRapierVector(gravity);
     worldProxy.integrationParameters.numSolverIterations = numSolverIterations;
-    worldProxy.integrationParameters.numAdditionalFrictionIterations = numAdditionalFrictionIterations;
     worldProxy.integrationParameters.numInternalPgsIterations = numInternalPgsIterations;
     worldProxy.integrationParameters.normalizedAllowedLinearError = allowedLinearError;
     worldProxy.integrationParameters.minIslandSize = minIslandSize;
@@ -756,7 +864,7 @@ const Physics = props => {
     worldProxy.integrationParameters.normalizedPredictionDistance = predictionDistance;
     worldProxy.lengthUnit = lengthUnit;
     worldProxy.integrationParameters.contact_natural_frequency = contactNaturalFrequency;
-  }, [worldProxy, ...gravity, numSolverIterations, numAdditionalFrictionIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
+  }, [worldProxy, ...gravity, numSolverIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
   const getSourceFromColliderHandle = React.useCallback(handle => {
     var _collider$parent;
     const collider = worldProxy.getCollider(handle);
@@ -803,7 +911,8 @@ const Physics = props => {
         callback.current(world);
       });
       world.timestep = delta;
-      world.step(eventQueue);
+      const hasHooks = filterContactPairHooks.size > 0 || filterIntersectionPairHooks.size > 0;
+      world.step(eventQueue, hasHooks ? hooks : undefined);
 
       // Trigger afterStep callbacks
       afterStepCallbacks.forEach(callback => {
@@ -994,7 +1103,9 @@ const Physics = props => {
     afterStepCallbacks,
     isPaused: paused,
     isDebug: debug,
-    step
+    step,
+    filterContactPairHooks,
+    filterIntersectionPairHooks
   }), [paused, step, debug, colliders, gravity]);
   const stepCallback = React.useCallback(delta => {
     if (!paused) {
@@ -1812,6 +1923,8 @@ exports.interactionGroups = interactionGroups;
 exports.quat = quat;
 exports.useAfterPhysicsStep = useAfterPhysicsStep;
 exports.useBeforePhysicsStep = useBeforePhysicsStep;
+exports.useFilterContactPair = useFilterContactPair;
+exports.useFilterIntersectionPair = useFilterIntersectionPair;
 exports.useFixedJoint = useFixedJoint;
 exports.useImpulseJoint = useImpulseJoint;
 exports.usePrismaticJoint = usePrismaticJoint;

package/dist/react-three-rapier.esm.js

@@ -555,6 +555,98 @@ const useAfterPhysicsStep = callback => {
   }, []);
 };
 
+/**
+ * Registers a callback to filter contact pairs.
+ *
+ * The callback determines if contact computation should happen between two colliders,
+ * and how the constraints solver should behave for these contacts.
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_CONTACT_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `SolverFlags.COMPUTE_IMPULSE` (1) - Process the collision normally (compute impulses and resolve penetration)
+ *   - `SolverFlags.EMPTY` (0) - Skip computing impulses for this collision pair (colliders pass through each other)
+ *   - `null` - Skip this hook; let the next registered hook decide, or use Rapier's default behavior if no hook handles it
+ *
+ * When multiple hooks are registered, they are called in order until one returns a non-null value.
+ * That value is then passed to Rapier's physics engine.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterContactPair } from '@react-three/rapier';
+ * import { SolverFlags } from '@dimforge/rapier3d-compat';
+ *
+ * useFilterContactPair((collider1, collider2, body1, body2) => {
+ *   // Only process collisions for specific bodies
+ *   if (body1 === myBodyHandle) {
+ *     return SolverFlags.COMPUTE_IMPULSE;
+ *   }
+ *   // Let other hooks or default behavior handle it
+ *   return null;
+ * });
+ * ```
+ */
+const useFilterContactPair = callback => {
+  const {
+    filterContactPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  useEffect(() => {
+    filterContactPairHooks.add(ref);
+    return () => {
+      filterContactPairHooks.delete(ref);
+    };
+  }, []);
+};
+
+/**
+ * Registers a callback to filter intersection pairs.
+ *
+ * The callback determines if intersection computation should happen between two colliders
+ * (where at least one is a sensor).
+ *
+ * This will only be executed if at least one of the involved colliders contains the
+ * `ActiveHooks.FILTER_INTERSECTION_PAIR` flag in its active hooks.
+ *
+ * @param callback - Function that returns:
+ *   - `true` - Allow the intersection to be detected (trigger intersection events)
+ *   - `false` - Block the intersection (no intersection events will fire)
+ *
+ * When multiple hooks are registered, the **first hook that returns `false` blocks** the intersection.
+ * If all hooks return `true`, the intersection is allowed.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * import { useFilterIntersectionPair } from '@react-three/rapier';
+ *
+ * useFilterIntersectionPair((collider1, collider2, body1, body2) => {
+ *   // Block intersections for specific body pairs
+ *   if (body1 === myBodyHandle && body2 === otherBodyHandle) {
+ *     return false;
+ *   }
+ *   // Allow all other intersections
+ *   return true;
+ * });
+ * ```
+ */
+const useFilterIntersectionPair = callback => {
+  const {
+    filterIntersectionPairHooks
+  } = useRapier();
+  const ref = useMutableCallback(callback);
+  useEffect(() => {
+    filterIntersectionPairHooks.add(ref);
+    return () => {
+      filterIntersectionPairHooks.delete(ref);
+    };
+  }, []);
+};
+
 // Internal hooks
 /**
  * @internal
@@ -683,7 +775,6 @@ const Physics = props => {
     allowedLinearError = 0.001,
     predictionDistance = 0.002,
     numSolverIterations = 4,
-    numAdditionalFrictionIterations = 4,
     numInternalPgsIterations = 1,
     minIslandSize = 128,
     maxCcdSubsteps = 1,
@@ -699,6 +790,24 @@ const Physics = props => {
   const rigidBodyEvents = useConst(() => new Map());
   const colliderEvents = useConst(() => new Map());
   const eventQueue = useConst(() => new EventQueue(false));
+  const filterContactPairHooks = useConst(() => new Set());
+  const filterIntersectionPairHooks = useConst(() => new Set());
+  const hooks = useConst(() => ({
+    filterContactPair: (...args) => {
+      for (const hook of filterContactPairHooks) {
+        const result = hook.current(...args);
+        if (result !== null) return result;
+      }
+      return null;
+    },
+    filterIntersectionPair: (...args) => {
+      for (const hook of filterIntersectionPairHooks) {
+        const result = hook.current(...args);
+        if (result === false) return false;
+      }
+      return true;
+    }
+  }));
   const beforeStepCallbacks = useConst(() => new Set());
   const afterStepCallbacks = useConst(() => new Set());
 
@@ -723,7 +832,6 @@ const Physics = props => {
   useEffect(() => {
     worldProxy.gravity = vector3ToRapierVector(gravity);
     worldProxy.integrationParameters.numSolverIterations = numSolverIterations;
-    worldProxy.integrationParameters.numAdditionalFrictionIterations = numAdditionalFrictionIterations;
     worldProxy.integrationParameters.numInternalPgsIterations = numInternalPgsIterations;
     worldProxy.integrationParameters.normalizedAllowedLinearError = allowedLinearError;
     worldProxy.integrationParameters.minIslandSize = minIslandSize;
@@ -731,7 +839,7 @@ const Physics = props => {
     worldProxy.integrationParameters.normalizedPredictionDistance = predictionDistance;
     worldProxy.lengthUnit = lengthUnit;
     worldProxy.integrationParameters.contact_natural_frequency = contactNaturalFrequency;
-  }, [worldProxy, ...gravity, numSolverIterations, numAdditionalFrictionIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
+  }, [worldProxy, ...gravity, numSolverIterations, numInternalPgsIterations, allowedLinearError, minIslandSize, maxCcdSubsteps, predictionDistance, lengthUnit, contactNaturalFrequency]);
   const getSourceFromColliderHandle = useCallback(handle => {
     var _collider$parent;
     const collider = worldProxy.getCollider(handle);
@@ -778,7 +886,8 @@ const Physics = props => {
         callback.current(world);
       });
       world.timestep = delta;
-      world.step(eventQueue);
+      const hasHooks = filterContactPairHooks.size > 0 || filterIntersectionPairHooks.size > 0;
+      world.step(eventQueue, hasHooks ? hooks : undefined);
 
       // Trigger afterStep callbacks
       afterStepCallbacks.forEach(callback => {
@@ -969,7 +1078,9 @@ const Physics = props => {
     afterStepCallbacks,
     isPaused: paused,
     isDebug: debug,
-    step
+    step,
+    filterContactPairHooks,
+    filterIntersectionPairHooks
   }), [paused, step, debug, colliders, gravity]);
   const stepCallback = useCallback(delta => {
     if (!paused) {
@@ -1754,4 +1865,4 @@ const useSpringJoint = (body1, body2, [body1Anchor, body2Anchor, restLength, sti
 const interactionGroups = (memberships, filters) => (bitmask(memberships) << 16) + (filters !== undefined ? bitmask(filters) : 0b1111111111111111);
 const bitmask = groups => [groups].flat().reduce((acc, layer) => acc | 1 << layer, 0);
 
-export { AnyCollider, BallCollider, CapsuleCollider, ConeCollider, ConvexHullCollider, CuboidCollider, CylinderCollider, HeightfieldCollider, InstancedRigidBodies, MeshCollider, Physics, RigidBody, RoundConeCollider, RoundCuboidCollider, RoundCylinderCollider, TrimeshCollider, euler, interactionGroups, quat, useAfterPhysicsStep, useBeforePhysicsStep, useFixedJoint, useImpulseJoint, usePrismaticJoint, useRapier, useRevoluteJoint, useRopeJoint, useSphericalJoint, useSpringJoint, vec3 };
+export { AnyCollider, BallCollider, CapsuleCollider, ConeCollider, ConvexHullCollider, CuboidCollider, CylinderCollider, HeightfieldCollider, InstancedRigidBodies, MeshCollider, Physics, RigidBody, RoundConeCollider, RoundCuboidCollider, RoundCylinderCollider, TrimeshCollider, euler, interactionGroups, quat, useAfterPhysicsStep, useBeforePhysicsStep, useFilterContactPair, useFilterIntersectionPair, useFixedJoint, useImpulseJoint, usePrismaticJoint, useRapier, useRevoluteJoint, useRopeJoint, useSphericalJoint, useSpringJoint, vec3 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/rapier",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "source": "src/index.ts",
   "main": "dist/react-three-rapier.cjs.js",
   "module": "dist/react-three-rapier.esm.js",
@@ -25,7 +25,7 @@
     "three": ">=0.159.0"
   },
   "dependencies": {
-    "@dimforge/rapier3d-compat": "0.15.0",
+    "@dimforge/rapier3d-compat": "0.19.2",
     "suspend-react": "^0.1.3",
     "three-stdlib": "^2.35.12"
   },

package/readme.md

@@ -2,6 +2,11 @@
   <a href="#"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/hero.svg" alt="@react-three/rapier" /></a>
 </p>
 
+<p align="center">
+📣 @react-three/rapier v2 has been released, which adds support for @react-three/fiber v9 and react v19. If you are using react v18, you will need to use @react-three/rapier v1 and @react-three/fiber v8.
+</p>
+
+
 <p align="center">
   <a href="https://www.npmjs.com/package/@react-three/rapier"><img src="https://img.shields.io/npm/v/@react-three/rapier?style=for-the-badge&colorA=0099DA&colorB=ffffff" /></a>
   <a href="https://discord.gg/ZZjjNvJ"><img src="https://img.shields.io/discord/740090768164651008?style=for-the-badge&colorA=0099DA&colorB=ffffff&label=discord&logo=discord&logoColor=ffffff" /></a>
@@ -80,6 +85,7 @@ For full API outline and documentation, see 🧩 [API Docs](https://pmndrs.githu
   - [Spring Joint](#spring-joint)
   - [🖼 Joints Example](#-joints-example)
 - [Advanced hooks usage](#advanced-hooks-usage)
+  - [Physics Hooks (Collision Filtering)](#physics-hooks-collision-filtering)
   - [Manual stepping](#manual-stepping)
   - [On-demand rendering](#on-demand-rendering)
 - [Snapshots](#snapshots)
@@ -881,6 +887,95 @@ Advanced users might need granular access to the physics loop and direct access
   Allows you to run code after the physics simulation is stepped.  
   🧩 See [useAfterPhysicsStep docs](https://pmndrs.github.io/react-three-rapier/functions/useAfterPhysicsStep.html) for more information.
 
+### Physics Hooks (Collision Filtering)
+
+You can implement advanced collision behaviors like one-way platforms by using physics hooks. These hooks allow you to filter collision and intersection pairs during the physics step.
+
+`r3/rapier` provides two hooks for collision filtering:
+- `useFilterContactPair` - Filter collision pairs and control solver behavior
+- `useFilterIntersectionPair` - Filter intersection pairs for sensors
+
+#### Filter Contact Pairs
+
+`useFilterContactPair` allows you to control how collisions are processed. The callback should return:
+- `SolverFlags.COMPUTE_IMPULSE` (1) - Process the collision normally
+- `SolverFlags.EMPTY` (0) - Ignore the collision
+- `null` - Let other hooks decide, or use default behavior
+
+#### Filter Intersection Pairs  
+
+`useFilterIntersectionPair` controls which sensor intersections are detected. The callback should return:
+- `true` - Allow the intersection to be detected
+- `false` - Block the intersection
+
+If multiple hooks are registered:
+- For contact pairs, the **first hook that returns non-null wins**
+- For intersection pairs, the **first hook that returns false blocks** the intersection
+
+**Important:** To avoid Rust aliasing errors, you **cannot** access rigid body properties (like `translation()` or `linvel()`) directly during the physics step. Instead, cache the needed state before the step using `useBeforePhysicsStep`.
+
+🧩 See [useFilterContactPair docs](https://pmndrs.github.io/react-three-rapier/functions/useFilterContactPair.html) and [useFilterIntersectionPair docs](https://pmndrs.github.io/react-three-rapier/functions/useFilterIntersectionPair.html) for more information.
+
+```tsx
+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);
+  
+  // Cache for storing body states before physics step
+  const bodyStateCache = useRef(new Map());
+  
+  const { rapier } = useRapier();
+
+  // Cache body states BEFORE the physics step
+  useBeforePhysicsStep(() => {
+    if (platformRef.current && ballRef.current) {
+      const ballPos = ballRef.current.translation();
+      const ballVel = ballRef.current.linvel();
+
+      bodyStateCache.current.set(ballRef.current.handle, {
+        position: ballPos,
+        velocity: ballVel
+      });
+    }
+  });
+
+  // Filter collisions using cached data
+  useFilterContactPair((collider1, collider2, body1, body2) => {
+    const ballState = bodyStateCache.current.get(body1);
+    if (!ballState) return null; // Let other hooks or default behavior handle it
+
+    // Allow collision only if ball is moving down and above platform
+    if (ballState.velocity.y < 0 && ballState.position.y > 0) {
+      return rapier.SolverFlags.COMPUTE_IMPULSE; // Process collision
+    }
+    return rapier.SolverFlags.EMPTY; // Ignore collision
+  });
+
+  useEffect(() => {
+    // Enable active hooks on the collider (required for filtering)
+    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>
+    </>
+  );
+};
+```
+
 ### Manual stepping
 
 You can manually step the physics simulation by calling the `step` method from the `useRapier` hook.
@@ -939,4 +1034,4 @@ const SnapshottingComponent = () => {
     <Rigidbody>...</RigidBody>
   </>
 }
-```
+```