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:

uv sync

Run the baseline simulation (headless):

uv run walker-run --seconds 10

Evaluate gait quality numerically:

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:

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

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

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

To save results for plotting:

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:

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:

uv run walker-run --viewer --seconds 30

Render video without opening a GUI:

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

Export a CSV trajectory:

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

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

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:

uv sync --extra rl

Train PPO baseline:

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.