@react-three/rapier 0.11.2 → 0.11.3

package/dist/declarations/src/types.d.ts

@@ -72,6 +72,7 @@ export declare type UseBodyOptions = Omit<UseRigidBodyOptions, "shape">;
 export declare type RigidBodyTypeString = "fixed" | "dynamic" | "kinematicPosition" | "kinematicVelocity";
 export declare type ColliderShape = "cuboid" | "trimesh" | "ball" | "capsule" | "convexHull" | "heightfield" | "polyline" | "roundCuboid" | "cylinder" | "roundCylinder" | "cone" | "roundCone" | "convexMesh" | "roundConvexHull" | "roundConvexMesh";
 export declare type Vector3Array = [x: number, y: number, z: number];
+export declare type Vector4Array = [x: number, y: number, z: number, w: number];
 export declare type Boolean3Array = [x: boolean, y: boolean, z: boolean];
 export interface UseColliderOptions<ColliderArgs extends Array<unknown>> {
     /**
@@ -324,9 +325,9 @@ export declare type SphericalJointParams = [
 ];
 export declare type FixedJointParams = [
     body1Anchor: Vector3Array,
-    body1LocalFrame: Vector3Array,
+    body1LocalFrame: Vector4Array,
     body2Anchor: Vector3Array,
-    body2LocalFrame: Vector3Array
+    body2LocalFrame: Vector4Array
 ];
 export declare type PrismaticJointParams = [
     body1Anchor: Vector3Array,

package/dist/declarations/src/utils.d.ts

@@ -2,6 +2,7 @@ import { Quaternion as RapierQuaternion, Vector3 as RapierVector3 } from "@dimfo
 import { Euler, Quaternion, Vector3 } from "three";
 import { RigidBodyTypeString, Vector3Array } from "./types";
 export declare const vectorArrayToVector3: (arr: Vector3Array) => Vector3;
+export declare const tupleToObject: <T extends readonly any[], K extends readonly string[]>(tuple: T, keys: K) => { [Key in K[number]]: T[number]; };
 export declare const vector3ToQuaternion: (v: Vector3) => Quaternion;
 export declare const rapierVector3ToVector3: ({ x, y, z }: RapierVector3) => Vector3;
 export declare const rapierQuaternionToQuaternion: ({ x, y, z, w }: RapierQuaternion) => Quaternion;

package/dist/react-three-rapier.cjs.dev.js

@@ -85,6 +85,12 @@ const vectorArrayToVector3 = arr => {
   const [x, y, z] = arr;
   return new three.Vector3(x, y, z);
 };
+const tupleToObject = (tuple, keys) => {
+  return keys.reduce((obj, key, i) => {
+    obj[key] = tuple[i];
+    return obj;
+  }, {});
+};
 const rapierVector3ToVector3 = ({
   x,
   y,
@@ -860,11 +866,7 @@ const useFixedJoint = (body1, body2, [body1Anchor, body1LocalFrame, body2Anchor,
   const {
     rapier
   } = useRapier();
-  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body1LocalFrame)), {}, {
-    w: 1
-  }), vectorArrayToVector3(body2Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body2LocalFrame)), {}, {
-    w: 1
-  })));
+  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), tupleToObject(body1LocalFrame, ["x", "y", "z", "w"]), vectorArrayToVector3(body2Anchor), tupleToObject(body2LocalFrame, ["x", "y", "z", "w"])));
 };
 /**
  * The spherical joint ensures that two points on the local-spaces of two rigid-bodies always coincide (it prevents any relative

package/dist/react-three-rapier.cjs.prod.js

@@ -85,6 +85,12 @@ const vectorArrayToVector3 = arr => {
   const [x, y, z] = arr;
   return new three.Vector3(x, y, z);
 };
+const tupleToObject = (tuple, keys) => {
+  return keys.reduce((obj, key, i) => {
+    obj[key] = tuple[i];
+    return obj;
+  }, {});
+};
 const rapierVector3ToVector3 = ({
   x,
   y,
@@ -860,11 +866,7 @@ const useFixedJoint = (body1, body2, [body1Anchor, body1LocalFrame, body2Anchor,
   const {
     rapier
   } = useRapier();
-  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body1LocalFrame)), {}, {
-    w: 1
-  }), vectorArrayToVector3(body2Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body2LocalFrame)), {}, {
-    w: 1
-  })));
+  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), tupleToObject(body1LocalFrame, ["x", "y", "z", "w"]), vectorArrayToVector3(body2Anchor), tupleToObject(body2LocalFrame, ["x", "y", "z", "w"])));
 };
 /**
  * The spherical joint ensures that two points on the local-spaces of two rigid-bodies always coincide (it prevents any relative

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

@@ -60,6 +60,12 @@ const vectorArrayToVector3 = arr => {
   const [x, y, z] = arr;
   return new Vector3(x, y, z);
 };
+const tupleToObject = (tuple, keys) => {
+  return keys.reduce((obj, key, i) => {
+    obj[key] = tuple[i];
+    return obj;
+  }, {});
+};
 const rapierVector3ToVector3 = ({
   x,
   y,
@@ -835,11 +841,7 @@ const useFixedJoint = (body1, body2, [body1Anchor, body1LocalFrame, body2Anchor,
   const {
     rapier
   } = useRapier();
-  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body1LocalFrame)), {}, {
-    w: 1
-  }), vectorArrayToVector3(body2Anchor), _objectSpread2(_objectSpread2({}, vectorArrayToVector3(body2LocalFrame)), {}, {
-    w: 1
-  })));
+  return useImpulseJoint(body1, body2, rapier.JointData.fixed(vectorArrayToVector3(body1Anchor), tupleToObject(body1LocalFrame, ["x", "y", "z", "w"]), vectorArrayToVector3(body2Anchor), tupleToObject(body2LocalFrame, ["x", "y", "z", "w"])));
 };
 /**
  * The spherical joint ensures that two points on the local-spaces of two rigid-bodies always coincide (it prevents any relative

package/package.json

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

package/readme.md

@@ -7,9 +7,17 @@
   <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">⚠️ Under heavy 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>.
+</p>
+
+---
+
+`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.
 
-For contributions, please read the [contributing guide](https://github.com/pmndrs/react-three-rapier/blob/main/packages/react-three-rapier/CONTRIBUTING.md).
 
 ## Basic Usage
 
@@ -27,7 +35,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>
@@ -58,6 +66,11 @@ const App = () => {
 - [Configuring Time Step Size](#configuring-time-step-size)
 - [Manual stepping](#manual-stepping)
 - [Joints](#joints)
+  - [Fixed Joint](#fixed-joint)
+  - [Spherical Joint](#spherical-joint)
+  - [Revolute Joint](#revolute-joint)
+  - [Prismatic Joint](#prismatic-joint)
+  - [Joint APIs](#joint-apis)
   - [Joints Example](#joints-example)
 
 ---
@@ -200,11 +213,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 });
     });
   }, []);
@@ -379,7 +396,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>
 ```
@@ -496,8 +513,143 @@ step(1 / 60);
 ```
 
 ## 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.
+
+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.
+
+```tsx
+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
+    ]);
+
+  return (
+    <group>
+      <RigidBody ref={bodyA}>
+        <mesh />
+      </RigidBody>
+      <RigidBody ref={bodyB}>
+        <mesh />
+      </RigidBody>
+    </group>
+  );
+}
+```
+
+### 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).
+
+```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.
+
+```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.
+
+```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.
+
+```tsx
+const JointedThing = () => { 
+  const joint = useSphericalJoint(...)
+
+  useEffect(() => {
+    joint.configureMotorVelocity(1, 0)
+
+    // Disable contacts between the two joint bodies
+    joint.raw().setContactsEnabled(false)
+  }, [])
+
+  return ...
+}
+```
 
-- WIP
 
 ### 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>