# Alloy

> Alloy is a GPU physics engine for robotics, built on Newton, MuJoCo Warp and Warp (Python, `pip install alloy-engine`, import name `alloy`). One scene holds rigid robots (sub-millimetre contact for declared precision fits), cloth, liquids and other materials; Alloy routes each object to a suitable solver (MuJoCo Warp for rigid bodies and robots, Newton's VBD for cloth and soft bodies, Newton's MPM for sand and pastes, its own DFSPH for liquids), steps them together in parallel worlds on one GPU (thousands for free rigid bodies, 512 to 4,096 for a robot arm, tens to hundreds with cloth or liquid), checks the physics as it runs, and names everything so you read state by name.

Start with AGENTS.md: it is the complete quick start and every snippet in it runs as shown. The public API is `alloy.Scene`, `alloy.build`, `alloy.load`, `alloy.Sim` (`step`, `run`, `state`, `set_targets`, `health`, `check`), `alloy.estimate`, `alloy.materials`, `alloy.scenes` and the error classes; everything else is engine internals. Conventions: SI units, z up, sizes are full edge lengths, quaternion keys name their order (`quat_xyzw`, `quat_wxyz`). Without an NVIDIA GPU it runs on the CPU, slowly; the first build of a new scene compiles kernels (a few minutes on a GPU, more with cloth or liquid), cached afterwards.

## Short pages (the public docs set)

Each page is one idea with code that runs as written and the output it prints. Install is `pip install alloy-engine`.

- [Home](docs/public/index.md): what Alloy is, the install line, a 10-line example and its image
- [Quickstart](docs/public/quickstart.md): a first simulation, its result, an image, a health check, many worlds
- [What ships](docs/public/what-ships.md): every ready-made environment, robot and object library, with counts, licences and how to get each
- [Use Alloy with your coding agent](docs/public/agents.md): one prompt to paste, and what to ask an agent to do
- [Robots](docs/public/guides/robots.md): add a robot, drive a joint with a ramp, read its angle
- [Train with RL](docs/public/guides/rl.md): Gym-style environments, your own task, the one-command trainer
- [Imitation learning](docs/public/guides/imitation.md): record demonstrations, evaluate a policy
- [Camera](docs/public/guides/camera.md): render an image, place a camera, read depth
- [Liquids](docs/public/guides/liquids.md): water in a container, its volume, how much stays inside
- [Cloth](docs/public/guides/cloth.md): drape a sheet over an object and read its vertices
- [Cables](docs/public/guides/cables.md): lay a cable and read its centre line
- [World health](docs/public/guides/health.md): `sim.check()`, a failed world, every health flag with its fix
- [Errors and fixes](docs/public/errors.md): the error classes, `e.message` / `e.fix`, a symptom and fix table
- [Keep in mind](docs/public/keep-in-mind.md): one line per measured limit, linking its page

## Answers

One question per page, answered in the first paragraph, with code that runs as written.

