@react-three/rapier 0.12.2 → 0.13.0

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

@@ -1,8 +1,8 @@
-import { ColliderDesc, ActiveEvents, RigidBodyDesc, EventQueue } from '@dimforge/rapier3d-compat';
+import { ActiveEvents, ColliderDesc, EventQueue, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 export { CoefficientCombineRule, Collider as RapierCollider, RigidBody as RapierRigidBody } from '@dimforge/rapier3d-compat';
 import { useFrame, useThree } from '@react-three/fiber';
-import React, { useRef, useMemo, useEffect, useContext, useState, memo, createContext, useCallback, forwardRef, useImperativeHandle, useLayoutEffect } from 'react';
-import { Quaternion, Euler, Vector3, Object3D, Matrix4, MathUtils, InstancedMesh, BufferAttribute, DynamicDrawUsage } from 'three';
+import React, { useRef, useMemo, useEffect, useContext, useState, memo, createContext, useCallback, forwardRef, useImperativeHandle, Fragment } from 'react';
+import { Quaternion, Euler, Vector3, Object3D, Matrix4, MathUtils, BufferAttribute, DynamicDrawUsage } from 'three';
 import { useAsset } from 'use-asset';
 import { mergeVertices, VertexNormalsHelper } from 'three-stdlib';
 
@@ -47,10 +47,44 @@ function _objectSpread2(target) {
   return target;
 }
 
+const createWorldApi = ref => {
+  return {
+    raw: () => ref.current(),
+    getCollider: handle => ref.current().getCollider(handle),
+    getRigidBody: handle => ref.current().getRigidBody(handle),
+    createRigidBody: desc => ref.current().createRigidBody(desc),
+    createCollider: (desc, rigidBody) => ref.current().createCollider(desc, rigidBody),
+    removeRigidBody: rigidBody => {
+      if (!ref.current().bodies.contains(rigidBody.handle)) return;
+      ref.current().removeRigidBody(rigidBody);
+    },
+    removeCollider: (collider, wakeUp = true) => {
+      if (!ref.current().colliders.contains(collider.handle)) return;
+      ref.current().removeCollider(collider, wakeUp);
+    },
+    createImpulseJoint: (params, rigidBodyA, rigidBodyB, wakeUp = true) => ref.current().createImpulseJoint(params, rigidBodyA, rigidBodyB, wakeUp),
+    removeImpulseJoint: (joint, wakeUp = true) => {
+      if (!ref.current().impulseJoints.contains(joint.handle)) return;
+      ref.current().removeImpulseJoint(joint, wakeUp);
+    },
+    forEachCollider: callback => ref.current().forEachCollider(callback),
+    setGravity: ({
+      x,
+      y,
+      z
+    }) => ref.current().gravity = {
+      x,
+      y,
+      z
+    },
+    debugRender: () => ref.current().debugRender()
+  };
+};
+
 const _quaternion = new Quaternion();
 new Euler();
 const _vector3 = new Vector3();
-const _object3d = new Object3D();
+new Object3D();
 const _matrix4 = new Matrix4();
 const _position = new Vector3();
 const _rotation = new Quaternion();
@@ -66,11 +100,6 @@ const tupleToObject = (tuple, keys) => {
     return obj;
   }, {});
 };
