@react-three/rapier 0.6.8 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/rapier",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "source": "src/index.ts",
   "main": "dist/react-three-rapier.cjs.js",
   "module": "dist/react-three-rapier.esm.js",
@@ -20,12 +20,12 @@
   "peerDependencies": {
     "@react-three/fiber": "^8.0.12",
     "react": "^18.0.0",
-    "three": "^0.139.2",
-    "three-stdlib": "^2.15.0"
+    "three": ">=0.139.2"
   },
   "dependencies": {
     "@dimforge/rapier3d-compat": "0.9.0",
-    "use-asset": "^1.0.4"
+    "use-asset": "^1.0.4",
+    "three-stdlib": "^2.15.0"
   },
   "repository": "https://github.com/pmndrs/react-three-rapier/tree/master/packages/react-three-rapier"
 }

package/readme.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/hero.svg" alt="@react-three/rapier" />
+  <a href="#"><img src="https://raw.githubusercontent.com/pmndrs/react-three-rapier/HEAD/packages/react-three-rapier/misc/hero.svg" alt="@react-three/rapier" /></a>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/@react-three/rapier?style=for-the-badge&colorA=0099DA&colorB=ffffff" />
-  <img src="https://img.shields.io/discord/740090768164651008?style=for-the-badge&colorA=0099DA&colorB=ffffff&label=discord&logo=discord&logoColor=ffffff)](https://discord.gg/ZZjjNvJ" />
+  <a href="https://www.npmjs.com/package/@react-three/rapier"><img src="https://img.shields.io/npm/v/@react-three/rapier?style=for-the-badge&colorA=0099DA&colorB=ffffff" /></a>
+  <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>
@@ -141,7 +141,7 @@ const Scene = () => {
     instancedApi.at(40).applyImpulse({ x: 0, y: 10, z: 0 });
 
     // Or update all instances as if they were in an array
-    instancedApi.forEach((api) => {
+    instancedApi.forEach(api => {
       api.applyImpulse({ x: 0, y: 10, z: 0 });
     });
   }, []);
@@ -153,13 +153,13 @@ const Scene = () => {
   const rotations = Array.from({ length: COUNT }, (_, index) => [
     Math.random(),
     Math.random(),
-    Math.random(),
+    Math.random()
   ]);
 
   const scales = Array.from({ length: COUNT }, (_, index) => [
     Math.random(),
     Math.random(),
-    Math.random(),
+    Math.random()
   ]);
 
   return (
@@ -210,9 +210,9 @@ const Scene = () => {
 };
 ```
 
-## Events
+## Collision Events
 
-You can subscribe collision and state events on the RigidBody.
+You can subscribe to collision and state events on a RigidBody:
 
 ```tsx
 const RigidBottle = () => {
@@ -235,6 +235,76 @@ return (
 }
 ```
 
+You may also subscribe to collision events on individual Colliders:
+
+```tsx
+<CuboidCollider
+  onCollisionEnter={payload => {
+    /* ... */
+  }}
+  onCollisionExit={payload => {
+    /* ... */
+  }}
+/>
+```
+
+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)  
+  The [contact manifold](https://rapier.rs/javascript3d/classes/TempContactManifold.html) generated by the collision event.
+- `flipped` (enter only)  
+  `true` if the data in the `manifold` [is flipped](https://rapier.rs/javascript3d/classes/World.html#contactPair).
+
+### 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).)
+
+Since these are set as bitmasks and bitmasks can get a bit unwieldy to generate, this library provides a helper called `interactionGroups` that can be used to generate bitmasks from numbers and arrays of groups, where groups are identified using numbers from 0 to 15.
+
+The first argument is the group, or an array of groups, that the collider is a member of; the second argument is the group, or an array of groups, that the collider should interact with.
+
+Here the collider is in group 0, and interacts with colliders from groups 0, 1 and 2:
+
+```tsx
+<CapsuleCollider collisionGroups={interactionGroups(0, [0, 1, 2])} />
+```
+
+This collider is in multiple groups, but only interacts with colliders from a single group:
+
+```tsx
+<CapsuleCollider collisionGroups={interactionGroups([0, 5], 7)} />
+```
+
+When the second argument is omitted, the collider will interact with all groups:
+
+```tsx
+<CapsuleCollider collisionGroups={interactionGroups(12)} />
+```
+
+> **Note** Please remember that in Rapier, for a collision (or solving) event to occur, both colliders involved in the event must match the related interaction groups -- a one-way match will be ignored.
+
+> **Note** By default, colliders are members of all groups, and will interact with all other groups.
+
+## 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.
+
+```tsx
+<RigidBody>
+  <GoalPosts />
+
+  <CuboidCollider
+    args={[5, 5, 1]}
+    sensor
+    onIntersectionEnter={() => console.log("Goal!")}
+  />
+</RigidBody>
+```
+
 ## Joints
 
 WIP
@@ -255,7 +325,7 @@ In order, but also not necessarily:
 - [x] Colliders outside RigidBodies
 - [x] InstancedMesh support
 - [x] Timestep improvements for determinism
-- [ ] Normalize and improve collision events (add events to single Colliders, InstancedRigidBodies, etc)
+- [x] Normalize and improve collision events (add events to single Colliders)
+- [ ] Add collision events to InstancedRigidBodies
 - [ ] Docs
 - [ ] CodeSandbox examples
-- [ ] Helpers, for things like Vehicle, Rope, Player, etc