- [What is the Alloy physics engine?](docs/public/faq.md): what it is, who makes it, install, platforms, GPU or CPU, licence, coding agents
- [Which physics simulator should I use for robot learning?](docs/public/compare/index.md): when to choose Alloy and when another engine; the other engines' cells were read, not tested
- [Alloy vs MuJoCo and MuJoCo Warp](docs/public/compare/mujoco.md)
- [Alloy vs Newton](docs/public/compare/newton.md)
- [Alloy vs Genesis](docs/public/compare/genesis.md)
- [Alloy vs MuJoCo Playground](docs/public/compare/mujoco-playground.md)
- [Alloy vs ManiSkill](docs/public/compare/maniskill.md)
- [How do I run a physics simulator on a Mac without a GPU?](docs/public/how-to/mac-without-gpu.md)
- [How do I render a camera for thousands of parallel worlds?](docs/public/how-to/camera-many-worlds.md)
- [How do I let Claude Code, Codex or Cursor build a robot simulation?](docs/public/how-to/coding-agents.md)
- [How do I simulate a cable or wire in Python?](docs/public/how-to/cable-or-wire.md)
- [How do I train a quadruped robot to walk with reinforcement learning?](docs/public/how-to/quadruped-rl.md)
- [How do I simulate cloth folding for robot learning in Python?](docs/public/how-to/cloth-folding.md)
- [How do I simulate pouring a liquid with a robot arm?](docs/public/how-to/pour-liquid-robot-arm.md)
- [How do I record a dataset of robot demonstrations?](docs/public/how-to/make-a-dataset.md)
- [How do I evaluate a trained policy on held-out seeds?](docs/public/how-to/evaluate-checkpoint.md)
- [Which simulator can put robots, cloth and liquids in the same scene?](docs/public/answers/robots-cloth-liquids-one-scene.md)
- [What open-source GPU-parallel physics engines are there for reinforcement learning?](docs/public/answers/gpu-parallel-engines-for-rl.md)
- [Which physics engines are built on MuJoCo Warp or Newton?](docs/public/answers/built-on-mujoco-warp-or-newton.md)
- [Is there a physics engine with an MCP server for AI agents?](docs/public/answers/mcp-server-physics-engine.md)
- [Which simulators handle deformable object manipulation: cloth, rope and soft bodies?](docs/public/answers/deformable-object-manipulation.md)
- [Which open-source simulators for robot learning install with pip?](docs/public/answers/pip-installable-simulators.md)
- [Which simulators that read MuJoCo models also support liquids and sand?](docs/public/answers/mujoco-models-with-liquids-and-sand.md)
- [How can I tell whether a physics simulation blew up during RL training?](docs/public/answers/did-my-simulation-blow-up.md)
- [Which pip-installable Python physics engine supports robot manipulation with soft bodies?](docs/public/answers/soft-body-manipulation-python.md)
- [How do I generate imitation-learning data for a task with liquids?](docs/public/how-to/imitation-data-with-liquids.md)
- [Which open-source engines do multi-physics robot simulation?](docs/public/answers/open-source-multi-physics-engines.md)
- [Which simulators support sand and granular materials for robot learning?](docs/public/answers/sand-and-granular-materials.md)
- [Which new robotics simulators were released in 2026?](docs/public/answers/new-robotics-simulators-2026.md)
- [How do I load a MuJoCo MJCF robot into a scene with cloth or liquid?](docs/public/how-to/mjcf-robot-with-cloth-or-liquid.md)
- [How do I use a GPU-parallel simulator with the Gymnasium vector API?](docs/public/how-to/gymnasium-vector-api.md)
- [How do I record a LeRobot dataset from simulation?](docs/public/how-to/lerobot-dataset.md)
- [How do I randomise friction and mass across parallel worlds?](docs/public/how-to/randomise-parallel-worlds.md)
- [How do I simulate squeezing a soft object between two fingers?](docs/public/how-to/squeeze-soft-object.md)
- [What do Alloy's error messages mean and what should I change?](docs/public/answers/error-messages.md)

## Start here

- [Keep in mind](docs/guide/known_limits.md): read first: the engine limits we have measured, one file each in [docs/known_gaps/](docs/known_gaps/), with its size, the workaround and the planned fix; other limits are stated on the guide page where you meet them
- [AGENTS.md](AGENTS.md): install, a short quick start, names and trajectories, robots, many worlds, cloth, liquid and heat, precision and health, errors, camera, checks, files, plug-ins
- [Guide index](docs/guide/README.md): one page per topic, deeper than AGENTS.md
- [Examples](examples/README.md): runnable scripts by topic (api, basics, camera, check, cli, compose, create, envs, export, il, io, plugins, soft, tactile, topology, viewer), each prints its results

## Guide

- [Install and devices](docs/guide/install.md): pip install, optional extras, GPU or CPU (with CPU costs: one core per process for liquid and cloth; many worlds split over processes with `processes=`), kernel compile cache, quiet logs
- [Scenes](docs/guide/scenes.md): shapes, meshes, materials, friction, library objects (where `pos` puts them: `anchor=`), loading and saving scenes
- [Robots](docs/guide/robots.md): MJCF / URDF / USD robots, the shipped arms (Panda, FR3, UR10e) and others, joint names, targets, ramps, grasping (friction only; carrying a container)
- [Cloth and liquid](docs/guide/deformables.md): add_cloth (flat sheets only: fabric, paper, plastic film, metal), add_liquid, containers, volumes, routes, CPU cost, cloth accuracy (40 accelerated VBD iterations by default; "super" 60, about 1.4x; "fast" 10, about 0.4x), metal sheets that dent (`"<sheet>.plastic_strain"`) and liquid accuracy (4 mm default, 2 mm "super")
- [Rods](docs/guide/rods.md): add_rod (cables, wires, cords: bend, twist, rolling, gripping), apply_wrench, points and twist, accuracy, cost, limits
- [Randomizing robots](docs/guide/randomize_robots.md): per-world masses, centre of mass, friction, servo gains, armature and gravity of a robot (opt-in), once or at every reset, `sim.randomized()`, a random start at every reset and timed pushes (`scene.add_push`; both checked on the CPU only), what is not covered
- [Many worlds and speed](docs/guide/worlds.md): per-world starts, randomize, seeds and determinism, timing, estimate, profiles, build options for speed (rerun_worlds, mpm_coupling, mpm_sweeps), the rigid step (chosen per scene for rigid-only scenes; an opt-in fast mode for rigid stacks)
- [Health, checks and errors](docs/guide/health.md): health flags and fixes, per-world counts (retired particles, refined coupling periods), check(), precision contact, error classes
- [Cards and engine layers](docs/guide/cards.md): YAML cards, the card library, SceneAssembler and build_simulation
- [Camera](docs/guide/camera.md): sim.render quick look, a Camera over every world, numpy or torch images; scanned objects with their photo textures; depth (metres), segmentation / body-id / world-id, instance-id, class and optical-flow images from the fast camera (flow for rigid motion only: NaN on cloth, liquid and soft bodies), with what they do not cover
- [Frame export](docs/guide/frame-export.md): hand frames of picked worlds to a viewer you write (Alloy's own viewer: viewer.md) (alloy.export: FrameExporter, frame_export): body poses, cloth and soft-body vertices, particle subsets and rod lines as numpy arrays, without changing the run
- [Viewer](docs/guide/viewer.md): watch a running sim in a browser tab, a desktop window, Rerun or a USD file (alloy.viewer: launch, contacts, backends): pause, step, pick worlds, rigid contact points and forces; read-only unless you opt in to joint sliders or mouse dragging (CPU-tested; dragging robot links not tested); optional packages
- [Scene checks](docs/guide/check.md): alloy.check findings with fixes, expect_rest, the JSON command line
- [Import and export](docs/guide/import_export.md): MJCF / URDF / USD robots and scenes in and out of cards
- [Plug-ins](docs/guide/plugins.md): new forces, sensors, objects and solvers; template, test harness (plug-ins run as ordinary Python with your permissions; only the opt-in check has a sandbox)
- [Heat](docs/guide/heat.md): temperature on liquid and paste particles (scene API, then the plug-in): heaters, air, melting, boiling, cooking, energy checks
- [Cutting](docs/guide/cutting.md): soft objects cut by a kinematic knife, set up in cards (`topology:` on the object, `blade:` on the knife); two cut models; limits
- [Command line and MCP](docs/guide/cli.md): `alloy` JSON command line and `alloy mcp` tool server, no Python needed
- [Gym environments](docs/guide/envs.md): VectorEnv over parallel worlds, torch tensors, ready-made tasks
- [Imitation learning](docs/guide/imitation.md): record episodes to robomimic HDF5 or LeRobotDataset v3, keyboard teleoperation, scripted demo generation, replay, policy evaluation (no training code)
- [RL libraries](docs/guide/rl.md): wrappers for rsl_rl, Stable-Baselines3 and skrl, a one-command PPO train, an arm pick env (PickCube-v0), observation groups, task-space actions, noise / delay / history layers, actuator models
- [Legged locomotion](docs/guide/locomotion.md): the Go2 velocity environment on flat ground or on rough terrain tiles with a level curriculum (commands, pushes, gravity / accelerometer / foot-contact observations), `python -m alloy.envs.loco.train` (a blind policy: no height scan, no stairs or gaps; no actuator model; one rough-terrain training run measured)
- [Isaac Lab](docs/guide/isaaclab.md): run an unmodified Isaac Lab 3.0 task on Alloy with `physics=alloy` (tasks that offer Newton MuJoCo Warp): install beside Isaac Lab, the switch, settings, health checks, what is verified and what is not
- [System identification](docs/guide/sysid.md): fit a simulated robot's joint gains, damping, friction and delay to a recording of your real robot (opt-in), report, apply, what is not covered
- [Scene builder](docs/guide/compose.md): a sentence in, a physics-checked scene and variations out
- [Scene variants](docs/guide/variants.md): alloy.vary / `alloy vary`: n copies of a scene with free objects moved and textures swapped within a family, JSON in and out
- [Fetching objects](docs/guide/fetch.md): `alloy fetch` downloads library objects from the Hugging Face Hub into the local cache (public, no login needed), JSON in and out
- [Your own objects](docs/guide/create.md): alloy.create turns a mesh, photo or text into a checked object card; alloy.audit stress-tests a scene

## API reference

- [alloy.api](alloy/api/__init__.py): module docstrings with examples; `help(alloy.Scene)` in Python shows the same
- [Scene](alloy/api/scene.py): every add_* method and its keywords
- [Sim](alloy/api/sim.py): step, run, state, set_targets, apply_wrench, faces, liquid_volume, routes, health, check, render
- [Errors](alloy/api/errors.py): SceneError, BuildError, SimulationError, UnknownNameError, FeatureUnavailableError

## Optional

- [Library](library/): shipped materials (each value with its source, measured to estimated, and an uncertainty range), objects, scenes and robots as YAML cards
- [Plug-in guide](alloy/plugins/GUIDE.md): writing a plug-in in full
- [Engine layers example](examples/basics/09_engine_layers.py): cards, CardLibrary, SceneAssembler and build_simulation without the API
