@react-three/rapier 0.2.0 → 0.4.0

package/dist/react-three-rapier.esm.js

@@ -1,9 +1,9 @@
-import React, { useRef, useState, useLayoutEffect, useMemo, createContext, useContext, useEffect, forwardRef, useImperativeHandle, memo } from 'react';
+import React, { useRef, useState, useEffect, useMemo, createContext, useContext, forwardRef, useImperativeHandle, memo } from 'react';
 import { useAsset } from 'use-asset';
 import { useFrame } from '@react-three/fiber';
-import { Vector3, Quaternion, Object3D, Euler, CylinderBufferGeometry, BufferGeometry, BufferAttribute, SphereBufferGeometry, BoxBufferGeometry } from 'three';
-import { ColliderDesc, CoefficientCombineRule, ShapeType } from '@dimforge/rapier3d-compat';
+import { ColliderDesc, CoefficientCombineRule, ActiveEvents, EventQueue, ShapeType } from '@dimforge/rapier3d-compat';
 export { CoefficientCombineRule, Collider as RapierCollider, RigidBody as RapierRigidBody } from '@dimforge/rapier3d-compat';
+import { Vector3, Quaternion, Object3D, Euler, CylinderBufferGeometry, BufferGeometry, BufferAttribute, SphereBufferGeometry, BoxBufferGeometry } from 'three';
 
 const vectorArrayToObject = arr => {
   const [x, y, z] = arr;
@@ -38,11 +38,11 @@ const scaleColliderArgs = (shape, args, scale) => {
   const scaleArray = [scale.x, scale.y, scale.z];
   return newArgs.map((arg, index) => scaleArray[index] * arg);
 };
-const createColliderFromOptions = (options, world, rigidBodyHandle, scale = {
+const createColliderFromOptions = (options, world, rigidBody, scale = {
   x: 1,
   y: 1,
   z: 1
-}) => {
+}, hasCollisionEvents = false) => {
   var _options$shape, _options$args, _options$restitution, _options$restitutionC, _options$friction, _options$frictionComb;
 
   const mass = (options === null || options === void 0 ? void 0 : options.mass) || 1;
@@ -60,7 +60,12 @@ const createColliderFromOptions = (options, world, rigidBodyHandle, scale = {
     y: ry,
     z: rz,
     w: 1
-  }).setRestitution((_options$restitution = options === null || options === void 0 ? void 0 : options.restitution) !== null && _options$restitution !== void 0 ? _options$restitution : 0).setRestitutionCombineRule((_options$restitutionC = options === null || options === void 0 ? void 0 : options.restitutionCombineRule) !== null && _options$restitutionC !== void 0 ? _options$restitutionC : CoefficientCombineRule.Average).setFriction((_options$friction = options === null || options === void 0 ? void 0 : options.friction) !== null && _options$friction !== void 0 ? _options$friction : 0.7).setFrictionCombineRule((_options$frictionComb = options === null || options === void 0 ? void 0 : options.frictionCombineRule) !== null && _options$frictionComb !== void 0 ? _options$frictionComb : CoefficientCombineRule.Average); // If any of the mass properties are specified, add mass properties
+  }).setRestitution((_options$restitution = options === null || options === void 0 ? void 0 : options.restitution) !== null && _options$restitution !== void 0 ? _options$restitution : 0).setRestitutionCombineRule((_options$restitutionC = options === null || options === void 0 ? void 0 : options.restitutionCombineRule) !== null && _options$restitutionC !== void 0 ? _options$restitutionC : CoefficientCombineRule.Average).setFriction((_options$friction = options === null || options === void 0 ? void 0 : options.friction) !== null && _options$friction !== void 0 ? _options$friction : 0.7).setFrictionCombineRule((_options$frictionComb = options === null || options === void 0 ? void 0 : options.frictionCombineRule) !== null && _options$frictionComb !== void 0 ? _options$frictionComb : CoefficientCombineRule.Average);
+
+  if (hasCollisionEvents) {
+    colliderDesc = colliderDesc.setActiveEvents(ActiveEvents.COLLISION_EVENTS);
+  } // If any of the mass properties are specified, add mass properties
+
 
   if (options !== null && options !== void 0 && options.mass || options !== null && options !== void 0 && options.centerOfMass || options !== null && options !== void 0 && options.principalAngularInertia) {
     colliderDesc.setDensity(0);
@@ -80,10 +85,10 @@ const createColliderFromOptions = (options, world, rigidBodyHandle, scale = {
     });
   }
 
-  const collider = world.createCollider(colliderDesc, rigidBodyHandle);
+  const collider = world.createCollider(colliderDesc, rigidBody);
   return collider;
 };
