Open-Source Tool Lets AI Agents Infer Lego Mechanisms from LDraw Source and Animate Them 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

[!NOTE] The installation process will install every required tool and dependency locally on this project repo, in order to avoid polluting the host OS.

However, there is a requirement of setting several env vars on rc files, like e.g. .bashrc or .zshrc

The installed dependencies, like e.g. Blender, are git-ignored by default.

You'll need Python 3.12+ installed.

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

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

[!NOTE] More samples available at: Gallery

Animations have been generated from original models, not from ai-generated ones.

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.

<a href="samples/42043-crane.png"><img src="samples/42043-crane.png" width="320" alt="42043 Mercedes-Benz Arocs flatbed truck"></a>

▶ Video · Summary

Original

<a href="img/42043-1_Flatbed-Trailer.png"><img src="img/42043-1_Flatbed-Trailer.png" width="320" alt="42043 Mercedes-Benz Arocs flatbed truck"></a>

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.

<a href="samples/3625.png"><img src="samples/3625.png" width="320" alt="3625 Fabuland plane"></a>

▶ 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.

<a href="samples/minifigs.png"><img src="samples/minifigs.png" width="320" alt="Minifig movement catalog"></a>

▶ Video · Summary

（注：更多技术实现细节与完整 API 文档请查阅原项目 README）

作者发帖说明（HN）：

Hi there :)

Around a month ago, I released LDraw Nova, an agentic toolset for assembling LEGO CAD models by generating LDraw source code files.

For more details, here's the Show HN post:

https://news.ycombinator.com/item?id=49937916

From the comments, I got the impression that there was quite an interest in seeing not only AI-generated LEGO models, but also AI-animated LEGO ones.

I took a look at results from past experiments, and found it feasible to use agentic LLMs for:

• analyzing the LDraw source code for LEGO models - reverse-engineer! the mechanisms present by reading the descriptions and sequence for the parts there - and then, animate them via Blender!

This new project I'm presenting, LDraw Mecha, is the end result and proof that can be done:

• Read specially annotated LDraw LEGO models .mpd source files - Infer the model structure in terms of submodels - Select from those the ones that are mechanisms - Plan animations - Execute them in Blender

In summary, from an initial .mpd source file, get a rigged and animated version for the model as a Blender (.blend) file.

See the results here:

• Repo (v0.5.0): https://github.com/anteloc/ldraw-mecha/tree/v0.5.0 - Gallery: https://github.com/anteloc/ldraw-mecha/blob/v0.5.0/GALLERY.m... - Process: [https://github.com/anteloc/ldraw-mecha/blob/v0.5.0/PRO...