@react-three/rapier 1.1.2 → 1.2.1

package/dist/declarations/src/components/Physics.d.ts

@@ -77,6 +77,39 @@ export interface RapierContext {
      * The Rapier physics world
      */
     world: World;
+    /**
+     * Can be used to overwrite the current World. Useful when working with snapshots.
+     *
+     * @example
+     * ```tsx
+     * import { useRapier } from '@react-three/rapier';
+     *
+     * const SnapshottingComponent = () => {
+     *   const { world, setWorld, rapier } = useRapier();
+     *   const worldSnapshot = useRef<Uint8Array>();
+     *
+     *   // Store the snapshot
+     *   const takeSnapshot = () => {
+     *     const snapshot = world.takeSnapshot()
+     *     worldSnapshot.current = snapshot
+     *   }
+     *
+     *   // Create a new World from the snapshot, and replace the current one
+     *   const restoreSnapshot = () => {
+     *     setWorld(rapier.World.restoreSnapshot(worldSnapshot.current))
+     *   }
+     *
+     *   return <>
+     *     <Rigidbody>...</RigidBody>
+     *     <Rigidbody>...</RigidBody>
+     *     <Rigidbody>...</RigidBody>
+     *     <Rigidbody>...</RigidBody>
+     *     <Rigidbody>...</RigidBody>
+     *   </>
+     * }
+     * ```
+     */
+    setWorld: (world: World) => void;
     /**
      * If the physics simulation is paused
      */

package/dist/declarations/src/utils/singleton-proxy.d.ts

@@ -7,4 +7,5 @@
 export declare const createSingletonProxy: <SingletonClass extends object, CreationFn extends () => SingletonClass = () => SingletonClass>(createInstance: CreationFn) => {
     proxy: SingletonClass;
     reset: () => void;
+    set: (newInstance: SingletonClass) => void;
 };

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

@@ -572,7 +572,7 @@ const useMutableCallback = fn => {
 
 const useRapier = () => {
   const rapier = React.useContext(rapierContext);
-  if (!rapier) throw new Error('react-three-rapier: useRapier must be used within <Physics />!');
+  if (!rapier) throw new Error("react-three-rapier: useRapier must be used within <Physics />!");
   return rapier;
 };
 /**
@@ -682,6 +682,10 @@ const createSingletonProxy = createInstance => {
   const reset = () => {
     instance = undefined;
   };
+
+  const set = newInstance => {
+    instance = newInstance;
+  };
   /**
    * Return the proxy and a reset function
    */
@@ -689,7 +693,8 @@ const createSingletonProxy = createInstance => {
 
   return {
     proxy,
-    reset
+    reset,
+    set
   };
 };
 
@@ -764,7 +769,8 @@ const Physics = props => {
 
   const {
     proxy: worldProxy,
-    reset: resetWorldProxy
+    reset: resetWorldProxy,
+    set: setWorldProxy
   } = useConst(() => createSingletonProxy(() => new rapier.World(vectorArrayToVector3(gravity))));
   React.useEffect(() => {
     return () => {
@@ -1020,6 +1026,9 @@ const Physics = props => {
   const context = React.useMemo(() => ({
     rapier,
     world: worldProxy,
+    setWorld: world => {
+      setWorldProxy(world);
+    },
     physicsOptions: {
       colliders,
       gravity

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

@@ -572,7 +572,7 @@ const useMutableCallback = fn => {
 
 const useRapier = () => {
   const rapier = React.useContext(rapierContext);
-  if (!rapier) throw new Error('react-three-rapier: useRapier must be used within <Physics />!');
+  if (!rapier) throw new Error("react-three-rapier: useRapier must be used within <Physics />!");
   return rapier;
 };
 /**
@@ -682,6 +682,10 @@ const createSingletonProxy = createInstance => {
   const reset = () => {
     instance = undefined;
   };
+
+  const set = newInstance => {
+    instance = newInstance;
+  };
   /**
    * Return the proxy and a reset function
    */
@@ -689,7 +693,8 @@ const createSingletonProxy = createInstance => {
 
   return {
     proxy,
-    reset
+    reset,
+    set
   };
 };
 
@@ -764,7 +769,8 @@ const Physics = props => {
 
   const {
     proxy: worldProxy,
-    reset: resetWorldProxy
+    reset: resetWorldProxy,
+    set: setWorldProxy
   } = useConst(() => createSingletonProxy(() => new rapier.World(vectorArrayToVector3(gravity))));
   React.useEffect(() => {
     return () => {
@@ -1020,6 +1026,9 @@ const Physics = props => {
   const context = React.useMemo(() => ({
     rapier,
     world: worldProxy,
+    setWorld: world => {
+      setWorldProxy(world);
+    },
     physicsOptions: {
       colliders,
       gravity

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

@@ -547,7 +547,7 @@ const useMutableCallback = fn => {
 
 const useRapier = () => {
   const rapier = useContext(rapierContext);
-  if (!rapier) throw new Error('react-three-rapier: useRapier must be used within <Physics />!');
+  if (!rapier) throw new Error("react-three-rapier: useRapier must be used within <Physics />!");
   return rapier;
 };
 /**
@@ -657,6 +657,10 @@ const createSingletonProxy = createInstance => {
   const reset = () => {
     instance = undefined;
   };
+
+  const set = newInstance => {
+    instance = newInstance;
+  };
   /**
    * Return the proxy and a reset function
    */
@@ -664,7 +668,8 @@ const createSingletonProxy = createInstance => {
 
   return {
     proxy,
-    reset
+    reset,
+    set
   };
 };
 
@@ -739,7 +744,8 @@ const Physics = props => {
 
   const {
     proxy: worldProxy,
-    reset: resetWorldProxy
+    reset: resetWorldProxy,
+    set: setWorldProxy
   } = useConst(() => createSingletonProxy(() => new rapier.World(vectorArrayToVector3(gravity))));
   useEffect(() => {
     return () => {
@@ -995,6 +1001,9 @@ const Physics = props => {
   const context = useMemo(() => ({
     rapier,
     world: worldProxy,
+    setWorld: world => {
+      setWorldProxy(world);
+    },
     physicsOptions: {
       colliders,
       gravity

package/package.json

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

package/readme.md

@@ -82,6 +82,7 @@ For full API outline and documentation, see 🧩 [API Docs](https://pmndrs.githu
 - [Advanced hooks usage](#advanced-hooks-usage)
   - [Manual stepping](#manual-stepping)
   - [On-demand rendering](#on-demand-rendering)
+- [Snapshots](#snapshots)
 
 ---
 
@@ -413,7 +414,7 @@ const Scene = () => {
       // While Rapier's return types need conversion, setting values can be done directly with Three.js types
       rigidBody.current.setTranslation(position, true);
       rigidBody.current.setRotation(quaternion, true);
-      rigidBody.current.setAngVel({ x: 0, y: 2, z: 0 }, true);
+      rigidBody.current.setAngvel({ x: 0, y: 2, z: 0 }, true);
     }
   }, []);
 
@@ -812,3 +813,39 @@ Setting `<Physics updateLoop="independent" />` will make the physics simulation
   <Physics updateLoop="independent">...</Physics>
 </Canvas>
 ```
+
+## Snapshots
+The `world` can be serialized as a `Uint8Array` using `world.takeSnapshot()`, see Rapier's docs on [Serialization](https://rapier.rs/docs/user_guides/javascript/serialization/) for more info.
+
+The snapshot can be used to construct a new world. In `r3/rapier`, you need to replace the world with this snapshot.
+
+> [!NOTE]
+> This only works if the snapshotted world is identical to the restored one. If objects, or the order of creation of objects vary, expect RigidBodies to scramble.
+
+```tsx
+import { useRapier } from '@react-three/rapier';
+
+const SnapshottingComponent = () => {
+  const { world, setWorld, rapier } = useRapier();
+  const worldSnapshot = useRef<Uint8Array>();
+
+  // Store the snapshot
+  const takeSnapshot = () => {
+    const snapshot = world.takeSnapshot()
+    worldSnapshot.current = snapshot
+  }
+
+  // Create a new World from the snapshot, and replace the current one
+  const restoreSnapshot = () => {
+    setWorld(rapier.World.restoreSnapshot(worldSnapshot.current))
+  }
+
+  return <>
+    <Rigidbody>...</RigidBody>
+    <Rigidbody>...</RigidBody>
+    <Rigidbody>...</RigidBody>
+    <Rigidbody>...</RigidBody>
+    <Rigidbody>...</RigidBody>
+  </>
+}
+```