@react-three/rapier 0.8.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/rapier",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "source": "src/index.ts",
   "main": "dist/react-three-rapier.cjs.js",
   "module": "dist/react-three-rapier.esm.js",

package/readme.md

@@ -11,12 +11,12 @@
 
 For contributions, please read the [contributing guide](https://github.com/pmndrs/react-three-rapier/blob/main/packages/react-three-rapier/CONTRIBUTING.md).
 
-## Usage
+## Basic Usage
 
 ```tsx
 import { Box, Torus } from "@react-three/drei";
 import { Canvas } from "@react-three/fiber";
-import { Physics, RigidBody } from "@react-three/rapier";
+import { Physics, RigidBody, Debug } from "@react-three/rapier";
 
 const App = () => {
   return (
@@ -27,9 +27,9 @@ const App = () => {
             <Torus />
           </RigidBody>
 
-          <RigidBody position={[0, -2, 0]} type="kinematicPosition">
-            <Box args={[20, 0.5, 20]} />
-          </RigidBody>
+          <CuboidCollider position={[0, -2, 0]} args={[20, .5, 20]}>
+
+          <Debug />
         </Physics>
       </Suspense>
     </Canvas>
@@ -37,6 +37,23 @@ const App = () => {
 };
 ```
 
+---
+
+## Readme Topics
+
+- [Automatic Colliders](#automatic-colliders)
+- [Instanced Meshes](#instanced-meshes)
+- [Debug](#debug)
+- [Collision Events](#collision-events)
+- [Collision Groups](#configuring-collision-and-solver-groups)
+- [Contact Force Events](#contact-force-events)
+- [Sensors](#sensors)
+- [Attractors](#attractors)
+- [The timeStep](#configuring-time-step-size)
+- [Manual stepping](#manual-stepping)
+
+---
+
 ## 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.
@@ -138,8 +155,6 @@ 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`.
 
-> Note: Custom colliders (compound shapes) for InstancedMesh is currently not supported
-
 ```tsx
 import { InstancedRigidBodies } from "@react-three/rapier";
 
@@ -225,21 +240,35 @@ You can subscribe to collision and state events on a RigidBody:
 const RigidBottle = () => {
   const [isAsleep, setIsAsleep] = useState(false);
 
-return (
+  return (
     <RigidBody
       colliders="hull"
       onSleep={() => setIsAsleep(true)}
       onWake={() => setIsAsleep(false)}
-      onCollisionEnter={({manifold}) => {
-        console.log('Collision at world position ', manifold.solverContactPoint(0))
+      name="Bally McBallFace"
+      onCollisionEnter={({ manifold, target, other }) => {
+        console.log(
+          "Collision at world position ",
+          manifold.solverContactPoint(0)
+        );
+
+        if (other.rigidBodyObject) {
+          console.log(
+            // this rigid body's Object3D
+            target.rigidBodyObject.name,
+            " collided with ",
+            // the other rigid body's Object3D
+            other.rigidBodyObject.name
+          );
+        }
       }}
     >
       <Sphere>
-        <meshPhysicalMaterial color={isAsleep ? 'white' : 'blue'}>
+        <meshPhysicalMaterial color={isAsleep ? "white" : "blue"} />
       </Sphere>
     </RigidBody>
-  )
-}
+  );
+};
 ```
 
 You may also subscribe to collision events on individual Colliders:
@@ -258,14 +287,21 @@ You may also subscribe to collision events on individual Colliders:
 The `payload` object for all collision callbacks contains the following properties:
 
 - `target`  
-  The other rigidbody that was involved in the collision event.
-- `collider`  
-  The other collider that was involved in the collision event.
-- `manifold` (enter only)  
+  `CollisionTarget` of the object firing the event.
+- `other`  
+  `CollisionTarget` of the other object involved in the event.
+- `manifold` (onCollisionEnter only)  
   The [contact manifold](https://rapier.rs/javascript3d/classes/TempContactManifold.html) generated by the collision event.
-- `flipped` (enter only)  
+- `flipped` (onCollisionEnter only)  
   `true` if the data in the `manifold` [is flipped](https://rapier.rs/javascript3d/classes/World.html#contactPair).
 
+A `CollisionTarget` is an object containing references to objects involved in a collision event. It has the following properties:
+
+- `rigidBody` (if exists): `Rapier.RigidBody`
+- `rigidBodyObject` (if exists): `Three.Object3D`
+- `collider`: `Rapier.Collider`
+- `colliderObject`: `Three.Object3D`
+
 ### Configuring collision and solver groups
 
 Both `<RigidBody>` as well as all collider components allow you to configure `collisionsGroups` and `solverGroups` properties that configures which groups the colliders are in, and what other groups they should interact with in potential collision and solving events (you will find more details on this in the [Rapier documentation](https://rapier.rs/docs/user_guides/javascript/colliders/#collision-groups-and-solver-groups).)
@@ -296,10 +332,55 @@ When the second argument is omitted, the collider will interact with all groups:
 
 > **Note** By default, colliders are members of all groups, and will interact with all other groups.
 
+## Contact force events
+
+Contact force events are triggered on `<RigidBody>` and any collider components when two objects collider.
+
+```tsx
+<RigidBody
+  colliders="ball"
+  onContactForce={(payload) => {
+    console.log(`The total force generated was: ${payload.totalForce}`);
+  }}>
+  <Sphere>
+    <meshPhysicalMaterial color={'grey'}>
+  </Sphere>
+</RigidBody>
+```
+
+The payload for the contact force event contains the following properties:
+
+- `target`  
+  `CollisionTarget` of the object firing the event
+- `other`  
+  `CollisionTarget` of the other object involved in the event
+- `totalForce`  
+  The sum of all the forces between the two colliders
+- `totalForceMagnitude`  
+  The sum of the magnitudes of each force between the two colliders
+- `maxForceDirection`  
+  The magnitude of the largest force at a contact point of this contact pair
+- `maxForceMagnitude`  
+  The world-space (unit) direction of the force with strongest magnitude
+
+More information about each property can be found in the rapier [TempContactForceEvent API documentation](https://rapier.rs/javascript3d/classes/TempContactForceEvent.html).
+
+You can also add the `onContactForce` event to any collider.
+
+```tsx
+<CapsuleCollider
+  onContactForce={(payload) => {
+    /* ... */
+  }}
+/>
+```
+
 ## Sensors
 
 A Collider can be set to be a sensor, which means that it will not generate any contact points, and will not be affected by forces. This is useful for detecting when a collider enters or leaves another collider, without affecting the other collider.
 
+To detect when a collider enters or leaves another collider, you can use the `onIntersectionEnter` and `onIntersectionExit` events on the collider.
+
 ```tsx
 <RigidBody>
   <GoalPosts />
@@ -312,9 +393,39 @@ A Collider can be set to be a sensor, which means that it will not generate any
 </RigidBody>
 ```
 
-## Joints
+## Attractors
 
-WIP
+An attractor simulates a source of gravity. Any `RigidBody` within range will be _pulled_ (attracted) toward the attractor.  
+Setting the `strength` to a negative value will cause the `RigidBody` to be _pushed_ (repelled) away from the attractor.
+
+The force applied to rigid-bodies within range is calculated differently depending on the `type`.
+
+```tsx
+// Standard attractor
+<Attractor range={10} strength={5} type="linear" position={[5, -5, 0]} />
+
+// An attractor with negative strength, repels RigidBodies
+<Attractor range={10} strength={-5} position={[5, -5, 0]} />
+
+// You can also assign InteractionGroups.
+// An attractor belonging to group 0 only affecting bodies in group 2, and 3
+<Attractor range={10} strength={10} position={[5, -5, 0]} collisionGroups={interactionGroups(0, [2,3])} />
+```
+
+Gravity types:
+
+- "static" (Default)  
+  Static gravity means that the same force (`strength`) is applied on all rigid-bodies within range, regardless of distance.
+
+- "linear"  
+  Linear gravity means that force is calculated as `strength * distance / range`. That means the force applied decreases the farther a rigid-body is from the attractor position.
+
+- "newtonian"  
+  Newtonian gravity uses the traditional method of calculating gravitational force (`F = GMm/r^2`) and as such force is calculated as `gravitationalConstant * mass1 * mass2 / Math.pow(distance, 2)`.
+  - `gravitationalConstant` defaults to 6.673e-11 but you can provide your own
+  - `mass1` here is the "mass" of the Attractor, which is just the `strength` property
+  - `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
 
 ## Configuring Time Step Size
 
@@ -332,23 +443,16 @@ 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
+
+You can also manually step the physics simulation by calling the `step` method from the `useRapier` hook.
+
+```tsx
+const { step } = useRapier();
+
+step(1 / 60);
+```
 
-## Roadmap
-
-In order, but also not necessarily:
-
-- [x] RigidBodies, Colliders
-- [x] Joints
-- [x] Nested objects retain world transforms
-- [x] Nested objects retain correct collider scale
-- [x] Automatic colliders based on rigidbody children
-- [x] Translation and rotational constraints
-- [x] Collision events
-- [x] Colliders outside RigidBodies
-- [x] InstancedMesh support
-- [x] Timestep improvements for determinism
-- [x] Normalize and improve collision events (add events to single Colliders)
-- [x] Add collision events to InstancedRigidBodies
-- [ ] Docs
-- [ ] CodeSandbox examples
+## Joints
+
+WIP