Animate LDraw mechanisms in Blender

ldraw-mecha

Give an LDraw LEGO© model to an AI agent, get back a Blender-animated version of it.

The agent will:

• Reverse-engineer (infer) the LDraw model's mechanics from its .mpd source code file 🤓
• Study the discovered mechanisms.
• Plan the interactions between their different mechanical components.
• And finally, turn those plans into python code for Blender, that will:
  • Create the required rigs for controlling the different mechanisms.
  • Animate them according to plan! 🤯

Installation

You'll need Python 3.12+ installed.

System	Requirements
macOS	git-lfs (brew install git-lfs)
Linux, x86_64 (WIP, untested)	git-lfs, Blender and LeoCAD required graphics libs
Windows (WIP, untested)	Run inside WSL2 (Ubuntu)

Start by cloning the repo and running the setup script, pick the right one for your OS:

git clone https://github.com/anteloc/ldraw-mecha.git
cd ldraw-mecha
./setup-macos.sh            # or ./setup-linux.sh, ./setup-win-wsl.sh

Installed during setup

Item	Version
uv	0.9.3
bun	1.4.4
ldraw-annotator	0.5.0
ldraw-xray	0.5.0
jev-rerank	0.5.0
mpd2glb	0.9.1
Blender	5.2.3
LeoCAD	26.09
LDraw parts library	latest

At the end of the setup process, you'll get a snippet with the env vars to be added to your shell profile (.bashrc, .zshrc, etc.), something like e.g.:

# >>> ldraw-mecha (from setup-macos.sh) >>>
export LDRAW_DIR="/Users/me/ldraw-mecha/data/ldraw"
export LDRAWDIR="$LDRAW_DIR"
export BLENDER_BIN="/Users/me/ldraw-mecha/bin/Blender.app/Contents/MacOS/Blender"
export LEOCAD="/Users/me/ldraw-mecha/bin/LeoCAD.app/Contents/MacOS/LeoCAD"
export LDRAW_XRAY_CACHE="/Users/me/ldraw-mecha/.cache/ldraw-xray"
export LDRAW_ANNOTATOR_DB="/Users/me/ldraw-mecha/data/ldraw-info.db"
# export TYPESAFE_API_KEY=...   # optional: Jev semantic search (jev-rerank)
# other env vars...
# <<< ldraw-mecha <<<

If you're on VS Code or a terminal, restart it in order to get an updated env with the newly added env vars.

Usage

For inspecting and selecting one pre-annotated model to animate, open the annotated models selector by running:

python3 model-selector/serve.py

Then, take a look at the Process guide for a step-by-step usage example.

Samples

These are some samples of animations by different agents, take a look at their Summaries for more details.

42043 Mercedes-Benz Arocs flatbed truck: the pneumatic crane on its own

• Agent: Claude Sonnet 5.5
• Original model: 42043-1_Flatbed-Trailer.mpd
• Context: The model was too large and complex for fully animating it, finally I accepted Sonnet's suggestion about animating the crane alone.

▶ Video · Summary

Original

3625 Fabuland plane: take-off, flight and landing

• Agent: Claude Sonnet 5.5
• Original model: 3625-1.mpd
• Context: Asked for an in-place animation, to avoid the plane moving around.

▶ Video · Summary

Minifig movement catalog: ten minifigs, three moves each

• Agent: Claude Opus 5.5
• Original model: None
• Context: This one is actually a generated composition, from several different minifigs, to be used as a "howto reference" for other agents also animating minifigs.

▶ Video · Summary

Agent's informational sources

Need	Read
The whole process, step by step, on one example	Process
Everyday commands and recovery	Workflow
Joint types, equations, frames and fields	Motion plan
Source discovery and live Blender tools	API guide
Look boards for candidates and authored joints	Visual inspection with ldraw-xray
Missed contacts, rounded transforms, coverage	Discovery quality
Part families, descriptions and dimensions	Part information
Testing, clearance and evidence limits	Validation
Code boundaries	Architecture
Publishing a selected working example	Curation and asset archive

Why and How?

