mujoco-react 8.4.0 → 8.4.2

package/README.md

@@ -18,113 +18,89 @@ Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper a
 npm install mujoco-react three @react-three/fiber @react-three/drei
 ```
 
-## Quick Start
+## Load a Model
 
 ```tsx
-import {
-  MujocoProvider,
-  MujocoCanvas,
-  useIkController,
-  IkGizmo,
-} from "mujoco-react";
+import { MujocoProvider, MujocoCanvas } from "mujoco-react";
 import type { SceneConfig } from "mujoco-react";
-import { OrbitControls } from "@react-three/drei";
 
-const config: SceneConfig = {
+const panda: SceneConfig = {
   src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
   sceneFile: "scene.xml",
   homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
 };
 
-function Scene() {
-  const ik = useIkController({ siteName: "tcp" });
-  return (
-    <>
-      <OrbitControls enableDamping makeDefault />
-      {ik && <IkGizmo controller={ik} />}
-      <ambientLight intensity={0.7} />
-      <directionalLight position={[1, 2, 5]} intensity={1.2} castShadow />
-    </>
-  );
-}
-
-function App() {
+export function App() {
   return (
     <MujocoProvider>
       <MujocoCanvas
-        config={config}
+        config={panda}
         camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
-        shadows
         style={{ width: "100%", height: "100vh" }}
-      >
-        <Scene />
-      </MujocoCanvas>
+      />
     </MujocoProvider>
   );
 }
 ```
 
-## `useMujoco()`
-
-Inside `<MujocoCanvas>` or `<MujocoPhysics>`, `useMujoco()` gives you the simulation API, refs to the live model/data, and status:
+## Add Scene Tools
 
 ```tsx
-import { useMujoco } from "mujoco-react";
-
-function MyComponent() {
-  const { isPending, isError, error, api, mjModelRef } = useMujoco();
+import { OrbitControls } from "@react-three/drei";
+import { IkGizmo, useIkController } from "mujoco-react";
 
-  if (isPending) return <span>Loading...</span>;
-  if (isError) return <span>Error: {error}</span>;
+function PandaTools() {
+  const ik = useIkController({ siteName: "tcp" });
 
   return (
-    <button onClick={() => api.reset()}>
-      Reset ({mjModelRef.current?.nq} joints)
-    </button>
+    <>
+      <OrbitControls makeDefault />
+      {ik && <IkGizmo controller={ik} />}
+      <ambientLight intensity={0.7} />
+      <directionalLight position={[1, 2, 5]} intensity={1.2} />
+    </>
   );
 }
 ```
 
-## Writing a Controller
-
-A controller is a hook that reads sensors and writes actuators each physics step:
+Use it as a child of `<MujocoCanvas>`:
 
 ```tsx
-import { useCtrl, useSensor, useBeforePhysicsStep } from "mujoco-react";
+<MujocoCanvas config={panda}>
+  <PandaTools />
+</MujocoCanvas>
+```
+
+## Write Controllers
 
-function useMyController(gain: number) {
-  const shoulder = useCtrl("shoulder");
-  const elbow = useCtrl("elbow");
-  const force = useSensor("force_sensor");
+```tsx
+import { useBeforePhysicsStep } from "mujoco-react";
 
-  useBeforePhysicsStep(() => {
-    shoulder.write(gain * Math.sin(Date.now() / 1000));
-    elbow.write(force.read()[0] * -0.5);
+function MyController() {
+  useBeforePhysicsStep((_model, data) => {
+    data.ctrl[0] = Math.sin(data.time);
   });
+
+  return null;
 }
 ```
 
-### Applying Forces
+Controllers are just React children that read sensors, write `data.ctrl`, apply forces, or call the `MujocoSimAPI` at physics-step time.
 
-Write directly to `xfrc_applied` in a physics callback for per-frame forces. The layout is `[torque_x, torque_y, torque_z, force_x, force_y, force_z]` per body:
+## Use the Sim API
 
 ```tsx
-import { useBeforePhysicsStep } from "mujoco-react";
+import { useMujoco } from "mujoco-react";
 
-function useSpringForce(bodyId: number, target: [number, number, number], stiffness = 100) {
-  useBeforePhysicsStep((_model, data) => {
-    const i3 = bodyId * 3;
-    const i6 = bodyId * 6;
-    data.xfrc_applied[i6 + 3] = (target[0] - data.xpos[i3]) * stiffness;
-    data.xfrc_applied[i6 + 4] = (target[1] - data.xpos[i3 + 1]) * stiffness;
-    data.xfrc_applied[i6 + 5] = (target[2] - data.xpos[i3 + 2]) * stiffness;
-  });
+function ResetButton() {
+  const sim = useMujoco();
+  if (!sim.isReady) return null;
+
+  return <button onClick={() => sim.api.reset()}>Reset</button>;
 }
 ```
 
-The `api.applyForce(bodyName, force)` convenience method also works for one-off interactions (e.g. button clicks) but does a name lookup each call.
-
-### WebSocket Control
+## WebSocket Control
 
 Stream actuator commands over a WebSocket and send simulation state back. Use a schema validator such as Zod at this boundary because socket messages are untrusted app input (`npm install zod` for this example):
 
@@ -133,32 +109,28 @@ import { useEffect, useRef } from "react";
 import { z } from "zod";
 import { useMujoco, useBeforePhysicsStep, useAfterPhysicsStep } from "mujoco-react";
 
-const CtrlCommand = z.object({
-  type: z.literal("ctrl_command"),
-  ctrl: z.array(z.number()),
-});
-
-type CtrlCommand = z.infer<typeof CtrlCommand>;
-
-function parseSocketMessage(data: string): CtrlCommand | null {
+const CtrlCommand = z.preprocess((data) => {
   try {
-    const parsed = CtrlCommand.safeParse(JSON.parse(data));
-    return parsed.success ? parsed.data : null;
+    return typeof data === "string" ? JSON.parse(data) : data;
   } catch {
-    return null;
+    return undefined;
   }
-}
+}, z.object({
+  type: z.literal("ctrl_command"),
+  ctrl: z.array(z.number()),
+}));
 
 function useWebSocketControls(url: string) {
   const wsRef = useRef<WebSocket | null>(null);
-  const latestCommandRef = useRef<CtrlCommand | null>(null);
+  const latestCtrlRef = useRef<number[] | null>(null);
 
   useEffect(() => {
     const ws = new WebSocket(url);
     wsRef.current = ws;
 
     ws.onmessage = (evt) => {
-      latestCommandRef.current = parseSocketMessage(evt.data);
+      const command = CtrlCommand.safeParse(evt.data);
+      if (command.success) latestCtrlRef.current = command.data.ctrl;
     };
 
     return () => ws.close();
@@ -166,10 +138,10 @@ function useWebSocketControls(url: string) {
 
   // Apply incoming actuator controls each physics step.
   useBeforePhysicsStep((model, data) => {
-    const command = latestCommandRef.current;
-    if (!command) return;
-    for (let i = 0; i < Math.min(command.ctrl.length, model.nu); i++) {
-      data.ctrl[i] = command.ctrl[i];
+    const ctrl = latestCtrlRef.current;
+    if (!ctrl) return;
+    for (let i = 0; i < Math.min(ctrl.length, model.nu); i++) {
+      data.ctrl[i] = ctrl[i];
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.4.0",
+  "version": "8.4.2",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",