@react-three/rapier 0.12.2 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/rapier",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "source": "src/index.ts",
   "main": "dist/react-three-rapier.cjs.js",
   "module": "dist/react-three-rapier.esm.js",
@@ -14,26 +14,26 @@
   "devDependencies": {
     "@react-three/drei": "9.45.0",
     "@react-three/fiber": "8.9.1",
-    "@react-three/test-renderer": "^8.0.17",
-    "@types/react-dom": "^18.0.2",
-    "@types/three": "^0.139.0",
+    "@react-three/test-renderer": "8.0.17",
+    "@types/react-dom": "18.0.2",
+    "@types/three": "0.139.0",
     "@vitejs/plugin-react": "^2.1.0",
-    "@vitest/ui": "^0.25.2",
-    "happy-dom": "^7.5.5",
+    "@vitest/ui": "0.25.2",
+    "happy-dom": "7.5.5",
     "react": "18.2.0",
     "react-dom": "18.2.0",
     "three": "0.146.0",
-    "vitest": "^0.25.2"
+    "vitest": "0.25.2"
   },
   "peerDependencies": {
-    "@react-three/fiber": "^8.0.12",
-    "react": "^18.0.0",
+    "@react-three/fiber": "8.9.1",
+    "react": "18.2.0",
     "three": ">=0.139.2"
   },
   "dependencies": {
-    "@dimforge/rapier3d-compat": "0.10.0",
-    "three-stdlib": "^2.15.0",
-    "use-asset": "^1.0.4"
+    "@dimforge/rapier3d-compat": "0.11.1",
+    "three-stdlib": "2.21.6",
+    "use-asset": "1.0.4"
   },
   "repository": "https://github.com/pmndrs/react-three-rapier/tree/master/packages/react-three-rapier"
 }

package/readme.md

@@ -12,7 +12,7 @@
 <br />
 For contributions, please read the <a href="https://github.com/pmndrs/react-three-rapier/blob/main/packages/react-three-rapier/CONTRIBUTING.md">🪧 Contribution Guide</a>.
 <br/>
-For available APIs, see <a href="https://pmndrs.github.io/react-three-rapier/>">🧩 API Docs</a>
+For available APIs, see <a href="https://pmndrs.github.io/react-three-rapier/">🧩 API Docs</a>
 </p>
 
 ---
