Creature Lab

Design robots, simulate them, and understand why they succeed or fail.

Creature Lab is a local workbench for designing modular robot bodies, running them in physics, and finding out whether a result came from the body, controller, task, fragility, or simulator. It saves the exact experiment so you can inspect, replay, improve, and share it.

Design -> simulate -> diagnose -> improve -> verify -> share

It is designed for education and early prototyping, not hardware qualification, a cloud service, or large-scale GPU reinforcement learning.

Quick start

git clone https://github.com/oney-erge/Creature-Lab.git
cd Creature-Lab
./run.sh            # Linux; macOS: ./run.command

On Windows, use .\run.bat. The launcher sets up the starter environment and opens the browser-based build editor. Pick a preset, tune its body and motors, click Simulate, then read the score, diagnosis, and robustness results.

Each run produces ordinary JSON: a creature, task, controller, trace, hashes, and runtime provenance. That is the project's central unit: a minimum reproducible robot experiment.

No browser? After setup, run the built-in demo from a terminal:

uv run creature-lab

If launch fails, try python scripts/start.py --dry-run and uv run creature-lab doctor.

The launchers also accept doctor, repair, docker, logs, and stop. Docker binds the editor to localhost and keeps runs and outputs in named volumes.

Next steps

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 20

• zoo run runs a curated creature and controller.
• autopsy explains why a result scored as it did and writes a reproducible pack.
• evolve searches for a better body and gait.

The Getting Started guide walks through a complete first session. The CLI reference covers every command.

What it includes

• A Creature Zoo with working and deliberately broken examples.
• A browser editor for presets, parts, motors, validation, simulation, and URDF import/export.
• Physics traces, replay, diagnosis, robustness tests, and GIF/MP4 export.
• Local improvement tools for search and validated design edits.
• Portable JSON contracts for creatures, tasks, controllers, and traces.

PyBullet is the default simulator. The JSON specifications and saved traces are portable, but exact physics behavior can differ by backend.

Documentation

Guide	Use it for
Getting Started	A complete first experiment
Build Editor	Creating and editing creatures in the browser
Concepts	Creatures, tasks, traces, simulators, and improvement
Zoo	Bundled creatures, tasks, and challenge packs
Failure Lab	Intentional failures and diagnostic lessons
CLI reference	Advanced commands and exports
Known issues	Current limitations
Documentation home	JSON schemas, run artifacts, and advanced guides
Contributing	Development and verification

Apache-2.0. Built by Oney Erge.