mujoco-react 8.2.0 → 8.2.1

package/README.md

@@ -4,7 +4,7 @@
 
 # mujoco-react
 
-> **Beta** — This library is under active development. The API may change between minor versions until 1.0.
+> **Beta** — This library is under active development. The API may change between minor versions until 10.0.
 
 Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper around [mujoco-js](https://www.npmjs.com/package/mujoco-js). Load any MuJoCo model, step physics, render bodies, and write controllers as React components.
 
@@ -87,64 +87,37 @@ function MyComponent() {
 
 ## Writing a Controller
 
-A controller is a React component that uses handle-based hooks for type-safe actuator and sensor access:
+A controller is a hook that reads sensors and writes actuators each physics step:
 
 ```tsx
 import { useCtrl, useSensor, useBeforePhysicsStep } from "mujoco-react";
 
-function MyController() {
+function useMyController(gain: number) {
   const shoulder = useCtrl("shoulder");
   const elbow = useCtrl("elbow");
   const force = useSensor("force_sensor");
 
   useBeforePhysicsStep(() => {
-    shoulder.write(Math.sin(Date.now() / 1000));
+    shoulder.write(gain * Math.sin(Date.now() / 1000));
     elbow.write(force.read()[0] * -0.5);
   });
-  return null;
 }
 ```
 
-Drop it into the tree:
-
-```tsx
-<MujocoCanvas config={config}>
-  <MyController />
-</MujocoCanvas>
-```
-
-The `createControllerHook` factory produces a typed hook with config stabilization and default merging. Pass `null` to disable:
+For reusable controllers with typed config, default merging, and children, use the `createController` factory:
 
 ```tsx
-import { createControllerHook, useBeforePhysicsStep } from "mujoco-react";
-
-export const useMyController = createControllerHook<{ gain: number }, { value: number }>(
-  { name: "useMyController", defaultConfig: { gain: 1.0 } },
-  (config) => {
-    useBeforePhysicsStep((_model, data) => {
-      if (!config) return;
-      data.ctrl[0] = config.gain * Math.sin(data.time);
-    });
-    if (!config) return null;
-    return { value: config.gain };
-  },
-);
-
-// const result = useMyController({ gain: 2.0 });
-// const disabled = useMyController(null); // returns null
-```
-
-The `createController` factory is the component equivalent — same config stabilization, but returns a component that can render children:
-
-```tsx
-import { createController, useBeforePhysicsStep, Debug } from "mujoco-react";
+import { createController, useCtrl, useBeforePhysicsStep } from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
   ({ config, children }) => {
-    useBeforePhysicsStep((_model, data) => {
-      data.ctrl[0] = config.gain * Math.sin(data.time);
+    const shoulder = useCtrl("shoulder");
+
+    useBeforePhysicsStep(() => {
+      shoulder.write(config.gain * Math.sin(Date.now() / 1000));
     });
+
     return <>{children}</>;
   },
 );
@@ -154,6 +127,8 @@ export const MyController = createController<{ gain: number }>(
 // </MyController>
 ```
 
+A `createControllerHook` factory is also available for the hook equivalent — see the [Building Controllers](https://dadd.mintlify.app/guides/building-controllers) guide.
+
 ## Architecture
 
 `<MujocoCanvas>` wraps R3F `<Canvas>` and forwards all Canvas props (`camera`, `shadows`, `gl`, etc.). For full control over the Canvas, use `<MujocoPhysics>` inside your own:

package/package.json

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