Crate imaginu 

imaginu — AI-drivable procedural 3D asset compiler.

JSON recipes → deterministic, game-ready GLB (meshes, PBR vertex colors, skeletal animation, physics metadata) for Babylon.js, plus a built-in software renderer for visual verification.

Quick start

// Compile a recipe straight to GLB bytes.
let glb = imaginu::compile_to_glb(r#"{"kind":"tree","style":"oak"}"#).unwrap();
assert_eq!(&glb[0..4], b"glTF");

Compilation is deterministic: the same recipe (and seed) always yields byte-identical output, on every platform. Malformed or hostile recipe JSON returns an Error rather than panicking — see the error module.

Re-exports

pub use error::Error;

pub use error::Result;

pub use gltf::Asset;

pub use gltf::to_glb;

pub use recipe::Recipe;

Modules

anim

CPU animation evaluation + skinning: sample a clip at time t, produce joint matrices, and deform a skinned mesh — so the software renderer can SHOW animation frames, not just bind poses.

csg

Boolean mesh operations (union / subtract / intersect) via BSP trees — the csg.js algorithm. Deterministic; vertex colors interpolate through edge splits; results come back flat-shaded (crisp cut edges).

error

Error type for the public imaginu API.

generators

Procedural asset generators. Each takes recipe params + seed and returns a fully-formed crate::gltf::Asset.

gltf

Hand-written glTF 2.0 GLB writer: multi-primitive meshes with PBR vertex-color materials, skins, animation clips, and physics metadata in node extras (read by the Babylon.js side).

mesh

Mesh building blocks: an indexed triangle mesh with vertex colors, optional skinning attributes, and helpers for construction/merging.

noise

Seeded gradient noise, fBm and domain warping. Hand-rolled for determinism across platforms and zero heavyweight deps.

palette

Curated palettes and color utilities. Colors are linear-space RGB (glTF expects linear vertex colors; the renderer gamma-encodes on output).

recipe

Recipe schema — the JSON surface an AI agent writes. Small, forgiving (everything except kind has a default), deterministic via seed.

render

Headless software rasterizer: renders an Asset to PNG so quality can be verified without a GPU. Perspective camera, z-buffer, Lambert + hemisphere ambient + rim lighting, 2x supersampling, gamma-correct output.

sdf

Signed-distance-field modeling + surface-nets meshing. Bodies built as ONE smoothly-blended field (capsules, round cones, ellipsoids under polynomial smooth-min) mesh into a single continuous organic surface — no part seams, normals straight from the field gradient. Deterministic: fixed grid, no randomness.

skinning

Smooth multi-joint skinning: distance-based automatic weights (up to 4 joints per vertex) so organic meshes bend without seams at joints. Rigid binding (Mesh::bind_all_to_joint) remains for hard parts.

subdiv

Loop-style subdivision: each triangle splits into 4 via shared edge midpoints; optional Loop smoothing rounds the result. Attributes (colors, uvs/tangents, skin weights, morph deltas) interpolate through.

texture

Deterministic procedural texture baking: noise-driven patterns rendered to PNG (baseColor sRGB, tangent-space normal map, ORM) and embedded in the GLB. Same spec → identical bytes. All patterns tile seamlessly.

uv

UV projection + tangent generation for baked textures.

validate

Structural GLB checks: chunk layout, accessor/bufferView bounds, per-primitive attribute counts, animation sampler pairing, embedded PNG magic, morph-target counts, skin consistency, instancing attributes.

world

World compiler: one recipe -> a directory of seamless, streamable chunk GLBs + manifest.json. Every height/color sample is a pure function of WORLD coordinates + seed (the “seam law”), so adjacent chunks share bit-identical edges and any chunk built alone equals the same chunk built in a full run.

Functions

compile

Parse a recipe and compile it into an in-memory Asset.

compile_to_glb

Compile a recipe directly to serialized GLB (.glb) bytes, ready to write to disk or hand to a glTF loader such as Babylon.js.