react-three-rapier-unified 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "react-three-rapier-unified",
+  "version": "1.0.0",
+  "description": "Unified package combining @react-three/rapier and @react-three/rapier-addons",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "source": "src/index.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "vite build --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": "^9.0.4",
+    "react": "^19",
+    "three": ">=0.159.0"
+  },
+  "dependencies": {
+    "@dimforge/rapier3d-compat": "0.19.3",
+    "suspend-react": "^0.1.3",
+    "three-stdlib": "^2.35.12"
+  },
+  "devDependencies": {
+    "@react-three/fiber": "9.0.4",
+    "@types/react": "19.0.8",
+    "@types/three": "0.172.0",
+    "react": "19.0.0",
+    "three": "0.172.0",
+    "typescript": "5.7.3",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MMORPG-Lordson/react-three-rapier-unified.git"
+  },
+  "keywords": [
+    "react",
+    "three",
+    "threejs",
+    "physics",
+    "rapier",
+    "react-three-fiber",
+    "r3f"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/addons/attractor/Attractor.tsx

@@ -0,0 +1,178 @@
+import React from "react";
+import { InteractionGroups, RigidBody } from "@dimforge/rapier3d-compat";
+import { useBeforePhysicsStep, useRapier } from "../../hooks/hooks";
+import { FC, memo, useRef } from "react";
+import { Object3D, Vector3 } from "three";
+import { ThreeElements } from "@react-three/fiber";
+import { AttractorDebugHelper } from "./AttractorDebugHelper";
+
+type Object3DProps = ThreeElements["object3D"];
+
+export type AttractorGravityType = "static" | "linear" | "newtonian";
+
+export interface AttractorProps {
+  /**
+   * The relative position of this attractor
+   */
+  position?: Object3DProps["position"];
+
+  /**
+   * The strength of the attractor.
+   * Positive values attract, negative values repel.
+   *
+   * @defaultValue 1
+   */
+  strength?: number;
+
+  /**
+   * The range of the attractor. Will not affect objects outside of this range.
+   *
+   * @defaultValue 10
+   * @min 0
+   */
+  range?: number;
+
+  /**
+   * The type of gravity to use.
+   * - static: The gravity is constant and does not change over time.
+   * - linear: The gravity is linearly interpolated the closer the object is to the attractor.
+   * - newtonian: The gravity is calculated using the newtonian gravity formula.
+   * @defaultValue "static"
+   */
+  type?: AttractorGravityType;
+
+  /**
+   * The mass of the attractor. Used when type is `newtonian`.
+   * @defaultValue 6.673e-11
+   */
+  gravitationalConstant?: number;
+
+  /**
+   * The collision groups that this attractor will apply effects to. If a RigidBody contains one or more colliders that are in one of the mask group, it will be affected by this attractor.
+   * If not specified, the attractor will apply effects to all RigidBodies.
+   */
+  collisionGroups?: InteractionGroups;
+}
+
+export interface AttractorState
+  extends Required<Omit<AttractorProps, "position" | "collisionGroups">> {
+  collisionGroups?: InteractionGroups;
+}
+
+const calcForceByType = {
+  static: (s: number, m2: number, r: number, d: number, G: number) => s,
+  linear: (s: number, m2: number, r: number, d: number, G: number) =>
+    s * (d / r),
+  newtonian: (s: number, m2: number, r: number, d: number, G: number) =>
+    (G * s * m2) / Math.pow(d, 2)
+};
+
+const _position = new Vector3();
+const _vector3 = new Vector3();
+
+export const applyAttractorForceOnRigidBody = (
+  rigidBody: RigidBody,
+  {
+    object,
+    strength,
+    range,
+    gravitationalConstant,
+    collisionGroups,
+    type
+  }: AttractorState & {
+    object: Object3D;
+  }
+) => {
+  const rbPosition = rigidBody.translation();
+  _position.set(rbPosition.x, rbPosition.y, rbPosition.z);
+
+  const worldPosition = object.getWorldPosition(new Vector3());
+
+  const distance: number = worldPosition.distanceTo(_position);
+
+  if (distance < range) {
+    let force = calcForceByType[type](
+      strength,
+      rigidBody.mass(),
+      range,
+      distance,
+      gravitationalConstant
+    );
+
+    // Prevent wild forces when Attractors collide
+    force = force === Infinity ? strength : force;
+
+    // Naively test if the rigidBody contains a collider in one of the collision groups
+    let isRigidBodyInCollisionGroup =
+      collisionGroups === undefined ? true : false;
+    if (collisionGroups !== undefined) {
+      for (let i = 0; i < rigidBody.numColliders(); i++) {
+        const collider = rigidBody.collider(i);
+        const colliderCollisionGroups = collider.collisionGroups();
+        if (
+          ((collisionGroups >> 16) & colliderCollisionGroups) != 0 &&
+          ((colliderCollisionGroups >> 16) & collisionGroups) != 0
+        ) {
+          isRigidBodyInCollisionGroup = true;
+          break;
+        }
+      }
+    }
+
+    if (isRigidBodyInCollisionGroup) {
+      _vector3
+        .set(0, 0, 0)
+        .subVectors(worldPosition, _position)
+        .normalize()
+        .multiplyScalar(force);
+
+      rigidBody.applyImpulse(_vector3, true);
+    }
+  }
+};
+
+export const Attractor: FC<AttractorProps> = memo((props) => {
+  const {
+    position = [0, 0, 0],
+    strength = 1,
+    range = 10,
+    type = "static",
+    gravitationalConstant = 6.673e-11,
+    collisionGroups
+  } = props;
+  const object = useRef<Object3D>(null!);
+  const { isDebug } = useRapier();
+
+  useBeforePhysicsStep((world) => {
+    if (object.current) {
+      world.bodies.forEach((body) => {
+        if (body.isDynamic()) {
+          applyAttractorForceOnRigidBody(body, {
+            object: object.current!,
+            strength,
+            range,
+            type,
+            gravitationalConstant,
+            collisionGroups
+          });
+        }
+      });
+    }
+  });
+
+  return (
+    <>
+      <object3D ref={object} position={position} />
+      {isDebug && (
+        <AttractorDebugHelper
+          strength={strength}
+          gravitationalConstant={gravitationalConstant}
+          range={range}
+          type={type}
+          collisionGroups={collisionGroups}
+          object={object}
+        />
+      )}
+    </>
+  );
+});

package/src/addons/attractor/AttractorDebugHelper.tsx

@@ -0,0 +1,59 @@
+import React, { RefObject, useEffect, useRef } from "react";
+import { useThree, useFrame } from "@react-three/fiber";
+import {
+  Mesh,
+  MeshBasicMaterial,
+  Object3D,
+  SphereGeometry,
+  Vector3
+} from "three";
+import { VertexNormalsHelper } from "three-stdlib";
+import { AttractorState } from "./Attractor";
+
+const _v3 = new Vector3();
+
+export const AttractorDebugHelper = (
+  props: AttractorState & {
+    object: RefObject<Object3D>;
+  }
+) => {
+  const { scene } = useThree();
+  const ref = useRef<Mesh>(null!);
+  const normalsHelper = useRef<VertexNormalsHelper>(null!);
+  const color = props.strength > 0 ? 0x0000ff : 0xff0000;
+
+  useEffect(() => {
+    ref.current = new Mesh(
+      new SphereGeometry(0.2, 6, 6),
+      new MeshBasicMaterial({ color, wireframe: true })
+    );
+
+    normalsHelper.current = new VertexNormalsHelper(
+      ref.current,
+      props.range,
+      color
+    );
+    normalsHelper.current.frustumCulled = false;
+
+    scene.add(ref.current);
+    scene.add(normalsHelper.current);
+
+    return () => {
+      if (normalsHelper.current && ref.current) {
+        scene.remove(normalsHelper.current);
+        scene.remove(ref.current);
+      }
+    };
+  }, [props, color]);
+
+  useFrame(() => {
+    if (ref.current && props.object.current) {
+      const worldPosition = props.object.current.getWorldPosition(_v3);
+
+      ref.current.position.copy(worldPosition);
+      normalsHelper.current?.update();
+    }
+  });
+
+  return null;
+};

package/src/components/AnyCollider.tsx

@@ -0,0 +1,286 @@
+import { Collider } from "@dimforge/rapier3d-compat";
+import React, {
+  ForwardedRef,
+  memo,
+  ReactNode,
+  Ref,
+  useEffect,
+  useMemo,
+  useRef
+} from "react";
+import { Object3D } from "three";
+import { useRapier } from "../hooks/hooks";
+import { useForwardedRef } from "../hooks/use-forwarded-ref";
+import { useImperativeInstance } from "../hooks/use-imperative-instance";
+import {
+  BallArgs,
+  CapsuleArgs,
+  ColliderOptions,
+  ConeArgs,
+  ConvexHullArgs,
+  CuboidArgs,
+  CylinderArgs,
+  HeightfieldArgs,
+  RoundConeArgs,
+  RoundCuboidArgs,
+  RoundCylinderArgs,
+  TrimeshArgs
+} from "../types";
+import { vec3 } from "../utils/three-object-helpers";
+import {
+  cleanRigidBodyPropsForCollider,
+  createColliderFromOptions,
+  createColliderState,
+  getActiveCollisionEventsFromProps,
+  immutableColliderOptions,
+  useColliderEvents,
+  useUpdateColliderOptions
+} from "../utils/utils-collider";
+import { useRigidBodyContext } from "./RigidBody";
+
+export interface ColliderProps extends ColliderOptions<any> {
+  children?: ReactNode;
+  ref?: Ref<Collider>;
+}
+
+/**
+ * A collider is a shape that can be attached to a rigid body to define its physical properties.
+ * @internal
+ */
+export const AnyCollider = memo((props: ColliderProps) => {
+  const { children, position, rotation, quaternion, scale, name } = props;
+  const { world, colliderEvents, colliderStates } = useRapier();
+  const rigidBodyContext = useRigidBodyContext();
+  const colliderRef = useForwardedRef(props.ref);
+  const objectRef = useRef<Object3D>(null);
+
+  // We spread the props out here to make sure that the ref is updated when the props change.
+  const immutablePropArray = immutableColliderOptions.flatMap((key) =>
+    // Array.isArray(props[key]) ? [...props[key]] : props[key]
+    Array.isArray(props[key]) ? props[key] : [props[key]]
+  );
+
+  const getInstance = useImperativeInstance(
+    () => {
+      const worldScale = objectRef.current!.getWorldScale(vec3());
+
+      const collider = createColliderFromOptions(
+        props,
+        world,
+        worldScale,
+        rigidBodyContext?.getRigidBody
+      );
+
+      if (typeof props.ref == "function") {
+        props.ref(collider);
+      }
+      colliderRef.current = collider;
+
+      return collider;
+    },
+    (collider) => {
+      if (world.getCollider(collider.handle)) {
+        world.removeCollider(collider, true);
+      }
+    },
+    [...immutablePropArray, rigidBodyContext]
+  );
+
+  useEffect(() => {
+    const collider = getInstance();
+
+    colliderStates.set(
+      collider.handle,
+      createColliderState(
+        collider,
+        objectRef.current!,
+        rigidBodyContext?.ref.current
+      )
+    );
+
+    return () => {
+      colliderStates.delete(collider.handle);
+    };
+  }, [getInstance]);
+
+  const mergedProps = useMemo(() => {
+    return {
+      ...cleanRigidBodyPropsForCollider(rigidBodyContext?.options),
+      ...props
+    };
+  }, [props, rigidBodyContext?.options]);
+
+  useUpdateColliderOptions(getInstance, mergedProps, colliderStates);
+  useColliderEvents(
+    getInstance,
+    mergedProps,
+    colliderEvents,
+    getActiveCollisionEventsFromProps(rigidBodyContext?.options)
+  );
+
+  return (
+    <object3D
+      position={position}
+      rotation={rotation}
+      quaternion={quaternion}
+      scale={scale}
+      ref={objectRef}
+      name={name}
+    >
+      {children}
+    </object3D>
+  );
+});
+
+export type ColliderOptionsRequiredArgs<T extends unknown[]> = Omit<
+  ColliderOptions<T>,
+  "args"
+> & {
+  args: T;
+  children?: ReactNode;
+};
+
+export type CuboidColliderProps = ColliderOptionsRequiredArgs<CuboidArgs>;
+
+/**
+ * A cuboid collider shape
+ * @category Colliders
+ */
+export const CuboidCollider = React.forwardRef(
+  (props: CuboidColliderProps, ref: ForwardedRef<Collider>) => {
+    return <AnyCollider {...props} shape="cuboid" ref={ref} />;
+  }
+);
+CuboidCollider.displayName = "CuboidCollider";
+
+export type RoundCuboidColliderProps =
+  ColliderOptionsRequiredArgs<RoundCuboidArgs>;
+
+/**
+ * A round cuboid collider shape
+ * @category Colliders
+ */
+export const RoundCuboidCollider = React.forwardRef(
+  (props: RoundCuboidColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="roundCuboid" ref={ref} />
+  )
+);
+RoundCuboidCollider.displayName = "RoundCuboidCollider";
+
+export type BallColliderProps = ColliderOptionsRequiredArgs<BallArgs>;
+/**
+ * A ball collider shape
+ * @category Colliders
+ */
+export const BallCollider = React.forwardRef(
+  (props: BallColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="ball" ref={ref} />
+  )
+);
+BallCollider.displayName = "BallCollider";
+
+export type CapsuleColliderProps = ColliderOptionsRequiredArgs<CapsuleArgs>;
+
+/**
+ * A capsule collider shape
+ * @category Colliders
+ */
+export const CapsuleCollider = React.forwardRef(
+  (props: CapsuleColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="capsule" ref={ref} />
+  )
+);
+CapsuleCollider.displayName = "CapsuleCollider";
+
+export type HeightfieldColliderProps =
+  ColliderOptionsRequiredArgs<HeightfieldArgs>;
+
+/**
+ * A heightfield collider shape
+ * @category Colliders
+ */
+export const HeightfieldCollider = React.forwardRef(
+  (props: HeightfieldColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="heightfield" ref={ref} />
+  )
+);
+HeightfieldCollider.displayName = "HeightfieldCollider";
+
+export type TrimeshColliderProps = ColliderOptionsRequiredArgs<TrimeshArgs>;
+/**
+ * A trimesh collider shape
+ * @category Colliders
+ */
+export const TrimeshCollider = React.forwardRef(
+  (props: TrimeshColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="trimesh" ref={ref} />
+  )
+);
+TrimeshCollider.displayName = "TrimeshCollider";
+
+export type ConeColliderProps = ColliderOptionsRequiredArgs<ConeArgs>;
+
+/**
+ * A cone collider shape
+ * @category Colliders
+ */
+export const ConeCollider = React.forwardRef(
+  (props: ConeColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="cone" ref={ref} />
+  )
+);
+ConeCollider.displayName = "ConeCollider";
+
+export type RoundConeColliderProps = ColliderOptionsRequiredArgs<RoundConeArgs>;
+
+/**
+ * A round cylinder collider shape
+ * @category Colliders
+ */
+export const RoundConeCollider = React.forwardRef(
+  (props: RoundConeColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="roundCone" ref={ref} />
+  )
+);
+RoundConeCollider.displayName = "RoundConeCollider";
+
+export type CylinderColliderProps = ColliderOptionsRequiredArgs<CylinderArgs>;
+
+/**
+ * A cylinder collider shape
+ * @category Colliders
+ */
+export const CylinderCollider = React.forwardRef(
+  (props: CylinderColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="cylinder" ref={ref} />
+  )
+);
+CylinderCollider.displayName = "CylinderCollider";
+
+export type RoundCylinderColliderProps =
+  ColliderOptionsRequiredArgs<RoundCylinderArgs>;
+
+/**
+ * A round cylinder collider shape
+ * @category Colliders
+ */
+export const RoundCylinderCollider = React.forwardRef(
+  (props: RoundConeColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="roundCylinder" ref={ref} />
+  )
+);
+CylinderCollider.displayName = "RoundCylinderCollider";
+
+export type ConvexHullColliderProps =
+  ColliderOptionsRequiredArgs<ConvexHullArgs>;
+
+/**
+ * A convex hull collider shape
+ * @category Colliders
+ */
+export const ConvexHullCollider = React.forwardRef(
+  (props: ConvexHullColliderProps, ref: ForwardedRef<Collider>) => (
+    <AnyCollider {...props} shape="convexHull" ref={ref} />
+  )
+);
+ConvexHullCollider.displayName = "ConvexHullCollider";

package/src/components/Debug.tsx

@@ -0,0 +1,33 @@
+import React, { memo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { BufferAttribute, BufferGeometry, LineSegments } from "three";
+import { useRapier } from "../hooks/hooks";
+import { _vector3 } from "../utils/shared-objects";
+
+export const Debug = memo(() => {
+  const { world } = useRapier();
+  const ref = useRef<LineSegments>(null);
+
+  useFrame(() => {
+    const mesh = ref.current;
+    if (!mesh) return;
+
+    const buffers = world.debugRender();
+
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(buffers.vertices, 3));
+    geometry.setAttribute("color", new BufferAttribute(buffers.colors, 4));
+
+    mesh.geometry.dispose();
+    mesh.geometry = geometry;
+  });
+
+  return (
+    <group>
+      <lineSegments ref={ref} frustumCulled={false}>
+        <lineBasicMaterial color={0xffffff} vertexColors />
+        <bufferGeometry />
+      </lineSegments>
+    </group>
+  );
+});

package/src/components/FrameStepper.tsx

@@ -0,0 +1,36 @@
+import { useFrame } from "@react-three/fiber";
+import React, { memo } from "react";
+import { useRaf } from "../utils/utils-physics";
+import { PhysicsProps } from "./Physics";
+
+interface FrameStepperProps {
+  type?: PhysicsProps["updateLoop"];
+  onStep: (dt: number) => void;
+  updatePriority?: number;
+}
+
+const UseFrameStepper = ({ onStep, updatePriority }: FrameStepperProps) => {
+  useFrame((_, dt) => {
+    onStep(dt);
+  }, updatePriority);
+
+  return null;
+};
+
+const RafStepper = ({ onStep }: FrameStepperProps) => {
+  useRaf((dt) => {
+    onStep(dt);
+  });
+
+  return null;
+};
+
+const FrameStepper = ({ onStep, type, updatePriority }: FrameStepperProps) => {
+  return type === "independent" ? (
+    <RafStepper onStep={onStep} />
+  ) : (
+    <UseFrameStepper onStep={onStep} updatePriority={updatePriority} />
+  );
+};
+
+export default memo(FrameStepper);