> ## Documentation Index
> Fetch the complete documentation index at: https://dadd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# useBodyState

> Track body position, rotation, and velocities

Returns refs tracking a body's position, quaternion, linear velocity, and angular velocity. Updated every physics frame without triggering re-renders.

## Signature

```tsx theme={null}
useBodyState(name: string): {
  position: React.RefObject<THREE.Vector3>;
  quaternion: React.RefObject<THREE.Quaternion>;
  linearVelocity: React.RefObject<THREE.Vector3>;
  angularVelocity: React.RefObject<THREE.Vector3>;
}
```

## Usage

```tsx theme={null}
import { useBodyState } from "mujoco-react";
import { useFrame } from "@react-three/fiber";

function BodyTracker() {
  const { position, quaternion } = useBodyState("block_1");

  const meshRef = useRef<THREE.Mesh>(null);

  useFrame(() => {
    // Mirror the body's position on a custom mesh
    meshRef.current?.position.copy(position.current);
    meshRef.current?.quaternion.copy(quaternion.current);
  });

  return <mesh ref={meshRef}><sphereGeometry args={[0.01]} /></mesh>;
}
```

### Velocity Tracking

```tsx theme={null}
function SpeedDisplay() {
  const { linearVelocity } = useBodyState("ball");
  const textRef = useRef<{ text: string } | null>(null);

  useFrame(() => {
    const speed = linearVelocity.current.length();
    if (textRef.current) textRef.current.text = `${speed.toFixed(2)} m/s`;
  });

  return <Text ref={textRef} position={[0, 0.5, 0]} />;
}
```

## Return Value

| Field             | Type                          | Description                                                    |
| ----------------- | ----------------------------- | -------------------------------------------------------------- |
| `position`        | `RefObject<THREE.Vector3>`    | World position from `data.xpos`                                |
| `quaternion`      | `RefObject<THREE.Quaternion>` | World rotation from `data.xquat` (converted to Three.js order) |
| `linearVelocity`  | `RefObject<THREE.Vector3>`    | Linear velocity from `data.cvel`                               |
| `angularVelocity` | `RefObject<THREE.Vector3>`    | Angular velocity from `data.cvel`                              |

## Notes

* Returns are **refs**, not state — read `.current` in `useFrame` or event handlers
* No re-renders on updates — this is intentional for 60fps performance
* The body is looked up by name once; if the name doesn't exist, values stay at zero
* `cvel` layout is `[angular(3), linear(3)]` per body — the hook reorders for you