After publishing LDraw Nova, a sibling project for agentic generation of LDraw models, several people reached out to me asking about if models could be animated somehow.

During the development of Nova, I noticed that adding some special annotations to .mpd original model source files, and then giving those to agents, would:

• Help agents in understanding how to build other different models.
• But also, in understanding how a model was built.

Which gave me the idea that, maybe, an agent would also understand how a model would work.

Reverse-engineering mechanisms from their sources

As a first step to it, I gave annotated models to different agents, and prompted them to infer (reverse-engineer) their constituent submodels (see Haiku 5.5. experiment below).

Results from inference experiments were both pretty good and consistent across different agents, and I also noticed the following: many of the submodels inferred were actually mechanisms.

After questioning several agents about those inferred mechanisms, regarding how would they actually work, I also got consistent results: agents would describe behaviours based on the descriptions for the parts on a mechanism! 🤯

At this point, I had the following:

• Agents would split and refine models into submodels and mechanisms.
• Agents would understand each mechanism in isolation.
• Agents would understand how individual mechanisms worked.

The result of an actual divide-and-conquer process, right? 🤓

Which would make handling individual mechanisms manageable. 🤩

Correlating LDraw source code to a 3D model

Now, there was the matter of giving agents the means to actually animate mechanisms they already knew how they worked.

I was playing with Blender MCP at the time, and Blender looked promising as a tool that would provide agents a way to manipulate LDraw models in 3D, imported into Blender as glTF (.glb) files.

But there was still an open issue:

How to map from a refined model source code an agent would understand, to its equivalent 3D model in glTF format an agent could manipulate?

And the solution I found was:

Annotate the 3D glTF model's nodes with the same annotations as the source code, so the agent would:

• Outside Blender: plan on submodels 🤔 and parts as source code.
• Inside Blender: execute on matching nodes ✨ on the 3D glTF model.

Putting the pieces together 😉

Now, I had a draft for a process, but no tools for the agent to use and carry it forward.

Given that the process would require a high amount of complex geometric and spatial calculations, I asked the agent to derive a new python toolset from the one created for ldraw-nova

The new python toolset I refined iteratively, by giving the agent simple models at the beginning, and increasingly complex ones each time.

And to test it, I gave an agent instructions to:

• first, plan from an annotated and refined .mpd model
• then, generate a glTF 3D version of it, with matching annotations
• then, upload it to Blender
• and then, produce the Blender python scripts that would animate the model as planned.

And it finally worked! 🚀🚀🚀

(but not perfectly) 😜

Experiment - Claude Haiku 5.5 reverse-engineering session

Prompt:

This is a fragment, a submodel, from an LDraw .mpd file model.

This is not an executable code fragment, but more like a 3D CAD model fragment written in LDraw language.
Infer what this submodel is, and also split it into submodels (starting with: 0 FILE):

• always with relevant, semantical meaning,
• the first 0-line following every 0 FILE line is the "description line" for the submodel, according to the LDaw standard
• add the description for every submodel there, a one-liner, as a person would describe it while looking at it
• at the answer, first place the parent model, then the child one(s) and then the grandchildren, and then descendants... etc.: go from containers or parents to containees or children, children of children. etc.

---

Expand code...

0 FILE file-01  
0 file-01  
0 Name: file-01.ldr  
0 Author: Unknown  
0 !LDRAW_ORG Model  
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt
0 // Plate 2 x 12 (dark_bluish_grey)  
1 72 0 0 0 1 0 0 0 1 0 0 0 1 2445.dat  
0 // Tile 1 x 2 Grille with Groove (metallic_silver)  
1 80 -110 -8 0 0 0 1 0 1 0 -1 0 0 2412b.dat  

