@react-three/rapier 0.11.2 → 0.12.0

package/readme.md

@@ -7,9 +7,19 @@
   <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>
 </p>
 
-<p align="center">⚠️ Under heavy development. All APIs are subject to change. ⚠️</p>
+<p align="center">
+⚠️ This library is under development. All APIs are subject to change. ⚠️
+<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>
+</p>
+
+---
 
-For contributions, please read the [contributing guide](https://github.com/pmndrs/react-three-rapier/blob/main/packages/react-three-rapier/CONTRIBUTING.md).
+`react-three/rapier` (or `r3/rapier`) is a wrapper library around the Rapier (https://rapier.rs/docs/user_guides/javascript) WASM-based physics engine, designed to slot seamlessly into a `react-three/fiber` pipeline.
+
+The goal of this library to is to provide a fast physics engine with minimal friction and small, straight forward API.
 
 ## Basic Usage
 
@@ -27,7 +37,7 @@ const App = () => {
             <Torus />
           </RigidBody>
 
-          <CuboidCollider position={[0, -2, 0]} args={[20, .5, 20]}>
+          <CuboidCollider position={[0, -2, 0]} args={[20, .5, 20]} />
 
           <Debug />
         </Physics>
@@ -39,54 +49,81 @@ const App = () => {
 
 ---
 
+## 📝 Readme note
+Below follows a guide on core concepts for `react-three/rapier`.  
+For full API outline and documentation, see 🧩 [API Docs](https://pmndrs.github.io/react-three-rapier/).
+
+---
+
 ## Readme Topics
 
 - [Basic Usage](#basic-usage)
+- [📝 Readme note](#-readme-note)
 - [Readme Topics](#readme-topics)
 - [The Physics Component](#the-physics-component)
-- [Automatic colliders](#automatic-colliders)
-  - [Collider Examples](#collider-examples)
+- [The RigidBody Component](#the-rigidbody-component)
+- [Automatic Colliders](#automatic-colliders)
+- [Collider Components](#collider-components)
+  - [🖼 Collider Examples](#-collider-examples)
 - [Instanced Meshes](#instanced-meshes)
 - [Debug](#debug)
 - [Collision Events](#collision-events)
   - [Configuring collision and solver groups](#configuring-collision-and-solver-groups)
 - [Contact force events](#contact-force-events)
 - [Sensors](#sensors)
-  - [Sensors Example](#sensors-example)
+  - [🖼 Sensors Example](#-sensors-example)
 - [Attractors](#attractors)
-  - [Attractors Example](#attractors-example)
+  - [🖼 Attractors Example](#-attractors-example)
 - [Configuring Time Step Size](#configuring-time-step-size)
-- [Manual stepping](#manual-stepping)
 - [Joints](#joints)
-  - [Joints Example](#joints-example)
+  - [Fixed Joint](#fixed-joint)
+  - [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)
 
 ---
 
 ## The Physics Component
 The `<Physics />` component is the root component of your physics world. It is responsible for creating the physics world and managing the simulation. It relies on lazily initiating `Rapier` and needs to be wrapped in `<Suspense />`.
 
-```tsx
-  // The gravity of the physics workd
-  gravity?: Vector3Array; // default [0, -9.81, 0]
-
-  // Which collider shape to generate for meshes by default
-  colliders?: RigidBodyAutoCollider; // default "cuboid"
+🧩 See [PhysicsProps docs](https://pmndrs.github.io/react-three-rapier/interfaces/PhysicsProps.html) for available props.
 
-  // The number of physics steps per second
-  timeStep?: number | "vary"; // default 1/60
+```tsx
+const Scene = () => {
+  return (
+    <Canvas>
+      <Suspense>
+        <Physics 
+          gravity={[0,1,0]} 
+          interpolation={false} 
+          colliders={false}
+        >
+          ...
+        </Physics>
+      </Suspense>
+    </Canvas>
+  );
+}
+```
 
-  // Pause the physic simulation
-  paused?: boolean; // default false
+## The RigidBody Component
+The `<RigidBody />` component is used to add a `mesh` into the physics world. You use it by wrapping one or more `meshes` and setting desired props. By default, this will automatically generate `Colliders` based on the shape of the wrapped `meshes` (see [Automatic colliders](#automatic-colliders)).
 
-  // Which order to run the physics simulation
-  updatePriority?: number;
+🧩 See [RigidBodyProps docs](https://pmndrs.github.io/react-three-rapier/interfaces/RigidBodyProps.html) for available props.
 
-  // If the physics updates slower than the monitor refreshes,
-  // interpolation will smooth out the steps between frames
-  interpolate?: boolean; // default true
+```tsx
+const RigidBodyMesh = () => (
+  <RigidBody>
+    <mesh />
+  </RigidBody>
+);
 ```
 
-## Automatic colliders
+## Automatic Colliders
 
 RigidBodies generate automatic colliders by default for all meshes that it contains. You can control the default collider by setting the `colliders` prop on a `<RigidBody />`, or change it globally by setting `colliders` on `<Physics />`. Setting `colliders={false}` disables auto-generation.
 
@@ -127,35 +164,47 @@ const Scene = () => (
     <RigidBody position={[0, 10, 0]} colliders="ball">
       <Sphere />
     </RigidBody>
+  </Physics>
+);
+```
 
-    {/* Make a compound shape with two custom BallColliders */}
-    <RigidBody position={[0, 10, 0]}>
-      <Sphere />
-      <BallCollider args={[0.5]} />
-      <BallCollider args={[0.5]} position={[1, 0, 0]} />
-    </RigidBody>
-
-    {/* Make a compound shape with two custom BallColliders, an automatic BallCollider,
-        Two automatic MeshColliders, based on two different shape strategies */}
-    <RigidBody position={[0, 10, 0]} colliders='ball'>
-      <MeshCollider type="trimesh">
-        <mesh ... />
-      </MeshCollider>
+## Collider Components
 
-      <MeshCollider type="hull">
-        <mesh ... />
-      </MeshCollider>
+You can also create `Colliders` by hand and add them to a `RigidBody` to create compound colliders. This is useful for creating more complex shapes, for creating simplified shapes for performance reasons, or for detecting collisions on specific parts of a mesh.
 
-      <Sphere />
+🧩 See [ColliderProps docs](https://pmndrs.github.io/react-three-rapier/interfaces/ColliderProps.html) for available props.
 
-      <BallCollider args={[0.5]} />
-      <BallCollider args={[0.5]} position={[1, 0, 0]} />
-    </RigidBody>
-  </Physics>
-);
+```tsx
+const Scene = () => (<>
+  {/* Make a compound shape with two custom BallColliders */}
+  <RigidBody position={[0, 10, 0]}>
+    <Sphere />
+    <BallCollider args={[0.5]} />
+    <BallCollider args={[0.5]} position={[1, 0, 0]} />
+  </RigidBody>
+
+  {/* Make a compound shape with two custom BallColliders, an automatic BallCollider,
+      Two automatic MeshColliders, based on two different shape types */}
+  <RigidBody position={[0, 10, 0]} colliders='ball'>
+    <MeshCollider type="trimesh">
+      <mesh ... />
+    </MeshCollider>
+
+    <MeshCollider type="hull">
+      <mesh ... />
+    </MeshCollider>
+
+    <Sphere />
+
+    <BallCollider args={[0.5]} />
+    <BallCollider args={[0.5]} position={[1, 0, 0]} />
+  </RigidBody>
+<>)
 ```
 
-Objects work inside other transformed objects as well. Simulation runs in world space and is transformed to the objects local space, so that things act as you'd expect.
+RigidBodies work inside other transformed objects as well. Simulation runs in world space and is transformed to the objects local space, so that things act as you'd expect.
+
+> **Note** It's always best to create RigidBodies where the center of gravity is in the center of the object, otherwise you might get some unexpected behavior during simulation interpolation.
 
 ```tsx
 import { Box } from "@react-three/drei";
@@ -181,7 +230,7 @@ If part of our meshes are invisible and you want to include them in the collider
 </RigidBody>
 ```
 
-### Collider Examples
+### 🖼 Collider Examples
 <a href="https://codesandbox.io/s/react-three-rapier-auto-colliders-b4coz1"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/example-auto-colliders.jpg" width="240" /></a>
 <a href="https://codesandbox.io/s/react-three-rapier-compound-colliders-ol5ybn"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/example-compound-shapes.jpg" width="240" /></a>
 
@@ -191,6 +240,8 @@ Instanced meshes can also be used and have automatic colliders generated from th
 
 By wrapping the `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";
 
@@ -200,11 +251,15 @@ const Scene = () => {
   const instancedApi = useRef<InstancedRigidBodyApi>(null);
 
   useEffect(() => {
+    if (!instancedApi.current) {
+      return
+    }
+
     // You can access individual instanced by their index
-    instancedApi.at(40).applyImpulse({ x: 0, y: 10, z: 0 });
+    instancedApi.current.at(40).applyImpulse({ x: 0, y: 10, z: 0 });
 
     // Or update all instances as if they were in an array
-    instancedApi.forEach((api) => {
+    instancedApi.current.forEach((api) => {
       api.applyImpulse({ x: 0, y: 10, z: 0 });
     });
   }, []);
@@ -272,6 +327,8 @@ const Scene = () => {
 
 You can subscribe to collision and state events on a RigidBody:
 
+🧩 See [onCollisionEnter / onCollisionExit docs](https://pmndrs.github.io/react-three-rapier/interfaces/RigidBodyProps.html#onCollisionEnter) for more information.
+
 ```tsx
 const RigidBottle = () => {
   const [isAsleep, setIsAsleep] = useState(false);
@@ -379,7 +436,7 @@ Contact force events are triggered on `<RigidBody>` and any collider components
     console.log(`The total force generated was: ${payload.totalForce}`);
   }}>
   <Sphere>
-    <meshPhysicalMaterial color={'grey'}>
+    <meshPhysicalMaterial color={'grey'} />
   </Sphere>
 </RigidBody>
 ```
@@ -417,6 +474,10 @@ A Collider can be set to be a sensor, which means that it will not generate any
 
 To detect when a collider enters or leaves another collider, you can use the `onIntersectionEnter` and `onIntersectionExit` events on the collider.
 
+🧩 See [onIntersectionEnter / onIntersectionExit docs](https://pmndrs.github.io/react-three-rapier/interfaces/RigidBodyProps.html#onIntersectionEnter) for more information.
+
+```tsx
+
 ```tsx
 <RigidBody>
   <GoalPosts />
@@ -429,7 +490,7 @@ To detect when a collider enters or leaves another collider, you can use the `on
 </RigidBody>
 ```
 
-### Sensors Example
+### 🖼 Sensors Example
 <a href="https://codesandbox.io/s/react-three-rapier-sensors-byjmsk"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/example-sensors.jpg" width="240" /></a>
 
 ## Attractors
@@ -439,6 +500,8 @@ Setting the `strength` to a negative value will cause the `RigidBody` to be _pus
 
 The force applied to rigid-bodies within range is calculated differently depending on the `type`.
 
+🧩 See [Attractor docs](https://pmndrs.github.io/react-three-rapier/interfaces/AttractorProps.html) for all available props.
+
 ```tsx
 // Standard attractor
 <Attractor range={10} strength={5} type="linear" position={[5, -5, 0]} />
@@ -466,7 +529,7 @@ Gravity types:
   - `mass2` is the mass of the rigid-body at the time of calculation. Note that rigid-bodies with colliders will use the mass provided to the collider. This is not a value you can control from the attractor, only from wherever you're creating rigid-body components in the scene.
   - `distance` is the distance between the attractor and rigid-body at the time of calculation
 
-### Attractors Example
+### 🖼 Attractors Example
 <a href="https://codesandbox.io/s/react-three-rapier-attractors-oyj640"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/example-attractors.jpg" width="240" /></a>
 
 ## Configuring Time Step Size
@@ -485,19 +548,182 @@ The `timeStep` prop may also be set to `"vary"`, which will cause the simulation
 
 > **Note** This is useful for games that run at variable frame rates, but may cause instability in the simulation. It also prevents the physics simulation from being fully deterministic. Please use with care!
 
-## Manual stepping
+## Joints
+Joints can be made between two `RigidBodies` to provide a way to restrict a motion of a body in relation to another.
+> Read more about joints in Rapier: https://rapier.rs/docs/user_guides/javascript/joints
+
+Joints are available in `r3/rapier` as hooks.
 
-You can also manually step the physics simulation by calling the `step` method from the `useRapier` hook.
+There are 4 different joint types available:
+- Fixed (two bodies are fixed together)
+- Spherical (two bodies are connected by a ball and socket, for things like arms or chains)
+- 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)
+
+### 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.
+
+🧩 See [FixedJoint docs](https://pmndrs.github.io/react-three-rapier/functions/useFixedJoint.html) for available options.
 
 ```tsx
-const { step } = useRapier();
+const JointedThing = () => {
+  const joint = useFixedJoint(
+    bodyA,
+    bodyB,
+    [
+      [0, 0, 0], // Position of the joint in bodyA's local space
+      [0, 0, 0, 1], // Orientation of the joint in bodyA's local space
+      [0, 0, 0], // Position of the joint in bodyB's local space
+      [0, 0, 0, 1], // Orientation of the joint in bodyB's local space
+    ]);
 
-step(1 / 60);
+  return (
+    <group>
+      <RigidBody ref={bodyA}>
+        <mesh />
+      </RigidBody>
+      <RigidBody ref={bodyB}>
+        <mesh />
+      </RigidBody>
+    </group>
+  );
+}
 ```
 
-## Joints
+### Spherical Joint
+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).
 
-- WIP
+🧩 See [SphericalJoint docs](https://pmndrs.github.io/react-three-rapier/functions/useSphericalJoint.html) for available options.
 
-### 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>
+```tsx
+
+```tsx
+const JointedThing = () => {
+  const joint = useSphericalJoint(
+    bodyA,
+    bodyB,
+    [
+      [0, 0, 0], // Position of the joint in bodyA's local space
+      [0, 0, 0], // Position of the joint in bodyB's local space
+    ]);
+
+  return (
+    <group>
+      <RigidBody ref={bodyA}>
+        <mesh />
+      </RigidBody>
+      <RigidBody ref={bodyB}>
+        <mesh />
+      </RigidBody>
+    </group>
+  );
+}
+```
+
+### Revolute Joint
+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.
+
+🧩 See [RevoluteJoint docs](https://pmndrs.github.io/react-three-rapier/functions/useRevoluteJoint.html) for available options.
+
+```tsx
+const JointedThing = () => {
+  const joint = useRevoluteJoint(
+    bodyA,
+    bodyB,
+    [
+      [0, 0, 0], // Position of the joint in bodyA's local space    
+      [0, 0, 0], // Position of the joint in bodyB's local space
+      [0, 0, 0], // Axis of the joint, expressed in the local-space of the rigid-bodies it is attached to.
+    ]);
+
+  return (
+    <group>
+      <RigidBody ref={bodyA}>
+        <mesh />
+      </RigidBody>
+      <RigidBody ref={bodyB}>
+        <mesh />
+      </RigidBody>
+    </group>
+  );
+}
+```
+
+### Prismatic Joint
+The prismatic joint prevents any relative movement between two rigid-bodies, except for relative translations along one axis.
+
+🧩 See [PrismaticJoint docs](https://pmndrs.github.io/react-three-rapier/functions/usePrismaticJoint.html) for available options.
+
+```tsx
+
+```tsx
+const JointedThing = () => {
+  const joint = usePrismaticJoint(
+    bodyA,
+    bodyB,
+    [
+      [0, 0, 0], // Position of the joint in bodyA's local space    
+      [0, 0, 0], // Position of the joint in bodyB's local space
+      [0, 0, 0], // Axis of the joint, expressed in the local-space of the rigid-bodies it is attached to.
+    ]);
+
+  return (
+    <group>
+      <RigidBody ref={bodyA}>
+        <mesh />
+      </RigidBody>
+      <RigidBody ref={bodyB}>
+        <mesh />
+      </RigidBody>
+    </group>
+  );
+}
+```
+
+### 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>
+
+## Advanced hooks usage
+
+Advanced users might need granular access to the physics loop and direct access to the `world` instance. This can be done by using the following hooks:
+
+- `useRapier`  
+  Gives you access to the `world`, direct access to `rapier`, and more.  
+  🧩 See [useRapier docs](https://pmndrs.github.io/react-three-rapier/interfaces/RapierContext.html) for more information.
+- `useBeforePhysicsStep`  
+  Allows you to run code before the physics simulation is stepped.  
+  🧩 See [useBeforePhysicsStep docs](https://pmndrs.github.io/react-three-rapier/functions/useBeforePhysicsStep.html) for more information.
+- `useAfterPhysicsStep`
+  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.
+
+### Manual stepping
+
+You can manually step the physics simulation by calling the `step` method from the `useRapier` hook.
+
+```tsx
+const { step } = useRapier();
+
+step(1 / 60);
+```