# MuJoCo Walker Scaffold

This folder adds a Python + MuJoCo rigid-body simulation track to the existing web-based kinematic simulator.

## What is included

- A rigid-body 4-leg linkage model in MJCF (two legs per side, tandem links).
- A fully unconstrained 3D torso base (`freejoint`) so roll/yaw/lateral motion emerge from contacts.
- One crank motor per side; each motor drives two legs through closed-chain constraints.
- A PD crank controller baseline (phase-driven near/far cranks).
- A CLI runner for quick simulation and optional viewer.
- A CSV trajectory exporter for replay/comparison workflows.

## Setup with uv

From this directory:

```bash
uv sync
```

Run the baseline simulation (headless):

```bash
uv run walker-run --seconds 10
```

Evaluate gait quality numerically:

```bash
uv run walker-eval --seconds 10
```

## Foot length tuning (middle ground between 5 cm and 30 cm)

In `model/walker.xml`, lateral foot span is controlled by these capsule geoms:

- `near_front_foot_lateral`
- `near_rear_foot_lateral`
- `far_front_foot_lateral`
- `far_rear_foot_lateral`

Their `fromto` Y distance is the effective foot length (for example `0.30` means 30 cm).

Practical search strategy:

1. Run a coarse sweep from 5 cm to 30 cm.
2. Keep only lengths with `fallen=False`.
3. From those, pick the shortest length that still has acceptable forward speed.
4. Run a fine sweep around that candidate (for example +/-3 cm).

Use the dedicated sweep command (run from `sim/mujoco`):

```bash
uv run walker-tune-feet --min-cm 5 --max-cm 30 --step-cm 2 --seconds 10
```

To save results for plotting:

```bash
uv run walker-tune-feet --min-cm 5 --max-cm 30 --step-cm 1 --csv ../../artifacts/foot_sweep.csv
```

Suggested acceptance rule for "middle ground":

- `fallen=False`
- pick the smallest stable length first
- use speed/sway as secondary tie-breakers

With the current baseline controller, a good first region to inspect is usually around `8-15 cm`, then refine from there.

You can run any simulator command with an overridden foot length (without editing `walker.xml`) via `--foot-cm`:

```bash
uv run walker-eval --seconds 15 --foot-cm 15
uv run walker-export-web --frame world --seconds 15 --foot-cm 15 --out ../../artifacts/mujoco_trace_15cm.json
```

Run with interactive MuJoCo viewer:

```bash
uv run walker-run --viewer --seconds 30
```

Render video without opening a GUI:

```bash
uv run walker-video --seconds 12 --out ../../artifacts/walker.mp4
```

Export a CSV trajectory:

```bash
uv run walker-export --seconds 15 --out ../../artifacts/walker_traj.csv
```

Export playback JSON for the browser viewer (true 3D playback + 2D overlay):

```bash
uv run walker-export-web --frame world --seconds 15 --out ../../artifacts/mujoco_trace.json
```

Use `--frame world` for physically grounded playback in the web app. In world frame, the feet contact the ground plane at `z=0` and torso height stays above the floor as expected.

If you export with `--frame body`, the torso is re-centered to body-local coordinates (`torso.z ~= 0`), which is useful for relative-linkage debugging but can look like the body is dropped onto the floor in overlay/playback.

In the web app, use "MuJoCo Import" to load that JSON.

You can also load built-in MuJoCo playback presets from the web app "Presets" tab:

- `MuJoCo 10cm trace`
- `MuJoCo 20cm trace`
- `MuJoCo 30cm trace`

- Default format is `v2` (`walkersim-mujoco-playback-v2`) and is used for true playback in the 3D pane.
- To export the old 2D-only overlay schema, add `--format v1`.

## RL wrapper

Install RL dependencies:

```bash
uv sync --extra rl
```

Train PPO baseline:

```bash
uv run walker-train-ppo --steps 200000
```

## Notes

- The torso now uses an unconstrained freejoint; side tilt is physically simulated, but the default PD crank gait can be less stable and may tumble during some runs.
- The model matches the codebase linkage layout (nearF/nearG/farF/farG) but still needs tuning for stronger forward gait.
- This scaffold is independent from the browser simulator and can be evolved without breaking the JS app.
- Next step is geometry alignment/tuning against the linkage dimensions in the main app.

## TODO

- Tune contact/friction/damping to improve stability with unconstrained 3D freejoint dynamics.
- Retune PD gait phase offsets and gains for forward progress under full 3D dynamics.
- Add roll/pitch/yaw summary metrics to `walker-eval` for easier stability regression checks.
- Add a short recommended viewer camera preset for inspecting side tilt behavior.