react-three-rapier-unified 1.0.0

package/src/components/RigidBody.tsx

@@ -0,0 +1,153 @@
+import React, {
+  createContext,
+  forwardRef,
+  memo,
+  ReactNode,
+  Ref,
+  RefObject,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef
+} from "react";
+import { Object3D } from "three";
+import { useChildColliderProps, useRapier } from "../hooks/hooks";
+import { useForwardedRef } from "../hooks/use-forwarded-ref";
+import { useImperativeInstance } from "../hooks/use-imperative-instance";
+import { RapierRigidBody, RigidBodyOptions } from "../types";
+import {
+  createRigidBodyState,
+  immutableRigidBodyOptions,
+  rigidBodyDescFromOptions,
+  useRigidBodyEvents,
+  useUpdateRigidBodyOptions
+} from "../utils/utils-rigidbody";
+import { AnyCollider } from "./AnyCollider";
+
+type RigidBodyContextType = {
+  ref: RefObject<Object3D>;
+  getRigidBody: () => RapierRigidBody;
+  options: RigidBodyOptions;
+};
+
+export const RigidBodyContext = createContext<RigidBodyContextType>(undefined!);
+
+export const useRigidBodyContext = () => useContext(RigidBodyContext);
+
+export interface RigidBodyProps extends RigidBodyOptions {
+  children?: ReactNode;
+  ref?: Ref<RapierRigidBody>;
+}
+
+/**
+ * A rigid body is a physical object that can be simulated by the physics engine.
+ * @category Components
+ */
+export const RigidBody = memo((props: RigidBodyProps) => {
+  const {
+    ref,
+    children,
+
+    type,
+    position,
+    rotation,
+    scale,
+
+    quaternion,
+    transformState,
+    ...objectProps
+  } = props;
+
+  const objectRef = useRef<Object3D>(null);
+  const rigidBodyRef = useForwardedRef(ref);
+  const { world, rigidBodyStates, physicsOptions, rigidBodyEvents } =
+    useRapier();
+
+  const mergedOptions = useMemo(() => {
+    return {
+      ...physicsOptions,
+      ...props,
+      children: undefined
+    };
+  }, [physicsOptions, props]);
+
+  const immutablePropArray = immutableRigidBodyOptions.flatMap((key) => {
+    return Array.isArray(mergedOptions[key])
+      ? [...mergedOptions[key]]
+      : mergedOptions[key];
+  });
+
+  const childColliderProps = useChildColliderProps(objectRef, mergedOptions);
+
+  // Provide a way to eagerly create rigidbody
+  const getRigidBody = useImperativeInstance(
+    () => {
+      const desc = rigidBodyDescFromOptions(mergedOptions);
+      const rigidBody = world.createRigidBody(desc);
+
+      if (typeof ref === "function") {
+        ref(rigidBody);
+      }
+      rigidBodyRef.current = rigidBody;
+
+      return rigidBody;
+    },
+    (rigidBody) => {
+      if (world.getRigidBody(rigidBody.handle)) {
+        world.removeRigidBody(rigidBody);
+      }
+    },
+    immutablePropArray
+  );
+
+  // Only provide a object state after the ref has been set
+  useEffect(() => {
+    const rigidBody = getRigidBody();
+
+    const state = createRigidBodyState({
+      rigidBody,
+      object: objectRef.current!
+    });
+
+    rigidBodyStates.set(
+      rigidBody.handle,
+      props.transformState ? props.transformState(state) : state
+    );
+
+    return () => {
+      rigidBodyStates.delete(rigidBody.handle);
+    };
+  }, [getRigidBody]);
+
+  useUpdateRigidBodyOptions(getRigidBody, mergedOptions, rigidBodyStates);
+  useRigidBodyEvents(getRigidBody, mergedOptions, rigidBodyEvents);
+
+  const contextValue = useMemo(() => {
+    return {
+      ref: objectRef as RigidBodyContextType["ref"],
+      getRigidBody: getRigidBody,
+      options: mergedOptions
+    };
+  }, [getRigidBody]);
+
+  return (
+    <RigidBodyContext.Provider value={contextValue}>
+      <object3D
+        ref={objectRef}
+        {...objectProps}
+        position={position}
+        rotation={rotation}
+        quaternion={quaternion}
+        scale={scale}
+      >
+        {children}
+
+        {childColliderProps.map((colliderProps, index) => (
+          <AnyCollider key={index} {...colliderProps} />
+        ))}
+      </object3D>
+    </RigidBodyContext.Provider>
+  );
+});
+
+RigidBody.displayName = "RigidBody";

package/src/hooks/hooks.ts