-const createCollidersFromChildren = (object, rigidBody, type, world) => {
+const createCollidersFromChildren = (object, rigidBody, type, world, hasCollisionEvents = false) => {
   const colliders = [];
   let desc;
   let offset = new Vector3();
@@ -156,7 +161,12 @@ const createCollidersFromChildren = (object, rigidBody, type, world) => {
         z: rz,
         w: rw
       });
-      const collider = world.createCollider(desc, rigidBody.handle);
+
+      if (hasCollisionEvents) {
+        desc.setActiveEvents(ActiveEvents.COLLISION_EVENTS);
+      }
+
+      const collider = world.createCollider(desc, rigidBody);
       colliders.push(collider);
     }
   });
@@ -224,6 +234,31 @@ const createRigidBodyApi = ref => {
         w
       } = ref.current().rotation();
       return new Quaternion(x, y, z, w);
+    },
+
+    setNextKinematicRotation({
+      x,
+      y,
+      z
+    }) {
+      ref.current().setNextKinematicRotation({
+        x,
+        y,
+        z,
+        w: 1
+      });
+    },
+
+    setNextKinematicTranslation({
+      x,
+      y,
+      z
+    }) {
+      ref.current().setNextKinematicTranslation({
+        x,
+        y,
+        z
+      });
     }
 
   };
@@ -245,10 +280,10 @@ const createWorldApi = ref => {
     getCollider: handle => ref.current().getCollider(handle),
     getRigidBody: handle => ref.current().getRigidBody(handle),
     createRigidBody: desc => ref.current().createRigidBody(desc),
-    createCollider: (desc, rigidBodyHandle) => ref.current().createCollider(desc, rigidBodyHandle),
+    createCollider: (desc, rigidBody) => ref.current().createCollider(desc, rigidBody),
     removeRigidBody: rigidBody => ref.current().removeRigidBody(rigidBody),
     removeCollider: collider => ref.current().removeCollider(collider, true),
-    createImpulseJoint: (params, rigidBodyA, rigidBodyB) => ref.current().createImpulseJoint(params, rigidBodyA, rigidBodyB),
+    createImpulseJoint: (params, rigidBodyA, rigidBodyB) => ref.current().createImpulseJoint(params, rigidBodyA, rigidBodyB, true),
     removeImpulseJoint: joint => ref.current().removeImpulseJoint(joint, true),
     forEachCollider: callback => ref.current().forEachCollider(callback)
   };
@@ -291,9 +326,11 @@ const Physics = ({
     return worldRef.current;
   });
   const [colliderMeshes] = useState(() => new Map());
-  const [rigidBodyMeshes] = useState(() => new Map()); // Init world
+  const [rigidBodyMeshes] = useState(() => new Map());
+  const [rigidBodyEvents] = useState(() => new Map());
+  const [eventQueue] = useState(() => new EventQueue(false)); // Init world
 
