Creature Lab is a failure-first, local workbench for robot morphology experiments. Design a body, run it in physics, and find out whether a failure came from the body, controller, task, fragility, or simulator — then hand someone the exact experiment that proves it. Everything is inspectable JSON and runs offline on an ordinary laptop.
Design → Run → Autopsy → Improve → Verify → Share
The distinctive unit is a minimum reproducible robot experiment: creature, task, controller, trace, hashes, and runtime provenance in a verified pack. Creature Lab is an educational and early-prototyping tool — not hardware qualification, a cloud service, or a GPU-scale RL platform.
From a fresh checkout, run one launcher. It installs the starter extras, checks the environment, and opens the interactive build editor in your browser — configure a creature first, then run it, instead of jumping straight into physics.
.\scripts\start.ps1python scripts/start.pyA terminal shows setup progress and an editor URL such as http://localhost:8080. Pick a
preset, tune it, click Simulate to run it through the physics pipeline and read its
score/diagnosis and a robustness sweep in the same panel, then Save to write a normal
CreatureSpec JSON (or .urdf). Try a different starting body with
python scripts/start.py --creature humanoid.
No browser handy? Once installed, a bare creature-lab with no arguments runs a built-in
creature through its measured gait and prints score + diagnosis straight to the terminal:
uv run creature-labIf launch fails, start with python scripts/start.py --dry-run and uv run creature-lab doctor.
uv sync --inexact --extra sim --extra viz
uv run creature-lab buildFor the plain looping playback demo instead of the setup screen: uv run creature-lab demo --open-browser (add --no-hold to save a trace and exit after one pass).
uv run creature-lab zoo list
uv run creature-lab zoo run quadruped
uv run creature-lab autopsy examples/quadruped.json --task examples/crawl_forward.json
uv run creature-lab evolve examples/quadruped.json --task examples/crawl_forward.json --attempts 20zoo run uses the measured curated controller by default; autopsy explains why a run
scored the way it did and emits a reproducible pack; evolve searches for a better body/gait.
See Getting Started for the full first-session walkthrough and
CLI Reference for every command.
- A curated Creature Zoo: quadruped, worm, hexapod, tripod, damaged quadruped, and humanoids.
- A browser build editor for presets, body sliders, part edits, motor tuning, validation,
simulation, live metrics/diagnosis, a robustness sweep, and URDF import/export — all in one
screen, with optional live file-sync to a project directory (
--project). - Portable JSON specs for creatures and tasks, and physics runs saved with exact creature/task/controller snapshots, hashes, scores, contacts, and warnings.
- Experiment Autopsy: controller counterfactuals, task-aware perturbation trials, optional backend comparison, cause attribution, and a recommended next experiment.
- A Failure Zoo of intentionally broken experiments for teaching and diagnostic regression.
- Local improvement loops:
evolvefor search andask --offlinefor validated design edits. - Replay, diagnosis, GIF/MP4 export, and advanced backend/export bridges.
CreatureSpec + TaskSpec
-> run a physics episode
-> save an EpisodeTrace
-> inspect or diagnose the result
-> evolve or edit the creature
-> replay/export the best run
Every creature, task, and controller is JSON. Every episode is a trace. Every simulator is an adapter.
PyBullet is the default simulator. Specs, tasks, traces, and replays are portable; exact physics behavior is backend-dependent.
- Documentation Home - where to start and how the docs fit together.
- Getting Started - the shortest path from clone to first run.
- Build Editor - browser setup screen for creating CreatureSpec JSON.
- Concepts - creatures, tasks, traces, backends, and the improve loop.
- Creature Spec and Task Spec - JSON authoring.
- Run Artifacts - what is saved under
runs/<run-id>/. - Zoo - bundled creatures, tasks, baselines, and challenge pack.
- Failure Lab - hypothesis-driven lessons using intentional failures.
- CLI Reference - every command, grouped by workflow.
- Known Issues - latent gaps and deliberate limitations found in review.
- Changelog - notable changes by release.
- Grand Plan / Roadmap / Releasing - maintainer-facing roadmap and release process.
A sample of what's available beyond the first run — full detail in CLI Reference:
| Need | Command |
|---|---|
| Diagnose why a run failed | uv run creature-lab diagnose runs/<run-id> |
| Optimize a creature's gait (2-3x typical) | uv run creature-lab optimize creature.json --task task.json --out gait.json |
| Combine success/robustness/portability into one pass-fail | uv run creature-lab qualify creature.json --task task.json --profile basic-locomotion |
| Check robustness / cross-backend gap | uv run creature-lab robustness runs/<id> --trials 10 / sim2sim runs/<id> |
| Export a shareable, verified run | uv run creature-lab export-pack latest --out outputs/my_pack |
| Train a policy with reinforcement learning (PPO) | uv sync --extra rl, then uv run creature-lab train creature.json --task task.json --out outputs/trained |
| MuJoCo backend | uv sync --extra mujoco, then uv run creature-lab run ... --backend mujoco |
| URDF/MJCF bridge | export-urdf, export-mjcf, import-urdf |
| Gymnasium-style control | creature_lab.rl.gym_env.CreatureGymEnv (a real gymnasium.Env) |
Install everything with uv sync --all-extras.
uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run creature-lab zoo check-showcasesCI runs Ruff, Pytest, packaging, showcase acceptance, a real browser journey, and platform jobs on Linux, Windows, and macOS. See CONTRIBUTING.md for the full pre-PR checklist and docs/project/RELEASING.md for the release process.
Do not build a PyBullet project. Build a backend-agnostic creature lab where PyBullet is only the first backend.