0 STEP  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 -80 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 -40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 0 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 100 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 100 8 -20 1 0 0 0 1 0 0 0 1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 0 8 -20 1 0 0 0 1 0 0 0 1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 -40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat  
0 // Slope Brick Curved 2 x 2 x 0.667 (metallic_silver)  
1 80 -80 8 -20 1 0 0 0 1 0 0 0 1 15068.dat  
0 // Slope Brick Curved 4 x 1 Double with Red "NASA", Black "ESA", and Silver Background Pattern (light_bluish_grey)  
1 71 70 8 0 -1 0 0 0 1 0 0 0 -1 10283 - 93273p01.dat  
0 STEP  
0 // Tile 2 x 2 Inverted (light_bluish_grey)  
1 71 100 8 -20 1 0 0 0 1 0 0 0 1 11203.dat  
0 // Tile 2 x 2 Inverted (light_bluish_grey)  
1 71 100 8 20 1 0 0 0 1 0 0 0 1 11203.dat

---

Answer:

This is a rounded silver hull section, probably a spacecraft piece such as a fairing, payload-bay shell, or module skin. It sits on a 2x12 dark-grey base plate, with a grille tile at the -X end and two light-grey inverted tiles at the +X end. The ridge slope carries red "NASA" and black "ESA" printing, so it likely comes from a space-agency-themed LEGO model, though the parts alone don't identify the exact set.

The split below follows the physical groups, which also match the three build steps in the original. The parent comes first, then its children (hull-shell.ldr and end-cap-tiles.ldr), then the grandchildren (the two slope rows). Coordinates are unchanged, so each submodel keeps its absolute positions and the parents reference children with an identity transform at the origin.

---

Expand code...

0 FILE curved-hull-section.ldr
0 Rounded silver hull section on a long dark-grey base plate, with a grille at the -X end and light-grey tiles at the +X end
0 Name: curved-hull-section.ldr
0 Author: Unknown
0 !LDRAW_ORG Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 // Plate  2 x 12 (dark_bluish_grey)
1 72 0 0 0 1 0 0 0 1 0 0 0 1 2445.dat
0 // Tile  1 x  2 Grille with Groove (metallic_silver)
1 80 -110 -8 0 0 0 1 0 1 0 -1 0 0 2412b.dat
0 STEP
1 16 0 0 0 1 0 0 0 1 0 0 0 1 hull-shell.ldr
0 STEP
1 16 0 0 0 1 0 0 0 1 0 0 0 1 end-cap-tiles.ldr

0 FILE hull-shell.ldr
0 Curved silver shell made of two rows of slopes joined by a NASA/ESA-marked ridge piece
1 16 0 0 0 1 0 0 0 1 0 0 0 1 shell-row-positive-z.ldr
1 16 0 0 0 1 0 0 0 1 0 0 0 1 shell-row-negative-z.ldr
0 // Slope Brick Curved 4 x 1 Double with Red "NASA", Black "ESA", and Silver Background Pattern (light_bluish_grey)
1 71 70 8 0 -1 0 0 0 1 0 0 0 -1 10283 - 93273p01.dat

0 FILE end-cap-tiles.ldr
0 Two light-grey inverted 2x2 tiles closing off the +X end of the hull shell
0 // Tile  2 x  2 Inverted (light_bluish_grey)
1 71 100 8 -20 1 0 0 0 1 0 0 0 1 11203.dat
0 // Tile  2 x  2 Inverted (light_bluish_grey)
1 71 100 8 20 1 0 0 0 1 0 0 0 1 11203.dat

0 FILE shell-row-positive-z.ldr
0 Row of five silver curved slopes forming one side of the shell, on the +Z side
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -80 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 0 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 100 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat

0 FILE shell-row-negative-z.ldr
0 Row of five silver curved slopes forming the other side of the shell, on the -Z side
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -80 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 0 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 100 8 -20 1 0 0 0 1 0 0 0 1 15068.dat

---

I replaced the original description file-01, which was only a file name, with real one-liners. I also renamed the root from file-01 to curved-hull-section.ldr, so if the outer MPD references file-01, that reference needs updating. All 15 original part lines are preserved, and I can save this as a .mpd file if you want it as a download. This is the same fragment I split a moment ago, so here is the same answer again. It is a rounded silver hull section, probably a spacecraft piece, on a 2x12 dark-grey base plate, with a grille at the -X end and two light-grey inverted tiles at the +X end. The ridge slope has red "NASA" and black "ESA" printing, so it likely comes from a space-themed LEGO model, though the parts don't identify the exact set.

