mojulo

# Mojulo

[![npm](https://img.shields.io/npm/v/mojulo)](https://www.npmjs.com/package/mojulo)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![node](https://img.shields.io/badge/node-%E2%89%A522.12-brightgreen)](control/package.json)

![A coding agent wired to mojulo over MCP: "build a 20 by 24 ft living room with a door on the south wall" mints a 12-line floorplan recipe, the dashboard shows the furnished room shaded with turnable views and HTML / glb / STL downloads, "add pot lights to the ceiling" edits one field on the same recipe, a couch-facing fix lands in the kernel with the recipe unchanged, and the same recipe renders in Blender Cycles before and after — same seed, same camera](docs/images/lounge-handoff-demo.gif)

<sub>One conversation, one recipe. <i>"Build a 20 by 24 ft living room with a door on the south wall"</i> mints a twelve-line floorplan recipe (`create_sketch`, kind <code>floorplan</code>) — walls, windows, sofa, two chairs, rug, lamp — served shaded and turnable at <code>/sketches/&lt;ref&gt;</code>. <i>"Add pot lights"</i> flips one field on the stored recipe (`update_sketch`); nothing is re-minted. <i>"The couch has its back to the TV"</i> is not the recipe's fault: a two-line kernel fix turns the sofa, and every lounge in every floorplan re-renders seated toward the screen while this recipe stays the same twelve lines, same seed. The handoff is the same file rendered in Blender Cycles, before and after, same camera. No key, no cloud render.</sub>

Mojulo is a 3D factory for agents: a local MCP server where everything your coding agent makes is a small recipe it can re-run identically.

**Install:** `npx mojulo init` — detects the MCP hosts on your machine (Claude Code, Codex, Claude Desktop, and others by declared profile), wires mojulo in, opens the dashboard. No API key needed. [Quickstart ↓](#quickstart)

**Mojulo is a 3D factory for agents** — local, yours, not a hosted service. Point the agent you already run (Claude Code, Codex) at it and build **objects, worlds, and games by conversation**: you talk; the agent does the generating and the reasoning. Mojulo catches that output as a deterministic **recipe** on your own disk — a few kilobytes of parameters that regenerate identically, are editable a line at a time, and outlive the chat.

**One ladder.** An **object** blocks out at literal scale. A **world** is a place you can walk. A **level** is a world minted under a game contract. A **game** composes the levels. Every rung is the same kind of recipe — deterministic geometry built from primitives on your machine, no image model, no cloud render, **no provider key** — so pieces compose upward, and **sound comes free**: SFX and music synthesized from pure math and seeded dice, no samples.

**Two pipelines out.** DIGITAL: worlds, levels and scenes render dependency-free in the browser (CSS-3D, WebGL) and export to **Godot** as a real project, to **Unity** and **Unreal** as a data pack plus importer (each with an advisory gate when the engine is installed), and to **Blender** as an art-pass pack — with `.glb` and OpenUSD for everything else. PHYSICAL: objects, vehicles and wordmarks export as **print-ready STL or 3MF at true scale** — mm units, z-up, slicer-ready, with a slicer gate that stamps what it measured — so a conversation ends at your 3D printer; figures and worlds print as maquettes fit to a size you choose.

**Mojulo feeds the tools you already use; it does not compete with them.** It is the agent-driven upstream — it authors the truth at home, and the edge tool consumes it without guessing at the seam. It is not a renderer trying to out-render Unreal, and it is not merely an exporter: the recipe is where the thing is born, lives, and re-renders. The engine or the printer is where it is optionally *finished*.

**Not a second brain — a body.** Your agent is the only intelligence in the loop. Mojulo holds state, runtime, and the audit trail, and needs no LLM credentials of its own: photo references are read by the agent's eyes, games are verified by agent-compiled traversals, and the reasoning bill stays on your existing Claude or ChatGPT subscription.

---

## What you can make

Every kind below is a recipe your agent mints from a sentence, iterates in place, and hands off through the same doors ([Where it goes](#where-it-goes)). Find a kind by intent with `sketch_what_possible` or `semantic_search`; read its manual with `get_solid_vocab` / `get_view_vocab` before passing a spec.

**Objects, at literal scale.**

- **Parts and mechanisms** — `mint_solid` on the workbench: lathes, sweeps, extrudes, lofts and field solids in real millimetres; **booleans are a line in the recipe** (`cuts[]` names a body and the parts that bore or intersect it); assemblies seat parts by declared relation ("the mug on the table"), not coordinates. `measure_solid` reads bounds, printed size, closure, Manifold volume and genus, overhang and wall thickness off the stored recipe without exporting.
- **Figures and animals** — a posed human body (stances, a reach, a walking gait, named emotes) and the same armature reoriented horizontal for dressed species and bare archetypes from rodent to theropod. Rigs export as glTF clips, as skinned meshes, or with VRM humanoid bone names.
- **Vehicles, wordmarks, everyday things** — vehicle-family instances, carved metal or bevelled wordmarks and badges, turntable solids, and blocked-out objects (a candlestick, a lamp, a snowman with a top hat).
- **Machina** — `verify_machina` checks a mechanism chain (levers, pulleys, screws, inclines) against a load: work conservation, force capacity, rate and storage margins. A verdict, not a picture.

**Places, walkable.**

- **Buildings and interiors** — furnished floorplans that stack (`levels[]` gives a building storeys, stairs through the slabs, set-back terraces as real decks), bespoke buildings authored as masses and concourses, and caves and dungeons grown procedurally. All traversable, all exportable.
- **Cities, hubs and campuses** — `compose_world` picks a base (a recursive skyline, an airport or station, a K-12 campus, a planetary body, a walkable Cayley graph) and a theme, then takes the base's own knobs. A city declares what one unit is in metres, so mechanics and exports scale with it.
- **Landscapes** — painterly terrain composed from sky, palette and geometry glyphs, or map-backed from real geo data.
- **Drivable worlds** — a live world you walk, fly or platform through, with the camera and entities as first-class primitives; an `action` base adds rules (score, timer, spawns, pickups). Opt-in WebXR on walkable worlds. A volumetric effects layer rides over the mesh.
- **Study objects** — animated science and math explainers (fission, the double slit, a derivative, DNA) from one kind plus a few knobs. The catalog is open: an attached recipe book adds chapters and whole new kinds.

**Games, composed.**

- `create_game` binds levels, music, figures and sprites by ref into a standalone playable artifact: a shell that owns a typed store (character, inventory, party, progression, flags) and a list of levels minted under a `game:` contract. Improve a bound world or score and the game inherits it. Arcade cabinets compile 2D reducer games to a single HTML file.
- `export_game` writes the game to a plain folder you host anywhere, or emits a Godot, Unity or Unreal pack instead. Play data never enters mojulo.

**Assets that fold in.**

- **Sound** — Beats synthesizes ambient loops, grooves, SFX cues, footsteps and full scores from seeded math, never samples; a part can sing; a deterministic voice register narrates. Worlds opt in to soundtracks; a score exports as WAV or MIDI.
- **From a photo** — your agent is the vision adapter: show it a picture and `reference_protocol` → `capture_reference` recover a room's perspective, a figure's pose, a landscape's gesture, or an object's part-graph as a scaffold. No vision key; the image never reaches mojulo.
- **Skins and surface detail** — a polygomer or figure can wear a painted skin; a mesh sculpted outside (TripoSR, Hunyuan3D, a cloud API, a hand pass in Blender) binds back to its recipe with hash provenance.
- **Motion** — any of the above set moving: a turntable, an orbit, a fly-through, baked to a GIF with `forge_motion`; clips stitch into an MP4.

![A terminal prompt — "create a snowman with a top hat" — becomes a bonded part-graph recipe, then the shaded snowman in the dashboard viewer with turnable views and HTML / glb / STL downloads — no API key, no image model](docs/images/snowman-demo.gif)

<sub>One prompt: <i>"Connect to mojulo and create a snowman with a top hat."</i> Your agent mints a bonded part-graph (`mint_solid` — three snowballs, a brimmed top hat, twig arms, a carrot nose, coal buttons, a scarf) as an editable deterministic recipe, then iterates coloration in place on the same ref. The dashboard serves the shaded model with turnable views at `/sketches/top_hat_snowman`; the same ref downloads as a self-contained HTML viewer, a <code>.glb</code> for Blender or Godot, or a print-ready <code>.stl</code>. No key, no cloud render.</sub>

---

## Where it goes

**One geometry spec, several targets, all off a single minted ref:** `/api/sketches/<ref>/{svg,scene,world,model.glb,model.stl,model.3mf,model.usdz}`. Each URL regenerates the file deterministically on request. Each emitter owns its own frame and unit conversion from mojulo's native z-up metres, and every handoff carries an **honest-loss ledger** naming what did not travel.

| Target | What you get | The gate |
|---|---|---|
| **Browser** | A still SVG; a dependency-free CSS-3D `preserve-3d` scene (real 3D in a plain HTML file, no WebGL, no build step); a traversable WebGL world you walk with WASD. | Your eyes. |
| **`.glb`** | glTF with mojulo's lighting baked into vertex colours and exported unlit, so it looks identical from any camera with no setup downstream — or `lit` fo