-const rapierVector3ToVector3 = ({
-  x,
-  y,
-  z
-}) => _vector3.set(x, y, z);
 const rapierQuaternionToQuaternion = ({
   x,
   y,
@@ -124,152 +153,6 @@ function useConst(initialValue) {
   return ref.current.value;
 }
 
-const createRigidBodyApi = ref => {
-  return {
-    raw: () => ref.current(),
-
-    get handle() {
-      return ref.current().handle;
-    },
-
-    mass: () => ref.current().mass(),
-
-    applyImpulse(impulseVector, wakeUp = true) {
-      ref.current().applyImpulse(impulseVector, wakeUp);
-    },
-
-    applyTorqueImpulse(torqueVector, wakeUp = true) {
-      ref.current().applyTorqueImpulse(torqueVector, wakeUp);
-    },
-
-    applyImpulseAtPoint: (impulseVector, impulsePoint, wakeUp = true) => ref.current().applyImpulseAtPoint(impulseVector, impulsePoint, wakeUp),
-    addForce: (force, wakeUp = true) => ref.current().addForce(force, wakeUp),
-    addForceAtPoint: (force, point, wakeUp = true) => ref.current().addForceAtPoint(force, point, wakeUp),
-    addTorque: (torque, wakeUp = true) => ref.current().addTorque(torque, wakeUp),
-
-    translation() {
-      return rapierVector3ToVector3(ref.current().translation());
-    },
-
-    setTranslation: (translation, wakeUp = true) => ref.current().setTranslation(translation, wakeUp),
-
-    rotation() {
-      const {
-        x,
-        y,
-        z,
-        w
-      } = ref.current().rotation();
-      return new Quaternion(x, y, z, w);
-    },
-
-    setRotation: (rotation, wakeUp = true) => {
-      ref.current().setRotation(rotation, wakeUp);
-    },
-
-    linvel() {
-      const {
-        x,
-        y,
-        z
-      } = ref.current().linvel();
-      return new Vector3(x, y, z);
-    },
-
-    setLinvel: (velocity, wakeUp = true) => ref.current().setLinvel(velocity, wakeUp),
-
-    angvel() {
-      const {
-        x,
-        y,
-        z
-      } = ref.current().angvel();
-      return new Vector3(x, y, z);
-    },
-
-    setAngvel: (velocity, wakeUp = true) => ref.current().setAngvel(velocity, wakeUp),
-
-    linearDamping() {
-      return ref.current().linearDamping();
-    },
-
-    setLinearDamping: factor => ref.current().setLinearDamping(factor),
-
-    angularDamping() {
-      return ref.current().angularDamping();
-    },
-
-    setAngularDamping: factor => ref.current().setAngularDamping(factor),
-    setNextKinematicRotation: rotation => {
-      ref.current().setNextKinematicRotation(rotation);
-    },
-    setNextKinematicTranslation: translation => ref.current().setNextKinematicTranslation(translation),
-    resetForces: (wakeUp = true) => ref.current().resetForces(wakeUp),
-    resetTorques: (wakeUp = true) => ref.current().resetTorques(wakeUp),
-    lockRotations: (locked, wakeUp = true) => ref.current().lockRotations(locked, wakeUp),
-    lockTranslations: (locked, wakeUp = true) => ref.current().lockTranslations(locked, wakeUp),
-    setEnabledRotations: (x, y, z, wakeUp = true) => ref.current().setEnabledRotations(x, y, z, wakeUp),
-    setEnabledTranslations: (x, y, z, wakeUp = true) => ref.current().setEnabledTranslations(x, y, z, wakeUp)
-  };
-};
-const createInstancedRigidBodiesApi = bodiesGetter => ({
-  at: index => bodiesGetter.current()[index].api,
-
-  forEach(callback) {
-    return bodiesGetter.current().map(b => b.api).forEach(callback);
-  },
-
-  get count() {
-    return bodiesGetter.current().length;
-  }
-
-});
-const createWorldApi = ref => {
-  return {
-    raw: () => ref.current(),
-    getCollider: handle => ref.current().getCollider(handle),
-    getRigidBody: handle => ref.current().getRigidBody(handle),
-    createRigidBody: desc => ref.current().createRigidBody(desc),
-    createCollider: (desc, rigidBody) => ref.current().createCollider(desc, rigidBody),
-    removeRigidBody: rigidBody => {
-      if (!ref.current().bodies.contains(rigidBody.handle)) return;
-      ref.current().removeRigidBody(rigidBody);
-    },
-    removeCollider: (collider, wakeUp = true) => {
-      if (!ref.current().colliders.contains(collider.handle)) return;
-      ref.current().removeCollider(collider, wakeUp);
-    },
-    createImpulseJoint: (params, rigidBodyA, rigidBodyB, wakeUp = true) => ref.current().createImpulseJoint(params, rigidBodyA, rigidBodyB, wakeUp),
-    removeImpulseJoint: (joint, wakeUp = true) => {
-      if (!ref.current().impulseJoints.contains(joint.handle)) return;
-      ref.current().removeImpulseJoint(joint, wakeUp);
-    },
-    forEachCollider: callback => ref.current().forEachCollider(callback),
-    setGravity: ({
-      x,
-      y,
-      z
-    }) => ref.current().gravity = {
-      x,
-      y,
-      z
-    },
-    debugRender: () => ref.current().debugRender()
-  };
-};
-const createJointApi = ref => {
-  return {
-    raw: () => ref.current(),
-
-    get handle() {
-      return ref.current().handle;
-    },
-
-    configureMotorPosition: (targetPos, stiffness, damping) => ref.current().configureMotorPosition(targetPos, stiffness, damping),
-    configureMotorVelocity: (targetVel, damping) => ref.current().configureMotorVelocity(targetVel, damping)
-  };
-};
-
 const scaleColliderArgs = (shape, args, scale) => {
   const newArgs = args.slice(); // Heightfield uses a vector
 
@@ -291,11 +174,11 @@ const scaleColliderArgs = (shape, args, scale) => {
   const scaleArray = [scale.x, scale.y, scale.z, scale.x, scale.x];
   return newArgs.map((arg, index) => scaleArray[index] * arg);
 };
-const createColliderFromOptions = (options, world, scale, rigidBody) => {
+const createColliderFromOptions = (options, world, scale, getRigidBody) => {
   const scaledArgs = scaleColliderArgs(options.shape, options.args, scale); // @ts-ignore
 
   const desc = ColliderDesc[options.shape](...scaledArgs);
-  return world.createCollider(desc, rigidBody);
+  return world.createCollider(desc, getRigidBody === null || getRigidBody === void 0 ? void 0 : getRigidBody());
 };
 const massPropertiesConflictError = "Please pick ONLY ONE of the `density`, `mass` and `massProperties` options.";
 
@@ -399,15 +282,14 @@ const setColliderOptions = (collider, options, states) => {
     setColliderMassOptions(collider, options);
   }
 };
-const useUpdateColliderOptions = (collidersRef, props, states) => {
+const useUpdateColliderOptions = (getCollider, props, states) => {
   // TODO: Improve this, split each prop into its own effect
   const mutablePropsAsFlatArray = useMemo(() => mutableColliderOptionKeys.flatMap(key => {
     return vectorToTuple(props[key]);
   }), [props]);
   useEffect(() => {
-    collidersRef.current.forEach(collider => {
-      setColliderOptions(collider, props, states);
-    });
+    const collider = getCollider();
+    setColliderOptions(collider, props, states);
   }, mutablePropsAsFlatArray);
 };
 
@@ -530,7 +412,7 @@ const getColliderArgsFromGeometry = (geometry, colliders) => {
     offset: new Vector3()
   };
 };
-const useColliderEvents = (collidersRef, props, events) => {
+const useColliderEvents = (getCollider, props, events) => {
   const {
     onCollisionEnter,
     onCollisionExit,
@@ -539,9 +421,9 @@ const useColliderEvents = (collidersRef, props, events) => {
     onContactForce
   } = props;
   useEffect(() => {
-    var _collidersRef$current;
+    const collider = getCollider();
 
-    (_collidersRef$current = collidersRef.current) === null || _collidersRef$current === void 0 ? void 0 : _collidersRef$current.forEach(collider => {
+    if (collider) {
       const hasCollisionEvent = !!(onCollisionEnter || onCollisionExit || onIntersectionEnter || onIntersectionExit);
       const hasContactForceEvent = !!onContactForce;
 
@@ -560,265 +442,76 @@ const useColliderEvents = (collidersRef, props, events) => {
         onIntersectionExit,
         onContactForce
       });
-    });
-    return () => {
-      var _collidersRef$current2;
+    }
 
-      (_collidersRef$current2 = collidersRef.current) === null || _collidersRef$current2 === void 0 ? void 0 : _collidersRef$current2.forEach(collider => events.delete(collider.handle));
+    return () => {
+      if (collider) {
+        events.delete(collider.handle);
+      }
     };
   }, [onCollisionEnter, onCollisionExit, onIntersectionEnter, onIntersectionExit, onContactForce]);
 };
 
-const rigidBodyDescFromOptions = options => {
-  var _options$canSleep;
-
-  const type = rigidBodyTypeFromString((options === null || options === void 0 ? void 0 : options.type) || "dynamic");
-  const desc = new RigidBodyDesc(type); // Apply immutable options
+/**
+ * Exposes the Rapier context, and world
+ * @category Hooks
+ */
 
-  desc.canSleep = (_options$canSleep = options === null || options === void 0 ? void 0 : options.canSleep) !== null && _options$canSleep !== void 0 ? _options$canSleep : true;
-  return desc;
-};
-const createRigidBodyState = ({
-  rigidBody,
-  object,
-  setMatrix,
-  getMatrix,
-  worldScale
-}) => {
-  object.updateWorldMatrix(true, false);
-  const invertedWorldMatrix = object.parent.matrixWorld.clone().invert();
-  return {
-    object,
-    rigidBody,
-    invertedWorldMatrix,
-    setMatrix: setMatrix ? setMatrix : matrix => {
-      object.matrix.copy(matrix);
-    },
-    getMatrix: getMatrix ? getMatrix : matrix => matrix.copy(object.matrix),
-    scale: worldScale || object.getWorldScale(_scale).clone(),
-    isSleeping: false
-  };
+const useRapier = () => {
+  return useContext(rapierContext);
 };
-const mutableRigidBodyOptions = {
-  gravityScale: (rb, value) => {
-    rb.setGravityScale(value, true);
-  },
-  linearDamping: (rb, value) => {
-    rb.setLinearDamping(value);
-  },
-  angularDamping: (rb, value) => {
-    rb.setAngularDamping(value);
-  },
-  enabledRotations: (rb, [x, y, z]) => {
-    rb.setEnabledRotations(x, y, z, true);
-  },
-  enabledTranslations: (rb, [x, y, z]) => {
-    rb.setEnabledTranslations(x, y, z, true);
-  },
-  lockRotations: (rb, value) => {
-    rb.lockRotations(value, true);
-  },
-  lockTranslations: (rb, value) => {
-    rb.lockTranslations(value, true);
-  },
-  angularVelocity: (rb, [x, y, z]) => {
-    rb.setAngvel({
-      x,
-      y,
-      z
-    }, true);
-  },
-  linearVelocity: (rb, [x, y, z]) => {
-    rb.setLinvel({
-      x,
-      y,
-      z
-    }, true);
-  },
-  ccd: (rb, value) => {
-    rb.enableCcd(value);
-  },
-  userData: (rb, value) => {
-    rb.userData = value;
-  },
-
-  type(rb, value) {
-    rb.setBodyType(rigidBodyTypeFromString(value));
-  },
+/**
+ * Registers a callback to be called before the physics step
+ * @category Hooks
+ */
 
-  position: () => {},
-  rotation: () => {},
-  quaternion: () => {},
-  scale: () => {}
+const useBeforePhysicsStep = callback => {
+  const {
+    beforeStepCallbacks
+  } = useRapier();
+  useEffect(() => {
+    beforeStepCallbacks.add(callback);
+    return () => {
+      beforeStepCallbacks.delete(callback);
+    };
+  }, []);
 };
-const mutableRigidBodyOptionKeys = Object.keys(mutableRigidBodyOptions);
-const setRigidBodyOptions = (rigidBody, options, states, updateTranslations = true) => {
-  if (!rigidBody) {
-    return;
-  }
+/**
+ * Registers a callback to be called after the physics step
+ * @category Hooks
+ */
 
-  const state = states.get(rigidBody.handle);
+const useAfterPhysicsStep = callback => {
+  const {
+    afterStepCallbacks
+  } = useRapier();
+  useEffect(() => {
+    afterStepCallbacks.add(callback);
+    return () => {
+      afterStepCallbacks.delete(callback);
+    };
+  }, []);
+}; // Internal hooks
 
-  if (state) {
-    if (updateTranslations) {
-      state.object.updateWorldMatrix(true, false);
+/**
+ * @internal
+ */
 
-      _matrix4.copy(state.object.matrixWorld).decompose(_position, _rotation, _scale);
+const useChildColliderProps = (ref, options, ignoreMeshColliders = true) => {
+  const [colliderProps, setColliderProps] = useState([]);
+  useEffect(() => {
+    const object = ref.current;
 
-      rigidBody.setTranslation(_position, false);
-      rigidBody.setRotation(_rotation, false);
+    if (object && options.colliders !== false) {
+      setColliderProps(createColliderPropsFromChildren({
+        object: ref.current,
+        options,
+        ignoreMeshColliders
+      }));
     }
-
-    mutableRigidBodyOptionKeys.forEach(key => {
-      if (key in options) {
-        mutableRigidBodyOptions[key](rigidBody, options[key]);
-      }
-    });
-  }
-};
-const useUpdateRigidBodyOptions = (rigidBodyRef, props, states, updateTranslations = true) => {
-  // TODO: Improve this, split each prop into its own effect
-  const mutablePropsAsFlatArray = useMemo(() => mutableRigidBodyOptionKeys.flatMap(key => {
-    return vectorToTuple(props[key]);
-  }), [props]);
-  useEffect(() => {
-    if (Array.isArray(rigidBodyRef.current)) {
-      for (const rigidBody of rigidBodyRef.current) {
-        setRigidBodyOptions(rigidBody, props, states, updateTranslations);
-      }
-    } else if (rigidBodyRef.current) {
-      setRigidBodyOptions(rigidBodyRef.current, props, states, updateTranslations);
-    }
-  }, mutablePropsAsFlatArray);
-};
-const useRigidBodyEvents = (rigidBodyRef, props, events) => {
-  const {
-    onWake,
-    onSleep,
-    onCollisionEnter,
-    onCollisionExit,
-    onIntersectionEnter,
-    onIntersectionExit
-  } = props;
-  const eventHandlers = {
-    onWake,
-    onSleep,
-    onCollisionEnter,
-    onCollisionExit,
-    onIntersectionEnter,
-    onIntersectionExit
-  };
-  useEffect(() => {
-    if (Array.isArray(rigidBodyRef.current)) {
-      for (const rigidBody of rigidBodyRef.current) {
-        events.set(rigidBody.handle, eventHandlers);
-      }
-    } else if (rigidBodyRef.current) {
-      events.set(rigidBodyRef.current.handle, eventHandlers);
-    }
-
-    return () => {
-      if (Array.isArray(rigidBodyRef.current)) {
-        for (const rigidBody of rigidBodyRef.current) {
-          events.delete(rigidBody.handle);
-        }
-      } else if (rigidBodyRef.current) {
-        events.delete(rigidBodyRef.current.handle);
-      }
-    };
-  }, [onWake, onSleep, onCollisionEnter, onCollisionExit, onIntersectionEnter, onIntersectionExit]);
-};
-
-const useRapier = () => {
-  return useContext(rapierContext);
-};
-const useBeforePhysicsStep = callback => {
-  const {
-    beforeStepCallbacks
-  } = useRapier();
-  useEffect(() => {
-    beforeStepCallbacks.add(callback);
-    return () => {
-      beforeStepCallbacks.delete(callback);
-    };
-  }, []);
-};
-const useAfterPhysicsStep = callback => {
-  const {
-    afterStepCallbacks
-  } = useRapier();
-  useEffect(() => {
-    afterStepCallbacks.add(callback);
-    return () => {
-      afterStepCallbacks.delete(callback);
-    };
-  }, []);
-}; // Internal hooks
-
-const useChildColliderProps = (ref, options, ignoreMeshColliders = true) => {
-  const [colliderProps, setColliderProps] = useState([]);
-  useEffect(() => {
-    const object = ref.current;
-
-    if (object && options.colliders !== false) {
-      setColliderProps(createColliderPropsFromChildren({
-        object: ref.current,
-        options,
-        ignoreMeshColliders
-      }));
-    }
-  }, [options.colliders]);
-  return colliderProps;
-};
-const useRigidBody = (options = {}) => {
-  const {
-    world,
-    rigidBodyStates,
-    physicsOptions,
-    rigidBodyEvents
-  } = useRapier();
-  const ref = useRef();
-  const mergedOptions = useMemo(() => {
-    return _objectSpread2(_objectSpread2(_objectSpread2({}, physicsOptions), options), {}, {
-      children: undefined
-    });
-  }, [physicsOptions, options]);
-  const childColliderProps = useChildColliderProps(ref, mergedOptions); // Create rigidbody
-
-  const rigidBodyRef = useRef();
-  const getRigidBodyRef = useRef(() => {
-    if (!rigidBodyRef.current) {
-      const desc = rigidBodyDescFromOptions(options);
-      const rigidBody = world.createRigidBody(desc);
-      rigidBodyRef.current = world.getRigidBody(rigidBody.handle);
-    }
-
-    return rigidBodyRef.current;
-  }); // Setup
-
-  useEffect(() => {
-    const rigidBody = getRigidBodyRef.current();
-    rigidBodyRef.current = rigidBody;
-
-    if (!ref.current) {
-      ref.current = new Object3D();
-    }
-
-    rigidBodyStates.set(rigidBody.handle, createRigidBodyState({
-      rigidBody,
-      object: ref.current
-    }));
-    return () => {
-      world.removeRigidBody(rigidBody);
-      rigidBodyStates.delete(rigidBody.handle);
-      rigidBodyRef.current = undefined;
-    };
-  }, []);
-  useUpdateRigidBodyOptions(rigidBodyRef, mergedOptions, rigidBodyStates);
-  useRigidBodyEvents(rigidBodyRef, mergedOptions, rigidBodyEvents);
-  const api = useMemo(() => createRigidBodyApi(getRigidBodyRef), []);
-  return [ref, api, childColliderProps];
-};
+  }, [options.colliders]);
+  return colliderProps;
+};
 
 const calcForceByType = {
   static: (s, m2, r, d, G) => s,
@@ -936,6 +629,10 @@ const importRapier = async () => {
   return r;
 };
 
+/**
+ * The main physics component used to create a physics world.
+ * @category Components
+ */
 const Physics = ({
   colliders: _colliders = "cuboid",
   gravity: _gravity = [0, -9.81, 0],
@@ -1095,7 +792,7 @@ const Physics = ({
         state.isSleeping = rigidBody.isSleeping();
       }
 
-      if (!rigidBody || rigidBody.isSleeping() || !state.setMatrix) {
+      if (!rigidBody || rigidBody.isSleeping() && !("isInstancedMesh" in state.object) || !state.setMatrix) {
         return;
       } // New states
 
@@ -1109,7 +806,7 @@ const Physics = ({
         _matrix4.compose(previousState.position, rapierQuaternionToQuaternion(previousState.rotation), state.scale).premultiply(state.invertedWorldMatrix).decompose(_position, _rotation, _scale); // Apply previous tick position
 
 
-        if (!(state.object instanceof InstancedMesh)) {
+        if (state.meshType == "mesh") {
           state.object.position.copy(_position);
           state.object.quaternion.copy(_rotation);
         }
@@ -1118,9 +815,8 @@ const Physics = ({
 
       _matrix4.compose(t, rapierQuaternionToQuaternion(r), state.scale).premultiply(state.invertedWorldMatrix).decompose(_position, _rotation, _scale);
 
-      if (state.object instanceof InstancedMesh) {
+      if (state.meshType == "instancedMesh") {
         state.setMatrix(_matrix4);
-        state.object.instanceMatrix.needsUpdate = true;
       } else {
         // Interpolate to new position
         state.object.position.lerp(_position, interpolationAlpha);
@@ -1304,8 +1000,87 @@ function _objectWithoutProperties(source, excluded) {
   return target;
 }
 
+/**
+ * Initiate an instance and return a safe getter
+ */
+
+const useImperativeInstance = (createFn, destroyFn) => {
+  const ref = useRef();
+  const refGetter = useMemo(() => () => {
+    if (!ref.current) {
+      ref.current = createFn();
+    }
+
+    return ref.current;
+  }, []);
+  useEffect(() => {
+    const instance = refGetter();
+    return () => {
+      destroyFn(instance);
+      ref.current = undefined;
+    };
+  }, []);
+  return refGetter;
+};
+
+/**
+ * Takes an object resembling a Vector3 and returs a Three.Vector3
+ * @category Math helpers
+ */
+
+const vec3 = ({
+  x,
+  y,
+  z
+} = {
+  x: 0,
+  y: 0,
+  z: 0
+}) => {
+  return new Vector3(x, y, z);
+};
+/**
+ * Takes an object resembling a Quaternion and returs a Three.Quaternion
+ * @category Math helpers
+ */
+
+const quat = ({
+  x,
+  y,
+  z,
+  w
+} = {
+  x: 0,
+  y: 0,
+  z: 0,
+  w: 1
+}) => {
+  return new Quaternion(x, y, z, w);
+};
+/**
+ * Takes an object resembling an Euler and returs a Three.Euler
+ * @category Math helpers
+ */
+
+const euler = ({
+  x,
+  y,
+  z
+} = {
+  x: 0,
+  y: 0,
+  z: 0
+}) => {
+  return new Euler(x, y, z);
+};
+
 // Colliders
-const AnyCollider = /*#__PURE__*/memo( /*#__PURE__*/React.forwardRef((props, forwardedRef) => {
+
+/**
+ * A collider is a shape that can be attached to a rigid body to define its physical properties.
+ * @internal
+ */
+const AnyCollider = /*#__PURE__*/memo( /*#__PURE__*/forwardRef((props, forwardedRef) => {
   const {
     children,
     position,
@@ -1321,52 +1096,21 @@ const AnyCollider = /*#__PURE__*/memo( /*#__PURE__*/React.forwardRef((props, for
   } = useRapier();
   const rigidBodyContext = useRigidBodyContext();
   const ref = useRef(null);
-  const collidersRef = useMemo(() => {
-    if (forwardedRef !== null) {
-      return forwardedRef;
-    }
-
-    const result = /*#__PURE__*/React.createRef();
-    result.current = [];
-    return result;
-  }, []);
-  useEffect(() => {
-    const object = ref.current;
-    const worldScale = object.getWorldScale(new Vector3());
-    const colliders = []; // If this is an InstancedRigidBody api
-
-    if (rigidBodyContext && "at" in rigidBodyContext.api) {
-      rigidBodyContext.api.forEach((body, index) => {
-        var _rigidBodyContext$opt, _rigidBodyContext$opt2;
-
-        let instanceScale = worldScale;
-
-        if ("scales" in rigidBodyContext.options && rigidBodyContext !== null && rigidBodyContext !== void 0 && (_rigidBodyContext$opt = rigidBodyContext.options) !== null && _rigidBodyContext$opt !== void 0 && (_rigidBodyContext$opt2 = _rigidBodyContext$opt.scales) !== null && _rigidBodyContext$opt2 !== void 0 && _rigidBodyContext$opt2[index]) {
-          instanceScale = instanceScale.clone().multiply(vectorArrayToVector3(rigidBodyContext.options.scales[index]));
-        }
-
-        const collider = createColliderFromOptions(props, world, instanceScale, body.raw());
-        colliderStates.set(collider.handle, createColliderState(collider, object, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.ref.current));
-        colliders.push(collider);
-      });
-    } else {
-      const collider = createColliderFromOptions(props, world, worldScale, rigidBodyContext && (rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.api).raw());
-      colliderStates.set(collider.handle, createColliderState(collider, object, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.ref.current));
-      colliders.push(collider);
-    }
-
-    collidersRef.current = colliders;
-    return () => {
-      colliders.forEach(collider => {
-        world.removeCollider(collider);
-      });
-    };
-  }, []);
+  const getInstance = useImperativeInstance(() => {
+    const worldScale = ref.current.getWorldScale(vec3());
+    const collider = createColliderFromOptions(props, world, worldScale, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.getRigidBody);
+    colliderStates.set(collider.handle, createColliderState(collider, ref.current, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.ref.current));
+    return collider;
+  }, collider => {
+    colliderStates.delete(collider.handle);
+    world.removeCollider(collider);
+  });
+  useImperativeHandle(forwardedRef, () => getInstance());
   const mergedProps = useMemo(() => {
     return _objectSpread2(_objectSpread2({}, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.options), props);
   }, [props, rigidBodyContext === null || rigidBodyContext === void 0 ? void 0 : rigidBodyContext.options]);
-  useUpdateColliderOptions(collidersRef, mergedProps, colliderStates);
-  useColliderEvents(collidersRef, mergedProps, colliderEvents);
+  useUpdateColliderOptions(getInstance, mergedProps, colliderStates);
+  useColliderEvents(getInstance, mergedProps, colliderEvents);
   return /*#__PURE__*/React.createElement("object3D", {
     position: position,
     rotation: rotation,
@@ -1376,54 +1120,99 @@ const AnyCollider = /*#__PURE__*/memo( /*#__PURE__*/React.forwardRef((props, for
     name: name
   }, children);
 }));
+
+/**
+ * A cuboid collider shape
+ * @category Colliders
+ */
 const CuboidCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "cuboid",
     ref: ref
   }));
 });
+/**
+ * A round cuboid collider shape
+ * @category Colliders
+ */
+
 const RoundCuboidCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "roundCuboid",
     ref: ref
   }));
 });
+/**
+ * A ball collider shape
+ * @category Colliders
+ */
+
 const BallCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "ball",
     ref: ref
   }));
 });
+/**
+ * A capsule collider shape
+ * @category Colliders
+ */
+
 const CapsuleCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "capsule",
     ref: ref
   }));
 });
+/**
+ * A heightfield collider shape
+ * @category Colliders
+ */
+
 const HeightfieldCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "heightfield",
     ref: ref
   }));
 });
+/**
+ * A trimesh collider shape
+ * @category Colliders
+ */
+
 const TrimeshCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "trimesh",
     ref: ref
   }));
 });