The parent comes first, then its children (hull-shell.ldr and end-cap-tiles.ldr), then the grandchildren (the two slope rows). Coordinates are unchanged, and the parents reference their children with an identity transform at the origin.

---

Expand code...

0 FILE curved-hull-section.ldr
0 Rounded silver hull section on a long dark-grey base plate, with a grille at the -X end and light-grey tiles at the +X end
0 Name: curved-hull-section.ldr
0 Author: Unknown
0 !LDRAW_ORG Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 // Plate  2 x 12 (dark_bluish_grey)
1 72 0 0 0 1 0 0 0 1 0 0 0 1 2445.dat
0 // Tile  1 x  2 Grille with Groove (metallic_silver)
1 80 -110 -8 0 0 0 1 0 1 0 -1 0 0 2412b.dat
0 STEP
1 16 0 0 0 1 0 0 0 1 0 0 0 1 hull-shell.ldr
0 STEP
1 16 0 0 0 1 0 0 0 1 0 0 0 1 end-cap-tiles.ldr

0 FILE hull-shell.ldr
0 Curved silver shell made of two rows of slopes joined by a NASA/ESA-marked ridge piece
1 16 0 0 0 1 0 0 0 1 0 0 0 1 shell-row-positive-z.ldr
1 16 0 0 0 1 0 0 0 1 0 0 0 1 shell-row-negative-z.ldr
0 // Slope Brick Curved 4 x 1 Double with Red "NASA", Black "ESA", and Silver Background Pattern (light_bluish_grey)
1 71 70 8 0 -1 0 0 0 1 0 0 0 -1 10283 - 93273p01.dat

0 FILE end-cap-tiles.ldr
0 Two light-grey inverted 2x2 tiles closing off the +X end of the hull shell
0 // Tile  2 x  2 Inverted (light_bluish_grey)
1 71 100 8 -20 1 0 0 0 1 0 0 0 1 11203.dat
0 // Tile  2 x  2 Inverted (light_bluish_grey)
1 71 100 8 20 1 0 0 0 1 0 0 0 1 11203.dat

0 FILE shell-row-positive-z.ldr
0 Row of five silver curved slopes forming one side of the shell, on the +Z side
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -80 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 0 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 40 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 100 8 20 -1 0 0 0 1 0 0 0 -1 15068.dat

0 FILE shell-row-negative-z.ldr
0 Row of five silver curved slopes forming the other side of the shell, on the -Z side
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -80 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 -40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 0 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 40 8 -20 1 0 0 0 1 0 0 0 1 15068.dat
0 // Slope Brick Curved  2 x  2 x  0.667 (metallic_silver)
1 80 100 8 -20 1 0 0 0 1 0 0 0 1 15068.dat

---

I replaced the original file-01 description, which was just a file name, with real one-liners, and renamed the root to curved-hull-section.ldr. If the outer MPD references file-01, that reference will need updating. All 15 original part lines are preserved, and I can save this as a .mpd file if you want a download.

Development

This is a very preliminar release that, however, yields many good results, but far from being optimal:

• Complex mechanisms and large models take too much time and effort to animate.
• Also for those, agents would go through "rabbit holes" and get lost during animation sessions.
• Broken animations for flexible parts on models like e.g. hoses or cables.
• Low-end models, like e.g. Claude Haiku 5.5 or GPT-6 Luna, can produce animations, but most of them have noticeable defects.
• No proper physics, it doesn't take into account e.g. gravity or any forces interactions, weights, inertia, etc.
• And more... 🤫

Trademarks

LEGO(R) is a trademark of the LEGO Group of companies which does not sponsor, authorize or endorse this software.

examples/README.md

Preserved examples

output/ is the working directory. This directory retains copies of the selected results used by the reference library, so documentation remains useful after that working directory is deleted. Original sources and results are not moved or rewritten during archiving.