@@ -0,0 +1,211 @@
+import React, {
+  RefObject,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import {
+  rapierContext,
+  RapierContext,
+  WorldStepCallback
+} from "../components/Physics";
+import { Object3D } from "three";
+
+import { ColliderProps, RigidBodyProps } from "..";
+import { createColliderPropsFromChildren } from "../utils/utils-collider";
+
+// Utils
+const useMutableCallback = <T>(fn: T) => {
+  const ref = useRef<T>(fn);
+  useEffect(() => {
+    ref.current = fn;
+  }, [fn]);
+  return ref;
+};
+
+// External hooks
+/**
+ * Exposes the Rapier context, and world
+ * @category Hooks
+ */
+export const useRapier = (): RapierContext => {
+  const rapier = useContext(rapierContext);
+  if (!rapier)
+    throw new Error(
+      "react-three-rapier: useRapier must be used within <Physics />!"
+    );
+  return rapier;
+};
+
+/**
+ * Registers a callback to be called before the physics step
+ * @category Hooks
+ */
+export const useBeforePhysicsStep = (callback: WorldStepCallback) => {
+  const { beforeStepCallbacks } = useRapier();
+
+  const ref = useMutableCallback(callback);
+
+  useEffect(() => {
+    beforeStepCallbacks.add(ref);
+
+    return () => {
+      beforeStepCallbacks.delete(ref);
+    };
+  }, []);
+};
+
+/**
+ * Registers a callback to be called after the physics step
+ * @category Hooks
+ */
+export const useAfterPhysicsStep = (callback: WorldStepCallback) => {
+  const { afterStepCallbacks } = useRapier();
+
+  const ref = useMutableCallback(callback);
+
+  useEffect(() => {
+    afterStepCallbacks.add(ref);
+
+    return () => {
+      afterStepCallbacks.delete(ref);
+    };
+  }, []);
+};
+
+/**
+ * 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 const useFilterContactPair = (
+  callback: (
+    collider1: number,
+    collider2: number,
+    body1: number,
+    body2: number
+  ) => number | null
+) => {
+  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;
+ * });
+ * ```
+ */
+export const useFilterIntersectionPair = (
+  callback: (
+    collider1: number,
+    collider2: number,
+    body1: number,
+    body2: number
+  ) => boolean
+) => {
+  const { filterIntersectionPairHooks } = useRapier();
+
+  const ref = useMutableCallback(callback);
+
+  useEffect(() => {
+    filterIntersectionPairHooks.add(ref);
+
+    return () => {
+      filterIntersectionPairHooks.delete(ref);
+    };
+  }, []);
+};
+
+// Internal hooks
+/**
+ * @internal
+ */
+export const useChildColliderProps = <O extends Object3D>(
+  ref: RefObject<O | undefined | null>,
+  options: RigidBodyProps,
+  ignoreMeshColliders = true
+) => {
+  const [colliderProps, setColliderProps] = useState<ColliderProps[]>([]);
+
+  useEffect(() => {
+    const object = ref.current;
+
+    if (object && options.colliders !== false) {
+      setColliderProps(
+        createColliderPropsFromChildren({
+          object: ref.current!,
+          options,
+          ignoreMeshColliders
+        })
+      );
+    }
+  }, [options.colliders]);
+
+  return colliderProps;
+};

package/src/hooks/joints.ts

@@ -0,0 +1,221 @@
+import {
+  FixedImpulseJoint,
+  ImpulseJoint,
+  PrismaticImpulseJoint,
+  RevoluteImpulseJoint,
+  RopeImpulseJoint,
+  SphericalImpulseJoint,
+  SpringImpulseJoint
+} from "@dimforge/rapier3d-compat";
+import { RefObject, useRef } from "react";
+import {
+  FixedJointParams,
+  PrismaticJointParams,
+  RapierRigidBody,
+  RevoluteJointParams,
+  RopeJointParams,
+  SphericalJointParams,
+  SpringJointParams,
+  UseImpulseJoint,
+  useRapier
+} from "..";
+import {
+  vector3ToRapierVector,
+  quaternionToRapierQuaternion
+} from "../utils/utils";
+
+import type Rapier from "@dimforge/rapier3d-compat";
+import { useImperativeInstance } from "./use-imperative-instance";
+
+/**
+ * @internal
+ */
+export const useImpulseJoint = <JointType extends ImpulseJoint>(
+  body1: RefObject<RapierRigidBody>,
+  body2: RefObject<RapierRigidBody>,
+  params: Rapier.JointData
+) => {
+  const { world } = useRapier();
+  const jointRef = useRef<JointType | undefined>(undefined);
+
+  useImperativeInstance(
+    () => {
+      if (body1.current && body2.current) {
+        const newJoint = world.createImpulseJoint(
+          params,
+          body1.current,
+          body2.current,
+          true
+        ) as JointType;
+
+        jointRef.current = newJoint;
+
+        return newJoint;
+      }
+    },
+    (joint) => {
+      if (joint) {
+        jointRef.current = undefined;
+        if (world.getImpulseJoint(joint.handle)) {
+          world.removeImpulseJoint(joint, true);
+        }
+      }
+    },
+    []
+  );
+
+  return jointRef;
+};
+
+/**
+ * A fixed joint ensures that two rigid-bodies don't move relative to each other.
+ * Fixed joints are characterized by one local frame (represented by an isometry) on each rigid-body.
+ * The fixed-joint makes these frames coincide in world-space.
+ *
+ * @category Hooks - Joints
+ */
+export const useFixedJoint: UseImpulseJoint<
+  FixedJointParams,
+  FixedImpulseJoint
+> = (
+  body1,
+  body2,
+  [body1Anchor, body1LocalFrame, body2Anchor, body2LocalFrame]
+) => {
+  const { rapier } = useRapier();
+
+  return useImpulseJoint<FixedImpulseJoint>(
+    body1,
+    body2,
+    rapier.JointData.fixed(
+      vector3ToRapierVector(body1Anchor),
+      quaternionToRapierQuaternion(body1LocalFrame),
+      vector3ToRapierVector(body2Anchor),
+      quaternionToRapierQuaternion(body2LocalFrame)
+    )
+  );
+};
+
+/**
+ * The spherical joint ensures that two points on the local-spaces of two rigid-bodies always coincide (it prevents any relative
+ * translational motion at this points). This is typically used to simulate ragdolls arms, pendulums, etc.
+ * They are characterized by one local anchor on each rigid-body. Each anchor represents the location of the
+ * points that need to coincide on the local-space of each rigid-body.
+ *
+ * @category Hooks - Joints
+ */
+export const useSphericalJoint: UseImpulseJoint<
+  SphericalJointParams,
+  SphericalImpulseJoint
+> = (body1, body2, [body1Anchor, body2Anchor]) => {
+  const { rapier } = useRapier();
+
+  return useImpulseJoint<SphericalImpulseJoint>(
+    body1,
+    body2,
+    rapier.JointData.spherical(
+      vector3ToRapierVector(body1Anchor),
+      vector3ToRapierVector(body2Anchor)
+    )
+  );
+};
+
+/**
+ * The revolute joint prevents any relative movement between two rigid-bodies, except for relative
+ * rotations along one axis. This is typically used to simulate wheels, fans, etc.
+ * They are characterized by one local anchor as well as one local axis on each rigid-body.
+ *
+ * @category Hooks - Joints
+ */
+export const useRevoluteJoint: UseImpulseJoint<
+  RevoluteJointParams,
+  RevoluteImpulseJoint
+> = (body1, body2, [body1Anchor, body2Anchor, axis, limits]) => {
+  const { rapier } = useRapier();
+
+  const params = rapier.JointData.revolute(
+    vector3ToRapierVector(body1Anchor),
+    vector3ToRapierVector(body2Anchor),
+    vector3ToRapierVector(axis)
+  );
+
+  if (limits) {
+    params.limitsEnabled = true;
+    params.limits = limits;
+  }
+
+  return useImpulseJoint<RevoluteImpulseJoint>(body1, body2, params);
+};
+
+/**
+ * The prismatic joint prevents any relative movement between two rigid-bodies, except for relative translations along one axis.
+ * It is characterized by one local anchor as well as one local axis on each rigid-body. In 3D, an optional
+ * local tangent axis can be specified for each rigid-body.
+ *
+ * @category Hooks - Joints
+ */
+export const usePrismaticJoint: UseImpulseJoint<
+  PrismaticJointParams,
+  PrismaticImpulseJoint
+> = (body1, body2, [body1Anchor, body2Anchor, axis, limits]) => {
+  const { rapier } = useRapier();
+
+  const params = rapier.JointData.prismatic(
+    vector3ToRapierVector(body1Anchor),
+    vector3ToRapierVector(body2Anchor),
+    vector3ToRapierVector(axis)
+  );
+
+  if (limits) {
+    params.limitsEnabled = true;
+    params.limits = limits;
+  }
+
+  return useImpulseJoint<PrismaticImpulseJoint>(body1, body2, params);
+};
+
+/**
+ * The rope joint limits the max distance between two bodies.
+ * @category Hooks - Joints
+ */
+export const useRopeJoint: UseImpulseJoint<
+  RopeJointParams,
+  RopeImpulseJoint
+> = (body1, body2, [body1Anchor, body2Anchor, length]) => {
+  const { rapier } = useRapier();
+
+  const vBody1Anchor = vector3ToRapierVector(body1Anchor);
+  const vBody2Anchor = vector3ToRapierVector(body2Anchor);
+
+  const params = rapier.JointData.rope(length, vBody1Anchor, vBody2Anchor);
+
+  return useImpulseJoint<RopeImpulseJoint>(body1, body2, params);
+};
+
+/**
+ * The spring joint applies a force proportional to the distance between two objects.
+ * @category Hooks - Joints
+ */
+export const useSpringJoint: UseImpulseJoint<
+  SpringJointParams,
+  SpringImpulseJoint
+> = (
+  body1,
+  body2,
+  [body1Anchor, body2Anchor, restLength, stiffness, damping]
+) => {
+  const { rapier } = useRapier();
+
+  const vBody1Anchor = vector3ToRapierVector(body1Anchor);
+  const vBody2Anchor = vector3ToRapierVector(body2Anchor);
+
+  const params = rapier.JointData.spring(
+    restLength,
+    stiffness,
+    damping,
+    vBody1Anchor,
+    vBody2Anchor
+  );
+
+  return useImpulseJoint<SpringImpulseJoint>(body1, body2, params);
+};

package/src/hooks/use-forwarded-ref.ts

@@ -0,0 +1,19 @@
+import { ForwardedRef, RefObject, useRef } from "react";
+
+// Need to catch the case where forwardedRef is a function... how to do that?
+export const useForwardedRef = <T>(
+  forwardedRef: ForwardedRef<T> | undefined,
+  defaultValue: T | null = null
+): RefObject<T> => {
+  const innerRef = useRef<T>(defaultValue);
+
+  // Update the forwarded ref when the inner ref changes
+  if (forwardedRef && typeof forwardedRef !== "function") {
+    if (!forwardedRef.current) {
+      forwardedRef.current = innerRef.current;
+    }
+    return forwardedRef as RefObject<T>;
+  }
+
+  return innerRef as RefObject<T>;
+};

package/src/hooks/use-imperative-instance.ts

@@ -0,0 +1,33 @@
+import { DependencyList, useCallback, useEffect, useRef } from "react";
+
+/**
+ * Initiate an instance and return a safe getter
+ */
+export const useImperativeInstance = <InstanceType>(
+  createFn: () => InstanceType,
+  destroyFn: (instance: InstanceType) => void,
+  dependencyList: DependencyList
+) => {
+  const ref = useRef<InstanceType | undefined>(undefined);
+
+  const getInstance = useCallback(() => {
+    if (!ref.current) {
+      ref.current = createFn();
+    }
+
+    return ref.current;
+  }, dependencyList);
+
+  useEffect(() => {
+    // Save the destroy function and instance
+    const instance = getInstance();
+    const destroy = () => destroyFn(instance);
+
+    return () => {
+      destroy();
+      ref.current = undefined;
+    };
+  }, [getInstance]);
+
+  return getInstance;
+};

package/src/index.ts

@@ -0,0 +1,55 @@
+// Core exports from react-three-rapier
+export * from "./types";
+
+// Component exports
+export type { RigidBodyProps } from "./components/RigidBody";
+export type {
+  InstancedRigidBodiesProps,
+  InstancedRigidBodyProps
+} from "./components/InstancedRigidBodies";
+export type {
+  CylinderColliderProps,
+  BallColliderProps,
+  CapsuleColliderProps,
+  ConeColliderProps,
+  ConvexHullColliderProps,
+  CuboidColliderProps,
+  HeightfieldColliderProps,
+  RoundCuboidColliderProps,
+  TrimeshColliderProps,
+  ColliderOptionsRequiredArgs
+} from "./components/AnyCollider";
+
+export type {
+  PhysicsProps,
+  RapierContext,
+  WorldStepCallback,
+  FilterContactPairCallback,
+  FilterIntersectionPairCallback
+} from "./components/Physics";
+export type { MeshColliderProps } from "./components/MeshCollider";
+
+export { Physics } from "./components/Physics";
+export { RigidBody } from "./components/RigidBody";
+export { MeshCollider } from "./components/MeshCollider";
+export { InstancedRigidBodies } from "./components/InstancedRigidBodies";
+export * from "./components/AnyCollider";
+
+// Hooks exports
+export * from "./hooks/joints";
+export {
+  useRapier,
+  useBeforePhysicsStep,
+  useAfterPhysicsStep,
+  useFilterContactPair,
+  useFilterIntersectionPair
+} from "./hooks/hooks";
+
+// Utils exports
+export * from "./utils/interaction-groups";
+export * from "./utils/three-object-helpers";
+
+// Addons exports
+export * from "./addons/attractor/Attractor";
+export * from "./addons/attractor/AttractorDebugHelper";
+