+/**
+ * A cone collider shape
+ * @category Colliders
+ */
+
 const ConeCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "cone",
     ref: ref
   }));
 });
+/**
+ * A cylinder collider shape
+ * @category Colliders
+ */
+
 const CylinderCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "cylinder",
     ref: ref
   }));
 });
+/**
+ * A convex hull collider shape
+ * @category Colliders
+ */
+
 const ConvexHullCollider = /*#__PURE__*/React.forwardRef((props, ref) => {
   return /*#__PURE__*/React.createElement(AnyCollider, _extends({}, props, {
     shape: "convexHull",
@@ -1440,31 +1229,212 @@ ConeCollider.displayName = "ConeCollider";
 CylinderCollider.displayName = "CylinderCollider";
 ConvexHullCollider.displayName = "ConvexHullCollider";
 
-const _excluded$1 = ["children", "type", "position", "rotation", "scale", "quaternion"];
+const rigidBodyDescFromOptions = options => {
+  var _options$canSleep;
+
+  const type = rigidBodyTypeFromString((options === null || options === void 0 ? void 0 : options.type) || "dynamic");
+  const desc = new RigidBodyDesc(type); // Apply immutable options
+
+  desc.canSleep = (_options$canSleep = options === null || options === void 0 ? void 0 : options.canSleep) !== null && _options$canSleep !== void 0 ? _options$canSleep : true;
+  return desc;
+};
+const createRigidBodyState = ({
+  rigidBody,
+  object,
+  setMatrix,
+  getMatrix,
+  worldScale,
+  meshType: _meshType = "mesh"
+}) => {
+  object.updateWorldMatrix(true, false);
+  const invertedWorldMatrix = object.parent.matrixWorld.clone().invert();
+  return {
+    object,
+    rigidBody,
+    invertedWorldMatrix,
+    setMatrix: setMatrix ? setMatrix : matrix => {
+      object.matrix.copy(matrix);
+    },
+    getMatrix: getMatrix ? getMatrix : matrix => matrix.copy(object.matrix),
+    scale: worldScale || object.getWorldScale(_scale).clone(),
+    isSleeping: false,
+    meshType: _meshType
+  };
+};
+const mutableRigidBodyOptions = {
+  gravityScale: (rb, value) => {
+    rb.setGravityScale(value, true);
+  },
+  linearDamping: (rb, value) => {
+    rb.setLinearDamping(value);
+  },
+  angularDamping: (rb, value) => {
+    rb.setAngularDamping(value);
+  },
+  enabledRotations: (rb, [x, y, z]) => {
+    rb.setEnabledRotations(x, y, z, true);
+  },
+  enabledTranslations: (rb, [x, y, z]) => {
+    rb.setEnabledTranslations(x, y, z, true);
+  },
+  lockRotations: (rb, value) => {
+    rb.lockRotations(value, true);
+  },
+  lockTranslations: (rb, value) => {
+    rb.lockTranslations(value, true);
+  },
+  angularVelocity: (rb, [x, y, z]) => {
+    rb.setAngvel({
+      x,
+      y,
+      z
+    }, true);
+  },
+  linearVelocity: (rb, [x, y, z]) => {
+    rb.setLinvel({
+      x,
+      y,
+      z
+    }, true);
+  },
+  ccd: (rb, value) => {
+    rb.enableCcd(value);
+  },
+  userData: (rb, value) => {
+    rb.userData = value;
+  },
+
+  type(rb, value) {
+    rb.setBodyType(rigidBodyTypeFromString(value), true);
+  },
+
+  position: () => {},
+  rotation: () => {},
+  quaternion: () => {},
+  scale: () => {}
+};
+const mutableRigidBodyOptionKeys = Object.keys(mutableRigidBodyOptions);
+const setRigidBodyOptions = (rigidBody, options, states, updateTranslations = true) => {
+  if (!rigidBody) {
+    return;
+  }
+
+  const state = states.get(rigidBody.handle);
+
+  if (state) {
+    if (updateTranslations) {
+      state.object.updateWorldMatrix(true, false);
+
+      _matrix4.copy(state.object.matrixWorld).decompose(_position, _rotation, _scale);
+
+      rigidBody.setTranslation(_position, false);
+      rigidBody.setRotation(_rotation, false);
+    }
+
+    mutableRigidBodyOptionKeys.forEach(key => {
+      if (key in options) {
+        mutableRigidBodyOptions[key](rigidBody, options[key]);
+      }
+    });
+  }
+};
+const useUpdateRigidBodyOptions = (getRigidBody, props, states, updateTranslations = true) => {
+  // TODO: Improve this, split each prop into its own effect
+  const mutablePropsAsFlatArray = useMemo(() => mutableRigidBodyOptionKeys.flatMap(key => {
+    return vectorToTuple(props[key]);
+  }), [props]);
+  useEffect(() => {
+    const rigidBody = getRigidBody();
+    setRigidBodyOptions(rigidBody, props, states, updateTranslations);
+  }, mutablePropsAsFlatArray);
+};
+const useRigidBodyEvents = (getRigidBody, props, events) => {
+  const {
+    onWake,
+    onSleep,
+    onCollisionEnter,
+    onCollisionExit,
+    onIntersectionEnter,
+    onIntersectionExit
+  } = props;
+  const eventHandlers = {
+    onWake,
+    onSleep,
+    onCollisionEnter,
+    onCollisionExit,
+    onIntersectionEnter,
+    onIntersectionExit
+  };
+  useEffect(() => {
+    const rigidBody = getRigidBody();
+    events.set(rigidBody.handle, eventHandlers);
+    return () => {
+      events.delete(rigidBody.handle);
+    };
+  }, [onWake, onSleep, onCollisionEnter, onCollisionExit, onIntersectionEnter, onIntersectionExit]);
+};
+
+const _excluded$1 = ["children", "type", "position", "rotation", "scale", "quaternion", "transformState"];
 const RigidBodyContext = /*#__PURE__*/createContext(undefined);
 const useRigidBodyContext = () => useContext(RigidBodyContext);
-const RigidBody = /*#__PURE__*/memo( /*#__PURE__*/forwardRef((props, ref) => {
+
+/**
+ * A rigid body is a physical object that can be simulated by the physics engine.
+ * @category Components
+ */
+const RigidBody = /*#__PURE__*/memo( /*#__PURE__*/forwardRef((props, forwardedRef) => {
   const {
     children,
     type,
     position,
     rotation,
     scale,
-    quaternion
+    quaternion,
+    transformState
   } = props,
         objectProps = _objectWithoutProperties(props, _excluded$1);
 
-  const [object, api, childColliderProps] = useRigidBody(props);
-  useImperativeHandle(ref, () => api);
-  const contextValue = useMemo(() => ({
-    ref: object,
-    api,
-    options: props
-  }), [object, api, props]);
+  const ref = useRef(null);
+  const {
+    world,
+    rigidBodyStates,
+    physicsOptions,
+    rigidBodyEvents
+  } = useRapier();
+  const mergedOptions = useMemo(() => {
+    return _objectSpread2(_objectSpread2(_objectSpread2({}, physicsOptions), props), {}, {
+      children: undefined
+    });
+  }, [physicsOptions, props]);
+  const childColliderProps = useChildColliderProps(ref, mergedOptions); // Create rigidbody
+
+  const getInstance = useImperativeInstance(() => {
+    const desc = rigidBodyDescFromOptions(mergedOptions);
+    const rigidBody = world.createRigidBody(desc);
+    const state = createRigidBodyState({
+      rigidBody,
+      object: ref.current
+    });
+    rigidBodyStates.set(rigidBody.handle, props.transformState ? props.transformState(state) : state);
+    return rigidBody;
+  }, rigidBody => {
+    world.removeRigidBody(rigidBody);
+    rigidBodyStates.delete(rigidBody.handle);
+  });
+  useUpdateRigidBodyOptions(getInstance, mergedOptions, rigidBodyStates);
+  useRigidBodyEvents(getInstance, mergedOptions, rigidBodyEvents);
+  useImperativeHandle(forwardedRef, () => getInstance());
+  const contextValue = useMemo(() => {
+    return {
+      ref,
+      getRigidBody: getInstance,
+      options: mergedOptions
+    };
+  }, [mergedOptions]);
   return /*#__PURE__*/React.createElement(RigidBodyContext.Provider, {
     value: contextValue
   }, /*#__PURE__*/React.createElement("object3D", _extends({
-    ref: object
+    ref: ref
   }, objectProps, {
     position: position,
     rotation: rotation,
@@ -1476,14 +1446,17 @@ const RigidBody = /*#__PURE__*/memo( /*#__PURE__*/forwardRef((props, ref) => {
 }));
 RigidBody.displayName = "RigidBody";
 
+/**
+ * A mesh collider is a collider that is automatically generated from the geometry of the children.
+ * @category Colliders
+ */
 const MeshCollider = /*#__PURE__*/memo(props => {
   const {
     children,
     type
   } = props;
   const {
-    physicsOptions,
-    world
+    physicsOptions
   } = useRapier();
   const object = useRef(null);
   const {
@@ -1597,155 +1570,119 @@ const Debug = /*#__PURE__*/memo(() => {
   }, attractor))));
 });
 
-const _excluded = ["positions", "rotations", "children"];
-const InstancedRigidBodies = /*#__PURE__*/forwardRef((props, ref) => {
-  const {
-    world,
-    rigidBodyStates,
-    physicsOptions,
-    rigidBodyEvents
-  } = useRapier();
+const _excluded = ["children", "instances", "colliderNodes", "position", "rotation", "quaternion", "scale"];
+const InstancedRigidBodies = /*#__PURE__*/memo( /*#__PURE__*/forwardRef((props, ref) => {
   const object = useRef(null);
+  const instancedWrapper = useRef(null);
 
   const {
-    positions,
-    rotations,
-    children
+    // instanced props
+    children,
+    instances,
+    colliderNodes = [],
+    // wrapper object props
+    position,
+    rotation,
+    quaternion,
+    scale
   } = props,
-        options = _objectWithoutProperties(props, _excluded);
+        rigidBodyProps = _objectWithoutProperties(props, _excluded);
 
-  const instancesRef = useRef([]);
-  const rigidBodyRefs = useRef([]);
-  const instancesRefGetter = useRef(() => {
-    if (!instancesRef.current) {
-      instancesRef.current = [];
-    }
+  const rigidBodyApis = useRef([]);
+  useImperativeHandle(ref, () => rigidBodyApis.current, [instances]);
+  const childColliderProps = useChildColliderProps(object, _objectSpread2(_objectSpread2({}, props), {}, {
+    children: undefined
+  }));
 
-    return instancesRef.current;
-  });
-  const mergedOptions = useMemo(() => {
-    return _objectSpread2(_objectSpread2({}, physicsOptions), options);
-  }, [physicsOptions, options]);
-  const childColliderProps = useChildColliderProps(object, mergedOptions);
-  useLayoutEffect(() => {
-    object.current.updateWorldMatrix(true, false);
-    const instances = instancesRefGetter.current();
-    const invertedWorld = object.current.matrixWorld.clone().invert();
-    object.current.traverseVisible(mesh => {
-      if (mesh instanceof InstancedMesh) {
-        mesh.instanceMatrix.setUsage(DynamicDrawUsage);
-        const worldScale = mesh.getWorldScale(_scale);
-
-        for (let index = 0; index < mesh.count; index++) {
-          var _options$scales;
-
-          const desc = rigidBodyDescFromOptions(props);
-          const rigidBody = world.createRigidBody(desc);
-          rigidBodyRefs.current.push(rigidBody);
-          const scale = ((_options$scales = options.scales) === null || _options$scales === void 0 ? void 0 : _options$scales[index]) || [1, 1, 1];
-          const instanceScale = worldScale.clone().multiply(vectorArrayToVector3(scale));
-          rigidBodyStates.set(rigidBody.handle, createRigidBodyState({
-            rigidBody,
-            object: mesh,
-            setMatrix: matrix => mesh.setMatrixAt(index, matrix),
-            getMatrix: matrix => {
-              mesh.getMatrixAt(index, matrix);
-              return matrix;
-            },
-            worldScale: instanceScale
-          }));
-          const [x, y, z] = (positions === null || positions === void 0 ? void 0 : positions[index]) || [0, 0, 0];
-          const [rx, ry, rz] = (rotations === null || rotations === void 0 ? void 0 : rotations[index]) || [0, 0, 0];
+  const getInstancedMesh = () => {
+    const firstChild = instancedWrapper.current.children[0];
 
-          _object3d.position.set(x, y, z);
+    if (firstChild && "isInstancedMesh" in firstChild) {
+      return firstChild;
+    }
 
-          _object3d.rotation.set(rx, ry, rz);
+    return undefined;
+  };
 
-          _object3d.applyMatrix4(invertedWorld);
+  useEffect(() => {
+    const instancedMesh = getInstancedMesh();
 
-          mesh.setMatrixAt(index, _object3d.matrix);
-          rigidBody.setTranslation(_object3d.position, false);
-          rigidBody.setRotation(_object3d.quaternion, false);
-          const api = createRigidBodyApi({
-            current() {
-              return rigidBody;
-            }
+    if (instancedMesh) {
+      instancedMesh.instanceMatrix.setUsage(DynamicDrawUsage);
+    } else {
+      console.warn("InstancedRigidBodies expects exactly one child, which must be an InstancedMesh");
+    }
+  }, []); // Update the RigidBodyStates whenever the instances change
 
-          });
-          instances.push({
-            rigidBody,
-            api
-          });
-        }
-      }
-    });
-    return () => {
-      instances.forEach(rb => {
-        world.removeRigidBody(rb.rigidBody);
-        rigidBodyStates.delete(rb.rigidBody.handle);
+  const applyInstancedState = (state, index) => {
+    const instancedMesh = getInstancedMesh();
+
+    if (instancedMesh) {
+      return _objectSpread2(_objectSpread2({}, state), {}, {
+        getMatrix: matrix => {
+          instancedMesh.getMatrixAt(index, matrix);
+          return matrix;
+        },
+        setMatrix: matrix => {
+          instancedMesh.setMatrixAt(index, matrix);
+          instancedMesh.instanceMatrix.needsUpdate = true;
+        },
+        meshType: "instancedMesh"
       });
-      rigidBodyRefs.current = [];
-      instancesRef.current = [];
-    };
-  }, []);
-  const api = useMemo(() => createInstancedRigidBodiesApi(instancesRefGetter), []);
-  useImperativeHandle(ref, () => api);
-  useUpdateRigidBodyOptions(rigidBodyRefs, mergedOptions, rigidBodyStates, false);
-  useRigidBodyEvents(rigidBodyRefs, mergedOptions, rigidBodyEvents);
-  const contextValue = useMemo(() => {
-    return {
-      ref: object,
-      api,
-      options: mergedOptions
-    };
-  }, [api, mergedOptions]);
-  return /*#__PURE__*/React.createElement(RigidBodyContext.Provider, {
-    value: contextValue
-  }, /*#__PURE__*/React.createElement("object3D", {
+    }
+
+    return state;
+  };
+
+  return /*#__PURE__*/React.createElement("object3D", _extends({
     ref: object
-  }, props.children, childColliderProps.map((colliderProps, index) => /*#__PURE__*/React.createElement(AnyCollider, _extends({
+  }, rigidBodyProps, {
+    position: position,
+    rotation: rotation,
+    quaternion: quaternion,
+    scale: scale
+  }), /*#__PURE__*/React.createElement("object3D", {
+    ref: instancedWrapper
+  }, children), instances === null || instances === void 0 ? void 0 : instances.map((instance, index) => /*#__PURE__*/React.createElement(RigidBody, _extends({}, rigidBodyProps, instance, {
+    ref: body => rigidBodyApis.current[index] = body,
+    transformState: state => applyInstancedState(state, index)
+  }), /*#__PURE__*/React.createElement(React.Fragment, null, colliderNodes.map((node, index) => /*#__PURE__*/React.createElement(Fragment, {
     key: index
-  }, colliderProps)))));
-});
+  }, node)), childColliderProps.map((colliderProps, colliderIndex) => /*#__PURE__*/React.createElement(AnyCollider, _extends({
+    key: colliderIndex
+  }, colliderProps)))))));
+}));
 InstancedRigidBodies.displayName = "InstancedRigidBodies";
 
+/**
+ * @internal
+ */
+
 const useImpulseJoint = (body1, body2, params) => {
   const {
     world
   } = useRapier();
   const jointRef = useRef();
-  const getJointRef = useRef(() => {
-    if (!jointRef.current) {
-      let rb1;
-      let rb2;
-
-      if ("current" in body1 && body1.current && "current" in body2 && body2.current) {
-        rb1 = world.getRigidBody(body1.current.handle);
-        rb2 = world.getRigidBody(body2.current.handle);
-        const newJoint = world.createImpulseJoint(params, rb1, rb2);
-        jointRef.current = newJoint;
-      }
+  useImperativeInstance(() => {
+    if (body1.current && body2.current) {
+      const newJoint = world.createImpulseJoint(params, body1.current, body2.current);
+      jointRef.current = newJoint;
+      return newJoint;
+    }
+  }, joint => {
+    if (joint) {
+      jointRef.current = undefined;
+      world.removeImpulseJoint(joint);
     }
-
-    return jointRef.current;
   });
-  useEffect(() => {
-    const joint = getJointRef.current();
-    return () => {
-      if (joint) {
-        world.removeImpulseJoint(joint);
-        jointRef.current = undefined;
-      }
-    };
-  }, []);
-  const api = useMemo(() => createJointApi(getJointRef), []);
-  return api;
+  return jointRef;
 };
 /**
- *
  * 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.
+ *
+ * @category Hooks - Joints
  */
 
 const useFixedJoint = (body1, body2, [body1Anchor, body1LocalFrame, body2Anchor, body2LocalFrame]) => {
@@ -1759,6 +1696,8 @@ const useFixedJoint = (body1, body2, [body1Anchor, body1LocalFrame, body2Anchor,
  * translational motion at this points). This is typically used to simulate ragdolls arms, pendulums, etc.
  * They are characterized by one local anchor on each rigid-body. Each anchor represents the location of the
  * points that need to coincide on the local-space of each rigid-body.
+ *
+ * @category Hooks - Joints
  */
 
 const useSphericalJoint = (body1, body2, [body1Anchor, body2Anchor]) => {
@@ -1771,6 +1710,8 @@ const useSphericalJoint = (body1, body2, [body1Anchor, body2Anchor]) => {
  * 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.
  * They are characterized by one local anchor as well as one local axis on each rigid-body.
+ *
+ * @category Hooks - Joints
  */
 
 const useRevoluteJoint = (body1, body2, [body1Anchor, body2Anchor, axis, limits]) => {
@@ -1790,6 +1731,8 @@ const useRevoluteJoint = (body1, body2, [body1Anchor, body2Anchor, axis, limits]
  * The prismatic joint prevents any relative movement between two rigid-bodies, except for relative translations along one axis.
  * It is characterized by one local anchor as well as one local axis on each rigid-body. In 3D, an optional
  * local tangent axis can be specified for each rigid-body.
+ *
+ * @category Hooks - Joints
  */
 
 const usePrismaticJoint = (body1, body2, [body1Anchor, body2Anchor, axis, limits]) => {
@@ -1842,4 +1785,4 @@ const interactionGroups = (memberships, filters) => (bitmask(memberships) << 16)
 
 const bitmask = groups => [groups].flat().reduce((acc, layer) => acc | 1 << layer, 0);
 
-export { AnyCollider, Attractor, BallCollider, CapsuleCollider, ConeCollider, ConvexHullCollider, CuboidCollider, CylinderCollider, Debug, HeightfieldCollider, InstancedRigidBodies, MeshCollider, Physics, RigidBody, RoundCuboidCollider, TrimeshCollider, interactionGroups, useAfterPhysicsStep, useBeforePhysicsStep, useFixedJoint, useImpulseJoint, usePrismaticJoint, useRapier, useRevoluteJoint, useSphericalJoint };
+export { AnyCollider, Attractor, BallCollider, CapsuleCollider, ConeCollider, ConvexHullCollider, CuboidCollider, CylinderCollider, Debug, HeightfieldCollider, InstancedRigidBodies, MeshCollider, Physics, RigidBody, RoundCuboidCollider, TrimeshCollider, euler, interactionGroups, quat, useAfterPhysicsStep, useBeforePhysicsStep, useFixedJoint, useImpulseJoint, usePrismaticJoint, useRapier, useRevoluteJoint, useSphericalJoint, vec3 };