imaginu

An AI-drivable procedural 3D asset compiler. JSON recipes → deterministic, game-ready GLB for Babylon.js - meshes, PBR vertex colors, skeletal animation, and physics metadata. No textures to wrangle, no C dependencies, byte-identical every time.

🌐 Live site & Babylon viewer · 📖 Docs · 🤖 Use it with your AI agent

What & why

imaginu compiles a small JSON recipe into a .glb asset you can drop straight into a Babylon.js scene. It exists because describing an asset is far cheaper than modeling one - especially for an AI agent, which can write a recipe, look at a render, and iterate, all without a DCC tool.

LLMs are great at structured parameters and terrible at raw vertex data. imaginu is the bridge: the agent decides what ("a windswept autumn oak, seed 42") and imaginu produces the how (a crafted mesh with harmonious colors, correct normals, a skeleton, walk/idle clips, and a collider).

• AI-native. imaginu schema prints the full recipe contract as a cheat-sheet. An agent reads it, writes JSON, and compiles - the skill wires this into Claude Code / Codex.
• Vertex-color PBR, no texture pipeline. Color lives in the mesh, so assets are small, self-contained, and load anywhere glTF loads. (Baked procedural PBR texture sets are available in the custom DSL when you want them.)
• Deterministic. Same recipe + seed → byte-identical GLB, on every OS. This is what lets worlds tile seamlessly and makes agent output reproducible.
• Zero C dependencies. Pure Rust (glam, serde, clap, png, rand). Static cross-compilation - including fully static musl - is trivial.
• Batteries included. A built-in software renderer lets you look at your output (PNG or MP4 turntable) without a GPU or a running engine.

Install

Prebuilt binary (no Rust needed):

curl -fsSL https://raw.githubusercontent.com/vicotrbb/imaginu/main/install.sh | sh

With cargo:

cargo install imaginu           # build from crates.io
cargo binstall imaginu          # or grab a prebuilt binary via cargo-binstall

From source:

git clone https://github.com/vicotrbb/imaginu && cd imaginu
cargo install --path .

ffmpeg on your PATH is optional - needed only for video (imaginu showcase, world --flyover). Everything else is standalone.

60-second quickstart

# Compile a recipe to GLB and render a PNG to look at:
imaginu generate '{"kind":"tree","style":"oak"}' -o tree.glb --preview

# The whole recipe contract, any time:
imaginu schema

# A rigged, animated character (build: slim|average|heavy|heroic, frame: masculine|feminine|neutral):
imaginu generate '{"kind":"character","class":"warrior","build":"heavy","animate":true}' -o hero.glb

# A rigged, animated monster (8 body plans + class presets):
imaginu generate '{"kind":"monster","body":"wyrm","class":"elemental"}' -o wyrm.glb

# A themed, navigable dungeon (per-room GLBs + manifest.json + overview.png):
imaginu dungeon '{"kind":"dungeon","type":"crypt","size":"medium"}' -o crypt/ --overview

# A multi-phase boss encounter creature (5 archetypes, weak-point metadata):
imaginu generate '{"kind":"boss","archetype":"hydra","element":"infernal"}' -o hydra.glb --preview

# A seamless streaming world (manifest.json + one GLB per chunk):
imaginu world '{"kind":"world","name":"everdale","size":2048}' -o everdale/

# Verify structure:
imaginu validate tree.glb

Load it in Babylon.js like any glTF - colliders ride along in the extras:

const { meshes } = await BABYLON.SceneLoader.ImportMeshAsync("", "", "tree.glb", scene);
const physics = meshes[0].metadata?.gltf?.extras?.imaginu_physics;
// → { collider: { type: "capsule", radius, height }, mass, friction, restitution }

Recipe gallery

Each of these is one line of JSON. Full field reference: imaginu schema. A boss is a multi-part, multi-phase, weak-point-tagged encounter creature (5 archetypes: hydra/colossus/lich/swarm_queen/dragon_lord) that places into dungeon boss rooms and world POIs.

Whole worlds, too - Voronoi biome zones, traced rivers, A*-routed roads, and a POI solver placing cities/castles/dungeons, all seamless across chunk borders:

See the live site for these GLBs running in a real Babylon.js viewer, plus looping video showcases. Recipes for everything above live in gallery/recipes/ and examples/.

🤖 Use it with your AI agent

imaginu ships a first-class agent skill so Claude Code or Codex can go from "make me a 3D oak tree" to a loadable GLB on its own - write recipe → generate → look at the PNG → iterate.

# Claude Code:
cp -r skill/imaginu ~/.claude/skills/imaginu

See skill/imaginu/SKILL.md for the workflow and Codex install instructions. The skill stays DRY against imaginu schema - the schema command is the reference, the skill is the workflow.

Determinism & the seam law

Generation is a pure function of (recipe, seed). Two consequences you can rely on:

1. Reproducible output - the same recipe yields a byte-identical GLB anywhere. CI enforces this on every push (generate twice, diff bytes, on both Linux and macOS to guard a known platform float heisenbug).
2. The seam law - terrain heights and colors are pure functions of world coordinates, so adjacent world chunks share bit-identical edges and tile with no cracks. Any chunk builds lazily (--chunk x,z) or in parallel with identical output. This is what makes streaming worlds possible.

Architecture

Pure-Rust library (src/lib.rs) + CLI (src/main.rs), cleanly modular:

Library entry points: imaginu::compile(recipe_json) and imaginu::compile_to_glb(recipe_json), both returning Result<_, imaginu::Error>

• the public boundary returns errors instead of panicking on malformed JSON.

CLI reference

Contributing

See CONTRIBUTING.md. The two rules: determinism is sacred and render and look before claiming visual quality. cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test must all be clean. Changelog: CHANGELOG.md.

License

MIT © 2026 Victor Bona.