-  useLayoutEffect(() => {
+  useEffect(() => {
     const world = getWorldRef.current();
     return () => {
       if (world) {
@@ -311,10 +348,27 @@ const Physics = ({
     const now = performance.now();
     const delta = Math.min(100, now - time.current);
     world.timestep = delta / 1000;
-    world.step(); // Update meshes
+    world.step(eventQueue); // Update meshes
 
     rigidBodyMeshes.forEach((mesh, handle) => {
       const rigidBody = world.getRigidBody(handle);
+      const events = rigidBodyEvents.get(handle);
+
+      if (events !== null && events !== void 0 && events.onSleep || events !== null && events !== void 0 && events.onWake) {
+        if (rigidBody.isSleeping() && !mesh.userData.isSleeping) {
+          var _events$onSleep;
+
+          events === null || events === void 0 ? void 0 : (_events$onSleep = events.onSleep) === null || _events$onSleep === void 0 ? void 0 : _events$onSleep.call(events);
+        }
+
+        if (!rigidBody.isSleeping() && mesh.userData.isSleeping) {
+          var _events$onWake;
+
+          events === null || events === void 0 ? void 0 : (_events$onWake = events.onWake) === null || _events$onWake === void 0 ? void 0 : _events$onWake.call(events);
+        }
+
+        mesh.userData.isSleeping = rigidBody.isSleeping();
+      }
 
       if (!rigidBody || rigidBody.isSleeping() || rigidBody.isFixed() || !mesh.parent) {
         return;
@@ -342,6 +396,50 @@ const Physics = ({
       o.updateMatrix();
       mesh.position.setFromMatrixPosition(o.matrix);
       mesh.rotation.setFromRotationMatrix(o.matrix);
+    }); // Collision events
+
+    eventQueue.drainCollisionEvents((handle1, handle2, started) => {
+      var _collider1$parent, _collider2$parent;
+
+      const collider1 = world.getCollider(handle1);
+      const collider2 = world.getCollider(handle2);
+      const rigidBodyHandle1 = (_collider1$parent = collider1.parent()) === null || _collider1$parent === void 0 ? void 0 : _collider1$parent.handle;
+      const rigidBodyHandle2 = (_collider2$parent = collider2.parent()) === null || _collider2$parent === void 0 ? void 0 : _collider2$parent.handle;
+
+      if (!collider1 || !collider2 || !rigidBodyHandle1 || !rigidBodyHandle2) {
+        return;
+      }
+
+      const rigidBody1 = world.getRigidBody(rigidBodyHandle1);
+      const rigidBody2 = world.getRigidBody(rigidBodyHandle2);
+      const events1 = rigidBodyEvents.get(rigidBodyHandle1);
+      const events2 = rigidBodyEvents.get(rigidBodyHandle2);
+
+      if (started) {
+        world.contactPair(collider1, collider2, (manifold, flipped) => {
+          var _events1$onCollisionE, _events2$onCollisionE;
+
+          events1 === null || events1 === void 0 ? void 0 : (_events1$onCollisionE = events1.onCollisionEnter) === null || _events1$onCollisionE === void 0 ? void 0 : _events1$onCollisionE.call(events1, {
+            target: rigidBody2,
+            manifold,
+            flipped
+          });
+          events2 === null || events2 === void 0 ? void 0 : (_events2$onCollisionE = events2.onCollisionEnter) === null || _events2$onCollisionE === void 0 ? void 0 : _events2$onCollisionE.call(events2, {
+            target: rigidBody1,
+            manifold,
+            flipped
+          });
+        });
+      } else {
+        var _events1$onCollisionE2, _events2$onCollisionE2;
+
+        events1 === null || events1 === void 0 ? void 0 : (_events1$onCollisionE2 = events1.onCollisionExit) === null || _events1$onCollisionE2 === void 0 ? void 0 : _events1$onCollisionE2.call(events1, {
+          target: rigidBody2
+        });
+        events2 === null || events2 === void 0 ? void 0 : (_events2$onCollisionE2 = events2.onCollisionExit) === null || _events2$onCollisionE2 === void 0 ? void 0 : _events2$onCollisionE2.call(events2, {
+          target: rigidBody1
+        });
+      }
     });
     time.current = now;
   });
@@ -354,7 +452,8 @@ const Physics = ({
       gravity: _gravity
     },
     colliderMeshes,
-    rigidBodyMeshes
+    rigidBodyMeshes,
+    rigidBodyEvents
   }), []);
   return /*#__PURE__*/React.createElement(RapierContext.Provider, {
     value: context
@@ -410,7 +509,8 @@ const useRigidBody = (options = {}) => {
     rapier,
     world,
     rigidBodyMeshes,
-    physicsOptions
+    physicsOptions,
+    rigidBodyEvents
   } = useRapier();
   const ref = useRef(); // Create rigidbody
 
@@ -431,7 +531,7 @@ const useRigidBody = (options = {}) => {
         z: avz
       }).setGravityScale(gravityScale).setCanSleep(canSleep).setCcdEnabled(ccdEnabled);
       const rigidBody = world.createRigidBody(desc);
-      rigidBodyRef.current = rigidBody;
+      rigidBodyRef.current = world.getRigidBody(rigidBody.handle);
     }
 
     return rigidBodyRef.current;
@@ -445,8 +545,10 @@ const useRigidBody = (options = {}) => {
 
     if (!ref.current) {
       ref.current = new Object3D();
-    } // Get intitial world transforms
+    } // isSleeping used for onSleep and onWake events
+
 
+    ref.current.userData.isSleeping = false; // Get intitial world transforms
 
     const worldPosition = ref.current.getWorldPosition(new Vector3());
     const worldRotation = ref.current.getWorldQuaternion(new Quaternion());
@@ -464,6 +566,7 @@ const useRigidBody = (options = {}) => {
       y: worldPosition.y + y * scale.y,
       z: worldPosition.z + z * scale.z
     }, false);
+    console.log(rigidBody.isKinematic());
     const eulerAngles = new Euler(rx, ry, rz, 'XYZ');
     const rotation = new Quaternion().setFromEuler(eulerAngles).multiply(worldRotation);
     rigidBody.setRotation({
@@ -475,16 +578,31 @@ const useRigidBody = (options = {}) => {
     rigidBody.resetForces(false);
     rigidBody.resetTorques(false);
     const colliderSetting = (_ref = (_options$colliders = options === null || options === void 0 ? void 0 : options.colliders) !== null && _options$colliders !== void 0 ? _options$colliders : physicsOptions.colliders) !== null && _ref !== void 0 ? _ref : false;
-    const autoColliders = colliderSetting !== false ? createCollidersFromChildren(ref.current, rigidBody, colliderSetting, world) : [];
+    const hasCollisionEvents = !!(options.onCollisionEnter || options.onCollisionExit);
+    const autoColliders = colliderSetting !== false ? createCollidersFromChildren(ref.current, rigidBody, colliderSetting, world, hasCollisionEvents) : [];
     rigidBody.wakeUp();
     rigidBodyMeshes.set(rigidBody.handle, ref.current);
     return () => {
+      const actualBody = world.getRigidBody(rigidBody.handle);
+      world.removeRigidBody(actualBody);
       autoColliders.forEach(collider => world.removeCollider(collider));
-      world.removeRigidBody(rigidBody);
       rigidBodyRef.current = undefined;
       rigidBodyMeshes.delete(rigidBody.handle);
     };
-  }, []);
+  }, []); // Events
+
+  useEffect(() => {
+    const rigidBody = getRigidBodyRef.current();
+    rigidBodyEvents.set(rigidBody.handle, {
+      onCollisionEnter: options === null || options === void 0 ? void 0 : options.onCollisionEnter,
+      onCollisionExit: options === null || options === void 0 ? void 0 : options.onCollisionExit,
+      onSleep: options === null || options === void 0 ? void 0 : options.onSleep,
+      onWake: options === null || options === void 0 ? void 0 : options.onWake
+    });
+    return () => {
+      rigidBodyEvents.delete(rigidBody.handle);
+    };
+  }, [options.onCollisionEnter, options.onCollisionExit]);
   const api = useMemo(() => createRigidBodyApi(getRigidBodyRef), []);
   return [ref, api];
 };
@@ -496,7 +614,7 @@ const useCollider = (body, options = {}) => {
   const objectRef = useRef();
   const getColliderRef = useRef(() => {
     if (!colliderRef.current) {
-      colliderRef.current = createColliderFromOptions(options, world, body.handle);
+      colliderRef.current = createColliderFromOptions(options, world, world.getRigidBody(body.handle));
     }
 
     return colliderRef.current;
@@ -522,7 +640,7 @@ const useRigidBodyWithCollider = (rigidBodyOptions, colliderOptions) => {
     }
 
     const scale = ref.current.getWorldScale(new Vector3());
-    const collider = createColliderFromOptions(colliderOptions, world, rigidBody.handle, scale);
+    const collider = createColliderFromOptions(colliderOptions, world, world.getRigidBody(rigidBody.handle), scale);
     return () => {
       world.removeCollider(collider);
     };
@@ -678,7 +796,6 @@ const useImpulseJoint = (body1, body2, params) => {
     const joint = getJointRef.current();
     return () => {
       if (joint) {
-        console.log('remove joint', joint);
         world.removeImpulseJoint(joint);
         jointRef.current = undefined;
       }
@@ -798,7 +915,7 @@ const _excluded = ["children"],
       _excluded2 = ["children"];
 const RigidBodyContext = /*#__PURE__*/createContext(undefined);
 
-const useParentRigidBody = () => useContext(RigidBodyContext); // RigidBody
+const useRigidBodyContext = () => useContext(RigidBodyContext); // RigidBody
 
 
 const RigidBody = /*#__PURE__*/forwardRef((_ref, ref) => {
@@ -810,7 +927,7 @@ const RigidBody = /*#__PURE__*/forwardRef((_ref, ref) => {
   const [object, rigidBody] = useRigidBody(props);
   useImperativeHandle(ref, () => rigidBody);
   return /*#__PURE__*/React.createElement(RigidBodyContext.Provider, {
-    value: [object, rigidBody]
+    value: [object, rigidBody, !!(props.onCollisionEnter || props.onCollisionExit)]
   }, /*#__PURE__*/React.createElement("object3D", {
     ref: object
   }, children));
@@ -825,11 +942,11 @@ const AnyCollider = _ref2 => {
   const {
     world
   } = useRapier();
-  const [, rigidBody] = useParentRigidBody();
+  const [, rigidBody, hasCollisionEvents] = useRigidBodyContext();
   const ref = useRef(null);
   useEffect(() => {
     const scale = ref.current.getWorldScale(new Vector3());
-    const collider = createColliderFromOptions(props, world, rigidBody.handle, scale);
+    const collider = createColliderFromOptions(props, world, world.getRigidBody(rigidBody.handle), scale, hasCollisionEvents);
     return () => {
       world.removeCollider(collider);
     };
@@ -886,20 +1003,20 @@ const ConvexHullCollider = props => {
 };
 
 const geometryFromCollider = collider => {
-  switch (collider.shapeType()) {
+  switch (collider.shape.type) {
     case ShapeType.Cuboid:
       {
         const {
           x,
           y,
           z
-        } = collider.halfExtents();
+        } = collider.shape.halfExtents;
         return new BoxBufferGeometry(x * 2 + 0.01, y * 2 + 0.01, z * 2 + 0.01);
       }
 
     case ShapeType.Ball:
       {
-        const r = collider.radius();
+        const r = collider.shape.radius;
         return new SphereBufferGeometry(r + +0.01, 8, 8);
       }
 
@@ -907,10 +1024,12 @@ const geometryFromCollider = collider => {
       {
         var _g$index;
 
-        const v = collider.vertices();
-        const i = collider.indices();
-        const g = new BufferGeometry();
-        g.setAttribute("position", new BufferAttribute(v, 3));
+        const v = collider.shape.vertices;
+        const i = collider.shape.indices;
+        const g = new BufferGeometry(); // Vertices are not always a float3darray (???), so we need to convert them
+
+        const safeVerts = Float32Array.from(v);
+        g.setAttribute("position", new BufferAttribute(safeVerts, 3));
         (_g$index = g.index) === null || _g$index === void 0 ? void 0 : _g$index.set(i);
         g.setDrawRange(0, g.attributes.position.array.length / 3 - 1);
         return g;
@@ -918,16 +1037,18 @@ const geometryFromCollider = collider => {
 
     case ShapeType.ConvexPolyhedron:
       {
-        const cv = collider.vertices();
+        const cv = collider.shape.vertices; // Vertices are not always a float3darray (???), so we need to convert them
+
+        const safeVerts = Float32Array.from(cv);
         const cg = new BufferGeometry();
-        cg.setAttribute("position", new BufferAttribute(cv, 3));
+        cg.setAttribute("position", new BufferAttribute(safeVerts, 3));
         return cg;
       }
 
     case ShapeType.Cylinder:
       {
-        const r = collider.radius();
-        const h = collider.halfHeight();
+        const r = collider.shape.radius;
+        const h = collider.shape.halfHeight;
         const g = new CylinderBufferGeometry(r, r, h);
         return g;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/rapier",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "source": "src/index.ts",
   "main": "dist/react-three-rapier.cjs.js",
   "module": "dist/react-three-rapier.esm.js",
@@ -23,7 +23,7 @@
     "three": "^0.139.2"
   },
   "dependencies": {
-    "@dimforge/rapier3d-compat": "^0.8.0-alpha.2",
+    "@dimforge/rapier3d-compat": "0.8.1",
     "use-asset": "^1.0.4"
   },
   "repository": "https://github.com/pmndrs/react-three-rapier/tree/master/packages/react-three-rapier"

package/readme.md

@@ -0,0 +1,176 @@
+<h1 align="center">@react-three/rapier 🗡</h1>
+
+<p align="center">⚠️ Under heavy development. All APIs are subject to change. ⚠️</p>
+
+## Usage
+
+```tsx
+import { Box } from "@react-three/drei";
+import { Canvas } from "@react-three/fiber";
+import { Physics, RigidBody } from "@react-three/rapier";
+
+const App = () => {
+  return (
+    <Canvas>
+      <Physics>
+        <RigidBody>
+          <Box />
+        </RigidBody>
+      </Physics>
+    </Canvas>
+  );
+};
+```
+
+## 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.
+
+Supported values:
+
+- `"cuboid"`, creates a CuboidCollider based on the bounding box of the mesh
+- `"ball"`, creates a SphereCollider based on the bounding sphere of the mesh
+- `"trimesh"`, creates a TrimeshCollider based on the mesh's geometry -- note trimeshes are massless by default (https://rapier.rs/docs/user_guides/javascript/common_mistakes#rigid-body-isnt-affected-by-gravity)
+- `"hull"`, creates a ConvexHullCollider based on the mesh's geometry
+- `false`, disables auto-generation
+
+Generate ConvexHull colliders for all meshes in a RigidBody by default:
+
+```tsx
+const Scene = () => (
+  <Physics colliders="hull">
+    <RigidBody>
+      <Box />
+    </RigidBody>
+    <RigidBody position={[0, 10, 0]}>
+      <Sphere />
+    </RigidBody>
+  </Physics>
+);
+```
+
+Turn off automatic collider generation globally, but apply auto generation locally:
+
+```tsx
+const Scene = () => (
+  <Physics colliders={false}>
+    <RigidBody colliders="cuboid">
+      <Box />
+    </RigidBody>
+
+    <RigidBody position={[0, 10, 0]} colliders="ball">
+      <Sphere />
+    </RigidBody>
+
+    <RigidBody position={[0, 10, 0]}>
+      <Sphere />
+      <BallCollider args={0.5} />
+      <BallCollider args={0.5} position={[1, 0, 0]} />
+    </RigidBody>
+  </Physics>
+);
+```
+
+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.
+
+```tsx
+import { Box } from "@react-three/drei";
+import { RigidBody, CuboidCollider } from "@react-three/rapier";
+
+const Scene = () => {
+  return (
+    <group position={[2, 5, 0]} rotation={[0, 0.3, 2]}>
+      <RigidBody>
+        <Box />
+        <CuboidCollider args={[0.5, 0.5, 0.5]} />
+      </RigidBody>
+    </group>
+  );
+};
+```
+
+## Debug
+
+Use the Debug component to see live representations of all colliders in a scene.
+
+> Note: Experimental. Not all shapes are supported. Unsupported shapes are always represented by cubes.
+
+```tsx
+import { Box, Sphere } from "@react-three/drei";
+import { RigidBody, Debug } from "@react-three/rapier";
+
+const Scene = () => {
+  return (
+    <Physics>
+      <Debug />
+
+      <RigidBody>
+        <Box />
+      </RigidBody>
+      <RigidBody>
+        <Sphere />
+      </RigidBody>
+    </Physics>
+  );
+};
+```
+
+## Events
+
+You can subscribe collision and state events on the RigidBody.
+
+```tsx
+const RigidBottle = () => {
+  const [isAsleep, setIsAsleep] = useState(false);
+
+return (
+    <RigidBody
+      colliders="hull"
+      onSleep={() => setIsAsleep(true)}
+      onWake={() => setIsAsleep(false)}
+      onCollision={({manifold}) => {
+        console.log('Collision at world position ', manifold.solverContactPoint(0))
+      }}
+    >
+      <Sphere>
+        <meshPhysicalMaterial color={isAsleep ? 'white' : 'blue'}>
+      </Sphere>
+    </RigidBody>
+  )
+}
+```
+
+## Hooks
+
+You can also use hooks to generate rigid bodies and colliders, but it's not encouraged.
+
+```tsx
+import { Box } from "@react-three/drei";
+import { useCuboid } from "@react-three/rapier";
+
+const RigidBox = () => {
+  // Generates a RigidBody and attaches a BoxCollider to it, returns a ref
+  const [box, rigidBody, collider] = useCuboid(
+    { position: [1, 1, 1] },
+    { args: [0.5, 0.5, 0.5] }
+  );
+
+  return <Box ref={box} />;
+};
+```
+
+## Roadmap?
+
+In order, but also not necessarily:
+
+- [x] Draft of all base shapes
+- [x] Draft of all base joints
+- [x] Nested objects retain world transforms
+- [x] Nested objects retain correct collider scale
+- [x] Automatic colliders based on rigidbody children
+- [ ] Translation and rotational constraints
+- [x] Collision events
+- [ ] InstancedMesh support
+- [ ] Docs
+- [ ] CodeSandbox examples
+- [ ] Helpers, for things like Vehicle, Rope, Player, etc