Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Diorama: speak a little world into being
Diorama turns one sentence into a tiny, explorable 3D world. You describe a scene, an AI set designer decomposes it into a placed set of single objects, and each object is forged into a real textured GLB and dropped into place, live, as it arrives. The finished world sits on a small floating island you can orbit, view in AR, save to a public gallery with its own permalink, and export as a single merged GLB that opens cleanly in Scene Studio.
Page: /diorama · API: /api/diorama
Why it exists
Forge makes one object at a time. But a world is a composition: a campfire and a tent and three pine trees, arranged on the ground, lit for a mood. Doing that by hand means forging each piece, importing them into a scene editor, and placing them one by one. Diorama collapses that into a sentence. It is the difference between a modeling tool and a director's chair: you say what you want to see, and the platform composes, generates, and assembles it in front of you. Every object is a real mesh (no billboards, no fakes), so the result is genuine geometry you can walk around, share, and take into any glTF tool.
How it works
Diorama is a four-step pipeline (api/diorama.js plus src/diorama/), and each step is real.
Compose.
POST /api/diorama {action:'compose', prompt}sends your sentence to the platform's free-first LLM chain (llmComplete) with a 3D-set-designer system prompt. The model returns a strict JSON plan: a 2-to-4-word title, a mood (dawn/day/dusk/night), a ground type (grass/sand/snow/stone/water/meadow/void), an island shape (round/craggy/plateau), a color palette (sky gradient, ground, fog, accent), and a placed list of objects. Each object is exactly one physical thing (a single tree, a single tent, never a scene and never "and"), with a one-line forge prompt (subject plus dominant material and color), an(x, 0, z)position spread across the island with spacing enforced, a scale, and a Y rotation. Objects come back withstatus:'pending'and no meshes.Forge each object. The browser walks the plan and calls
/api/forgefor every object, on the free lane, watching each one turn frompendingtoforgingtoready(orfailed, with an in-place retry). The renderer (src/diorama/renderer.js) materializes each mesh into the scene the moment it arrives, so the world assembles progressively in front of you rather than appearing all at once.Save and share.
POST /api/diorama {action:'save', diorama}persists a fully-forged world, returns an{id, url}permalink, opens the share sheet, refreshes the gallery, and rewrites the page URL to the new permalink. A signed-in creator's world links to their public portfolio; anonymous saves fall back to a plain handle.Export.
POST /api/diorama {action:'export', diorama}merges the world's objects, ground, and lights into one GLB (api/_lib/scene-graph-compose.js) with named, selectable nodes, uploads it, and hands back aglbUrlplus asceneStudioUrlso it opens directly in Scene Studio (/scene) or any glTF viewer.
A headless one-shot, POST /api/diorama {action:'build', prompt}, runs the whole flow server-side (compose, forge every object on the free lane, export the merged GLB) for callers with no browser to drive the progressive client, such as MCP tools and agents.
Reads: GET /api/diorama?id=<uuid> loads a saved world (a deep link renders it read-only and offers a remix), and GET /api/diorama?list=recent|featured&limit=<n> returns gallery cards. The gallery renders each card as live geometry through <model-viewer>, not a flat thumbnail.
There are no mocks: if the LLM chain is unreachable, the compose route returns a clean 503 and the page shows a designed retry state instead of fabricating a world.
Walkthrough
- Open /diorama.
- Type a sentence:
a lighthouse on a rocky islet at dusk, ora cozy campsite in a pine clearing. - Watch the plan appear as a row of per-object status chips (pending, forging, ready). The island, ground, and mood render immediately from the palette.
- Watch each object drop into place as its mesh finishes forging. A failed object gets a one-tap retry.
- Orbit the finished world. When at least one real mesh is present, the world actions unlock: remix, save, AR (on supported devices), and download.
- Save to get a permalink and a gallery slot, or export to open the merged GLB in Scene Studio.
Examples
Compose a plan, then drive the forge yourself, or let the server build the whole thing.
# 1) Compose: sentence -> placed plan of single-object forge prompts.
curl -X POST 'https://three.ws/api/diorama' \
-H 'content-type: application/json' \
-d '{"action":"compose","prompt":"a lighthouse on a rocky islet at dusk"}'
# 2) Headless one-shot: compose + forge every object + export a merged GLB.
curl -X POST 'https://three.ws/api/diorama' \
-H 'content-type: application/json' \
-d '{"action":"build","prompt":"a cozy campsite in a pine clearing"}'
# 3) Load a saved world by id.
curl 'https://three.ws/api/diorama?id=<uuid>'
# 4) Browse the public gallery.
curl 'https://three.ws/api/diorama?list=featured&limit=12'
The compose response shape (abridged). The plan always arrives under a
diorama key, and every read (?id=, the save and build actions) returns that
same object, so one renderer handles all of them. id and createdAt are empty
until the world is saved:
{
"diorama": {
"id": "",
"prompt": "a lighthouse on a rocky islet at dusk",
"title": "Lonely Beacon Watch",
"mood": "dusk",
"ground": "stone",
"island": "craggy",
"palette": { "sky": ["#2e3a59", "#d67850"], "ground": "#4a4a4a", "fog": "#332d40", "accent": "#ffcc00" },
"objects": [
{ "id": "obj-0", "label": "lighthouse", "prompt": "tall lighthouse made of weathered white brick with a glass lantern room", "position": [0, 0, 0], "scale": 2.2, "rotationY": 0, "status": "pending", "glbUrl": null },
{ "id": "obj-1", "label": "boulder", "prompt": "jagged grey granite boulder with lichen patches", "position": [3.5, 0, 2], "scale": 1.2, "rotationY": 0.5, "status": "pending", "glbUrl": null }
],
"author": null,
"createdAt": "",
"views": 0,
"featured": false
}
}
States and limits
- Object count is bounded (the plan enforces a minimum and maximum), and objects are spaced so they never stack.
- Compose failure: a clean 503 and a designed retry state, never a fabricated world.
- Per-object status: pending, forging, ready, failed (with in-place retry). One failed object does not block the rest.
- Save/export need object storage configured; export returns 503 with a clear message when it is not.
- AR and download appear only once at least one real mesh has forged.
- Deep links render a saved world read-only and offer a remix, so a shared permalink is stable.
- Prompt length is capped; reads are rate-limited per client IP.