Threedarium

Threedarium is an LLM-first compiler for static, textured 3D assets. A model edits a versioned .threed program; the compiler turns it into a typed asset DAG, runs explicit geometry/material workers, publishes GLB/LODs/colliders, and feeds quantitative diagnostics plus six inspection passes back into the next vision iteration.

The design target is a ready website/game prop, not a one-shot mesh: correct meter scale and pivot, UVs, normals and MikkTSpace tangents, typed glTF PBR textures, separate LOD/collider GLBs, validation evidence, and resumable agent checkpoints.

Development status: v0.1 implementation baseline. The Rust language/CLI, Node geometry/texture/agent workers, and Python validation/Blender worker live in this repository. Deterministic CPU previews make compat/source publication testable without Blender; the full reference-render/color pipeline remains capability-gated by installed system tools. threedarium doctor --require full verifies that Blender and the complete publication toolchain are usable before a full-pipeline run, while dependency-specific tests skip rather than claim evidence when an optional native tool is absent.

Why a language?

Generated mesh bytes lose the intent an LLM needs to revise an asset. .threed keeps dimensions, operations, materials, hierarchy, colliders, LOD policy, and assertions readable:

@language("0.1");

param width: Length = 1.2m;
let solid: SolidMesh = mesh.rounded_box(
  size: [width, 0.8m, 0.6m],
  radius: 2cm,
);
let mesh: Mesh = mesh.to_mesh(solid: solid);
let mapped: Mesh = uv.xatlas(
  mesh: mesh,
  resolution: 2048,
  padding: 8,
  texelsPerMeter: 512,
);
let paint: Material = material.pbr(
  baseColor: [0.18, 0.42, 0.72, 1],
  metallic: 0,
  roughness: 0.55,
);
let root: Node = scene.node(name: "Prop", mesh: mapped, material: paint);
let asset: Asset3D = scene.asset(root: root, pivot: "bottom-center");
export asset;

The compiler never silently converts SolidMesh, Mesh, or Field3, and never substitutes a missing backend. The canonical frame matches glTF: meters, right-handed, +Y up, and +Z forward.

Repository

• crates/: Rust compiler, CLI, diagnostics, scheduler, LSP and MCP surface
• packages/: TypeScript protocol, geometry, texture, viewer/agent workers
• python/threedarium-worker/: unsafe-Python SDK, Trimesh/Pillow validation, Blender 4.5 scripts
• schemas/: normative IR, RPC, diagnostics, event, run, provenance, manifest, stdlib, and toolchain contracts
• examples/: eight offline static-prop fixture projects
• docs/: architecture, language, generated stdlib reference, ecosystem survey, security, agent and release runbooks

Capability map

Layer	Current contract
Language	Lossless parsing/recovery, formatting, modules, typed quantities/assets, public params, IR/schema output, unsafe Python/JavaScript declarations
Geometry	Manifold solids/CSG; Three.js primitives/curves/scene; explicit Blender operations; xatlas UV, MikkTSpace tangent, meshoptimizer LOD/collider boundaries
Materials	glTF metallic-roughness roles; ordered typed layer stacks; exact masks/ORM; OpenImageIO/OpenColorIO transforms; sRGB color/emissive and linear normal/data; explicit bake/generation recipes
Publication	source, compat, and web profiles; main/LOD1/LOD2/collider GLBs, a decoder-independent companion for every web build, 36 canonical pass/view renders, seven contact sheets, manifest, and external hard validators
AI	Codex CLI and direct GPT-5.6 Sol Responses adapters; mandatory multiview imagegen/vision concept gate; image-tool probe with explicit gpt-image-2 fallback
Security	Bubblewrap on Linux; declared capabilities; artifact/path/buffer limits; unsafe nodes uncached by default

Characters, animation, exact CAD, fabrication, simulation, and USD composition are intentionally outside v0.1.

Build from source

Supported release host: Linux x86-64.

pnpm install --frozen-lockfile
cargo build --workspace
python3 -m pip install -e 'python/threedarium-worker[dev]'
just test

Core requirements are Rust/Cargo, Node 22+, pnpm, Python 3.12+, and Bubblewrap. Web delivery additionally needs gltfpack and KTX-Software. Full reference rendering/baking needs Blender 4.5 LTS, OpenImageIO, and OpenColorIO. The CLI does not download them. Every build uses the bounded deterministic CPU renderer for its required publication previews; threedarium render prefers Blender when 4.5 LTS is available and otherwise reports its CPU fallback:

cargo run -p threedarium-cli -- doctor --json

See installation and doctor for profile details.

Release archives are self-contained for the Node runtime layer: they ship the three stdio workers, the viewer-copy executable, production Node dependencies, the built static viewer, and an installable Python wheel. See the release installation layout for the exact commands and paths.

CLI surface

threedarium init [--codex]
threedarium doctor [--require core|compat|web|source|full] [--json]
threedarium fmt [--check]
threedarium check [--json|--sarif]
threedarium build [--profile source|web|compat] [--param key=value]
threedarium render [--views ...] [--passes ...]
threedarium inspect [--json]
threedarium validate [--json]
threedarium serve
threedarium texture generate|derive|compress
threedarium generate|refine|resume
threedarium docs search|schema
threedarium test [--update]
threedarium lsp
threedarium mcp serve
threedarium cache prune

Operational commands expose stable JSON events and differentiated exit codes: 2 source/validation, 3 configuration/tool, 4 worker, 5 provider, and 130 interrupted. An interrupted agent command emits its resumable checkpoint before returning 130.

Agent contract

Generation is an authoring loop, not part of build. Before source authoring, it image-generates a turnaround and material-detail sheet, re-opens both at original vision detail, and revises them until cross-view construction, materials, and exact markings pass. It then checks source before rendering, inspects beauty/clay/wireframe/normal/depth/object-ID contact sheets, critiques against prompt/references/the accepted concept, and preserves every passing checkpoint. Runs have no default iteration or spending cap; user limits are optional and explicit. Ctrl-C leaves a resumable manifest.

Generated images are ordinary relative files with threedarium.image-provenance/0.1 sidecars. Unchanged committed asset bytes can therefore rebuild offline.

Documentation

Read the documentation index and ecosystem decision matrix. The generated standard-library reference covers all 139 v0.1 operations and their required backends.

The core is dual-licensed under MIT or Apache-2.0. Optional/runtime dependencies retain their own terms; see third-party notices.