The selection records which artifacts were chosen. The manifest records each original working path, source SHA-256, archived SHA-256 and size. Plans/reports keep their original provenance, including historical machine-specific filenames. Adapted review scripts are identified in the manifest with both hashes and an adaptation note.

Bundle	Contents and documentation
42110	Defender drivetrain, steering, engine and winch
42083-w16	Geared crankshafts and slider-crank engine
42110-suspension-standalone	Suspension, with retained full-model measurement inputs
42083-mechanisms	Five independent Chiron rigs
minifigs	Articulated figures and clips
movables	Doors, windows, hatches, slides and motion styles
plants	Plant articulation and shared wind responses

Corresponding *-reference-review directories hold the evidence behind the documents. Other small bundles preserve the discovery and workflow regressions specifically cited by the docs. This is a selected archive, not a copy of every experiment, backup scene, generated diagram or rendered frame.

Read and play back

Fetch Git LFS content when cloning (git lfs pull): GLB, blend and selected image/video files are LFS-managed. Open an archived blend directly to inspect its native controls and Actions; save any edits as a new working file. Saved Blender playback does not need the original MPD paths, but rebuilding/checking source dependencies needs the relocated paths below. Follow the case's evidence page for an archived-input reopen command (--bundle on catalog checkers).

Archived REPORT.md/CATALOG.md files describe the original work. Their prose and code samples can still name original output/ locations; these are provenance, not the current location or instructions to overwrite a retained example. The curated docs provide current commands. Maintained builders remain in scripts/; original LDraw geometry/shadow libraries still come from the configured library.

Reuse a saved plan in this checkout

Never edit an archived source manifest merely to change workstations. Create a new working plan with only its source/dependency filenames relocated; hashes, coordinates, occurrence IDs and motion are preserved:

.venv/bin/python scripts/reference_assets.py plan \
  examples/reference/movables/S01_house_door/plan.json \
  --output output/door-study/plan.json
./ldraw-mecha validate output/door-study/plan.json
./ldraw-mecha rig output/door-study/plan.json \
  --glb examples/reference/movables/S01_house_door/study/model.glb \
  --save output/door-study/rigged.blend --report output/door-study/check.json

The relocation refuses missing or hash-mismatched sources and existing output files. It resolves archived generated MPDs under examples/reference/ and original model data under data/, never falls back to a stale working copy. For Python review code, scripts/reference_assets.load_plan(path) performs the same relocation in memory. This is a portability helper, not a new motion format. If the source selection/geometry changes, prepare and bind a new source normally.

Add future references

1. Work and verify under output/NEW_CASE, following the curation guide. Select the minimal inputs, evidence, scripts and playback assets needed to support and reuse the result.
2. Add the bundle's explicit file patterns to reference/selection.json, then run .venv/bin/python scripts/reference_assets.py copy NEW_CASE. Include its review bundle separately when applicable. This copies files, checks existing hashes and refuses to overwrite a changed snapshot. Earlier output directories do not need to exist when a new bundle is selected explicitly.
3. Link the documentation to the retained copies. Keep new runs under output/. If copied scripts need path adaptations, record the adaptation and new archived hash in the manifest while preserving source_sha256. Keep the original script in its working location unchanged. A materially changed result gets a new versioned bundle and a fresh review of its claims.
4. Run .venv/bin/python scripts/reference_assets.py check. It validates hashes, local document links, source dependencies and rejects links into output/. Check that every added artifact is eligible for Git tracking and that LFS objects are included with the change. Commit examples and docs together.

build_examples.py remains the separate executable baseline-example generator; its newly generated results belong in output/, not in this archive.

Verification of the archive

The 2026-10-12 portability review ran all seven source reviews in a separate checkout with no original working artifacts copied and Python access to the original output/ blocked. Six saved Blender bundles passed background reopen checks there. A relocated door plan also passed a fresh build, reopen and lifecycle check. The detailed reports are retained beside that summary. The 200 relevant Python tests passed, as did the two wind code examples and all seven new Mermaid renders.

These checks establish reproducibility of the retained definitions and sampled motion. They do not replace the individual references' clearance qualifications or establish physical feasibility.