@@ -66,7 +66,7 @@ For full API outline and documentation, see 🧩 [API Docs](https://pmndrs.githu
 - [Collider Components](#collider-components)
   - [🖼 Collider Examples](#-collider-examples)
 - [Instanced Meshes](#instanced-meshes)
-- [Debug](#debug)
+- [Moving things around, and applying forces](#moving-things-around-and-applying-forces)
 - [Collision Events](#collision-events)
   - [Configuring collision and solver groups](#configuring-collision-and-solver-groups)
 - [Contact force events](#contact-force-events)
@@ -80,7 +80,6 @@ For full API outline and documentation, see 🧩 [API Docs](https://pmndrs.githu
   - [Spherical Joint](#spherical-joint)
   - [Revolute Joint](#revolute-joint)
   - [Prismatic Joint](#prismatic-joint)
-  - [Joint APIs](#joint-apis)
   - [🖼 Joints Example](#-joints-example)
 - [Advanced hooks usage](#advanced-hooks-usage)
   - [Manual stepping](#manual-stepping)
@@ -238,66 +237,99 @@ If part of our meshes are invisible and you want to include them in the collider
 
 Instanced meshes can also be used and have automatic colliders generated from their mesh.
 
-By wrapping the `InstancedMesh` in `<InstancedRigidBodies />`, each instance will be attached to an individual `RigidBody`.
+By wrapping exactly one `Three.InstancedMesh` in `<InstancedRigidBodies />`, each instance will be attached to an individual `RigidBody`.
 
 🧩 See [InstancedRigidBodiesProps docs](https://pmndrs.github.io/react-three-rapier/interfaces/InstancedRigidBodiesProps.html) for available props.
 
 ```tsx
-import { InstancedRigidBodies } from "@react-three/rapier";
+import { InstancedRigidBodies, RapierRigidBody } from "@react-three/rapier";
 
 const COUNT = 1000;
 
 const Scene = () => {
-  const instancedApi = useRef<InstancedRigidBodyApi>(null);
+  const rigidBodies = useRef<RapierRigidBody[]>(null);
 
   useEffect(() => {
-    if (!instancedApi.current) {
+    if (!rigidBodies.current) {
       return
     }
 
     // You can access individual instanced by their index
-    instancedApi.current.at(40).applyImpulse({ x: 0, y: 10, z: 0 });
+    rigidBodies.current.at(40).applyImpulse({ x: 0, y: 10, z: 0 });
 
-    // Or update all instances as if they were in an array
-    instancedApi.current.forEach((api) => {
+    // Or update all instances
+    rigidBodies.current.forEach((api) => {
       api.applyImpulse({ x: 0, y: 10, z: 0 });
     });
   }, []);
 
   // We can set the initial positions, and rotations, and scales, of
-  // the instances by providing an array equal to the instance count
-  const positions = Array.from({ length: COUNT }, (_, index) => [index, 0, 0]);
-
-  const rotations = Array.from({ length: COUNT }, (_, index) => [
-    Math.random(),
-    Math.random(),
-    Math.random()
-  ]);
+  // the instances by providing an array of InstancedRigidBodyProps
+  // which is the same as RigidBodyProps, but with an additional "key" prop.
+  const instances = useMemo(() => {
+    const instances: InstancedRigidBodyProps[] = [];
+
+    for (let i = 0; i < COUNT; i++) {
+      instances.push({
+        key: 'instance_' + Math.random(),
+        position: [Math.random() * 10, Math.random() * 10, Math.random() * 10],
+        rotation: [Math.random(), Math.random(), Math.random()],
+      });
+    }
 
-  const scales = Array.from({ length: COUNT }, (_, index) => [
-    Math.random(),
-    Math.random(),
-    Math.random()
-  ]);
+    return instances;
+  }, []);
 
   return (
     <InstancedRigidBodies
       ref={instancedApi}
-      positions={positions}
-      rotations={rotations}
-      scales={scales}
+      instances={instances}
       colliders="ball"
     >
-      <instancedMesh args={[undefined, undefined, COUNT]}>
-        <sphereGeometry args={[0.2]} />
-        <meshPhysicalGeometry color="blue" />
+      <instancedMesh args={[undefined, undefined, COUNT]} count={COUNT} />
+    </InstancedRigidBodies>
+  );
+};
+```
+
+We can also create compound shapes for instanced meshes by providing an array of `Colliders` in the `colliderNodes` prop.
 
-        <CuboidCollider args={[0.1, 0.2, 0.1]} />
-      </instancedMesh>
+```tsx
+import { InstancedRigidBodies, BoxCollider, SphereCollider } from "@react-three/rapier";
+const COUNT = 500
+
+const Scene = () => {
+  const instances = useMemo(() => {
+    const instances: InstancedRigidBodyProps[] = [];
+
+    for (let i = 0; i < COUNT; i++) {
+      instances.push({
+        key: 'instance_' + Math.random(),
+        position: [Math.random() * 10, Math.random() * 10, Math.random() * 10],
+        rotation: [Math.random(), Math.random(), Math.random()],
+      });
+    }
+
+    return instances;
+  }, []);
+
+  return (
+    <InstancedRigidBodies
+      ref={instancedApi}
+      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>
   );
 };
 ```
+}
+```
 
 ## Debug
 
@@ -323,6 +355,87 @@ const Scene = () => {
 };
 ```
 
+## Moving things around, and applying forces
+You can access the instance for a RigidBody by storing its `ref`. This allows you to perform any operation on the underlying physics object directly.
+
+`r3/rapier` exposes a `RapierRigidBody` and `RapierCollider` as aliases for `rapiers` underlying base objects.
+
+For all available methods, see the [Rapier docs](https://rapier.rs/javascript3d/classes/RigidBody.html).
+
+```tsx
+import { 
+  RigidBody, 
+  RapierRigidBody
+} from "@react-three/rapier";
+
+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>
+  );
+};
+```
+
+Rapier's API returns quaternions and vectors that are not compatible with Three.js, `r3/rapier` therefore exposes some helper functions (`vec3`, `quat`, `euler`) for quick type conversions. These helper functions can also be used as a shorthand for creating new objects.
+
+```tsx
+import { 
+  RapierRigidBody, 
+  quat, 
+  vec3, 
+  euler 
+} from "@react-three/rapier";
+
+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>
+  );
+}
+
+```
+
 ## Collision Events
 
 You can subscribe to collision and state events on a RigidBody:
@@ -560,6 +673,21 @@ There are 4 different joint types available:
 - Revolute (two bodies are connected by a hinge, for things like doors or wheels)
 - Prismatic (two bodies are connected by a sliding joint, for things like pistons or sliders)
 
+Each joint hook returns a RefObject containing the raw reference to the joint instance.  
+```tsx
+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
+}
+```
+
 ### Fixed Joint
 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.
 
@@ -636,6 +764,12 @@ const JointedThing = () => {
       [0, 0, 0], // Axis of the joint, expressed in the local-space of the rigid-bodies it is attached to.
     ]);
 
+  useEffect(() => {
+    if (joint.current) {
+
+    }
+  }, [])
+
   return (
     <group>
       <RigidBody ref={bodyA}>
@@ -680,27 +814,6 @@ const JointedThing = () => {
 }
 ```
 
-### Joint APIs
-Joints can be controlled imperatively similarily to how `RigidBody` components can be controlled.
-
-🧩 See [Joint API docs](https://pmndrs.github.io/react-three-rapier/interfaces/JointApi.html) for more information.
-
-```tsx
-const JointedThing = () => { 
-  const joint = useSphericalJoint(...)
-
-  useEffect(() => {
-    joint.configureMotorVelocity(1, 0)
-
-    // Disable contacts between the two joint bodies
-    joint.raw().setContactsEnabled(false)
-  }, [])
-
-  return ...
-}
-```
-
-
 ### 🖼 Joints Example
 <a href="https://codesandbox.io/s/react-three-rapier-joints-mhhbd4"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/example-joints.jpg" width="240" /></a>
 

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

@@ -1,10 +0,0 @@
-import React from "react";
-import { InstancedRigidBodyApi } from "./api";
-import { RigidBodyProps } from "./RigidBody";
-import { Vector3Array } from "./types";
-export interface InstancedRigidBodiesProps extends Omit<RigidBodyProps, "position" | "rotation"> {
-    positions?: Vector3Array[];
-    rotations?: Vector3Array[];
-    scales?: Vector3Array[];
-}
-export declare const InstancedRigidBodies: React.ForwardRefExoticComponent<InstancedRigidBodiesProps & React.RefAttributes<InstancedRigidBodyApi>>;

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

@@ -1,179 +0,0 @@
-import { Collider, ColliderDesc, DebugRenderBuffers, ImpulseJoint, JointData, RigidBody, RigidBodyDesc, World } from "@dimforge/rapier3d-compat";
-import { Quaternion, Vector3 } from "three";
-import { RefGetter, Vector3Object } from "./types";
-export interface RigidBodyApi {
-    /**
-     * Get the raw RigidBody
-     * @see https://rapier.rs/javascript3d/classes/RigidBody.html
-     */
-    raw(): RigidBody;
-    /**
-     * The handle of this RigidBody
-     */
-    handle: number;
-    /**
-     * The mass of this rigid-body.
-     */
-    mass(): number;
-    /**
-     * Applies an impulse at the center-of-mass of this rigid-body.
-     */
-    applyImpulse(impulseVector: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * Applies an impulsive torque at the center-of-mass of this rigid-body.
-     */
-    applyTorqueImpulse(torqueVector: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * Applies an impulse at the given world-space point of this rigid-body.
-     */
-    applyImpulseAtPoint(impulseVector: Vector3Object, impulsePoint: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * Adds a force at the center-of-mass of this rigid-body.
-     */
-    addForce(force: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * Adds a force at the given world-space point of this rigid-body.
-     */
-    addForceAtPoint(force: Vector3Object, point: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * Adds a torque at the center-of-mass of this rigid-body.
-     */
-    addTorque(torque: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * The world-space translation of this rigid-body.
-     */
-    translation(): Vector3;
-    /**
-     * Sets the translation of this rigid-body.
-     */
-    setTranslation(translation: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * The world-space orientation of this rigid-body.
-     */
-    rotation(): Quaternion;
-    /**
-     * Sets the rotation quaternion of this rigid-body.
-     */
-    setRotation(rotation: Quaternion, wakeUp?: boolean): void;
-    /**
-     * The linear velocity of this rigid-body.
-     */
-    linvel(): Vector3;
-    /**
-     * Sets the linear velocity of this rigid-body.
-     */
-    setLinvel(velocity: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * The angular velocity of this rigid-body.
-     */
-    angvel(): Vector3;
-    /**
-     * Sets the angular velocity of this rigid-body.
-     */
-    setAngvel(velocity: Vector3Object, wakeUp?: boolean): void;
-    /**
-     * The linear damping of this rigid-body.
-     */
-    linearDamping(): number;
-    /**
-     * Sets the linear damping factor applied to this rigid-body.
-     */
-    setLinearDamping(factor: number): void;
-    /**
-     * The angular damping of this rigid-body.
-     */
-    angularDamping(): number;
-    /**
-     * Sets the anugular damping factor applied to this rigid-body.
-     */
-    setAngularDamping(factor: number): void;
-    /**
-     * If this rigid body is kinematic, sets its future rotation after the next timestep integration.
-     *
-     * This should be used instead of rigidBody.setRotation to make the dynamic object interacting with this
-     * kinematic body behave as expected. Internally, Rapier will compute an artificial velocity for this
-     * rigid-body from its current position and its next kinematic position. This velocity will be used
-     * to compute forces on dynamic bodies interacting with this body.
-     */
-    setNextKinematicRotation(rotation: Quaternion): void;
-    /**
-     * If this rigid body is kinematic, sets its future translation after the next timestep integration.
-     *
-     * This should be used instead of rigidBody.setTranslation to make the dynamic object interacting with
-     * this kinematic body behave as expected. Internally, Rapier will compute an artificial velocity
-     * for this rigid-body from its current position and its next kinematic position. This velocity
-     * will be used to compute forces on dynamic bodies interacting with this body.
-     */
-    setNextKinematicTranslation(translation: Vector3Object): void;
-    /**
-     * Resets to zero the user forces (but not torques) applied to this rigid-body.
-     */
-    resetForces(wakeUp?: boolean): void;
-    /**
-     * Resets to zero the user torques applied to this rigid-body.
-     */
-    resetTorques(wakeUp?: boolean): void;
-    /**
-     * Locks or unlocks the ability of this rigid-body to rotate.
-     */
-    lockRotations(locked: boolean, wakeUp?: boolean): void;
-    /**
-     * Locks or unlocks the ability of this rigid-body to translate.
-     */
-    lockTranslations(locked: boolean, wakeUp?: boolean): void;
-    /**
-     * Locks or unlocks the ability of this rigid-body to rotate along individual coordinate axes.
-     */
-    setEnabledRotations(x: boolean, y: boolean, z: boolean, wakeUp?: boolean): void;
-    /**
-     * Locks or unlocks the ability of this rigid-body to translate along individual coordinate axes.
-     */
-    setEnabledTranslations(x: boolean, y: boolean, z: boolean, wakeUp?: boolean): void;
-}
-export declare const createRigidBodyApi: (ref: RefGetter<RigidBody>) => RigidBodyApi;
-export interface InstancedRigidBodyApi {
-    at(index: number): RigidBodyApi;
-    get count(): number;
-    forEach(callback: (body: RigidBodyApi, index: number, array: RigidBodyApi[]) => void): void;
-}
-export declare const createInstancedRigidBodiesApi: (bodiesGetter: RefGetter<{
-    rigidBody: RigidBody;
-    api: RigidBodyApi;
-}[]>) => InstancedRigidBodyApi;
-export interface ColliderApi {
-    /**
-     * The Collider
-     * @see https://rapier.rs/javascript3d/classes/Collider.html
-     */
-    raw: () => Collider | undefined;
-    readonly handle: number;
-}
-export declare const createColliderApi: (ref: RefGetter<Collider>) => {
-    raw: () => Collider | undefined;
-    readonly handle: number;
-};
-export interface WorldApi {
-    raw(): World;
-    getCollider(handle: number): Collider | undefined;
-    getRigidBody(handle: number): RigidBody | undefined;
-    createRigidBody(desc: RigidBodyDesc): RigidBody;
-    createCollider(desc: ColliderDesc, parent?: RigidBody): Collider;
-    removeRigidBody(rigidBody: RigidBody): void;
-    removeCollider(collider: Collider, wakeUp?: boolean): void;
-    createImpulseJoint(params: JointData, rigidBodyA: RigidBody, rigidBodyB: RigidBody, wakeUp?: boolean): ImpulseJoint;
-    removeImpulseJoint(joint: ImpulseJoint, wakeUp?: boolean): void;
-    forEachCollider(callback: (collider: Collider) => void): void;
-    setGravity(gravity: Vector3): void;
-    debugRender(): DebugRenderBuffers;
-}
-export declare const createWorldApi: (ref: RefGetter<World>) => WorldApi;
-export interface JointApi {
-    /**
-     * @see https://rapier.rs/javascript3d/classes/ImpulseJoint.html
-     */
-    raw: () => ImpulseJoint | undefined;
-    readonly handle: number;
-    configureMotorPosition: (targetPos: number, stiffness: number, damping: number) => void;
-    configureMotorVelocity: (targetVel: number, damping: number) => void;
-}
-export declare const createJointApi: (ref: RefGetter<ImpulseJoint>) => JointApi;