Diorama Worlds guide

Install

npx skills add educlopez/diorama --skill diorama-worlds -g

--skill diorama-worlds selects Worlds; the SVG skill is --skill diorama. Both live under skills/ in the same repository. Add -a claude-code or -a codex to target one agent. Omit -g for a project-local install. The install CLI may require a newer Node version than the build tools; check its current requirements.

Node.js 20+ runs the build/check scripts. Chrome or Chromium runs browser checks; WebGL 2 is required to display the finished scene. Your agent reads the installed skill and runs npm ci --ignore-scripts --prefix <skill-folder> once. No API keys, model downloads or CDN imports.

Ask for a world

/diorama-worlds a miniature bakery for our landing page. A baker rolls dough beside a brick oven. Flat irregular ground, no platform. Halftone finish.

In agents without slash commands, ask “Use the diorama-worlds skill…” instead. Name the setting, one main action, where it will live and the finish. The agent builds the scene and inspects the actual output, including hand/prop contacts and mobile framing.

Four live finishes

Finish	What changes
miniature	Matte low-poly geometry, generated surface detail and contact shadows.
pixel	Low-resolution rendering, nearest-neighbour enlargement and ordered dithering. Not voxels or hand-drawn sprites.
halftone	Warm/cool ink dots over ivory paper, masked to the scene silhouette.
blueprint	Blue planes, pale screen-space edges and a subtle grid. A graphic treatment, not CAD.

All four preserve the same people, props and clock. The camera stays fixed. Ground is a flat, irregular cutout by default; an extruded display base is opt-in only.

Build and check

node <skill-folder>/scripts/build-world.mjs bakery.js world-bakery.html
node <skill-folder>/scripts/look-world.mjs bakery.js work/bakery-check

The scene imports defineWorld from @diorama/worlds; the builder resolves that alias. Browser checks render all four finishes, multiple phases and mobile views, and inspect contacts, loop seams, clock speed, reduced motion, cleanup and WebGL fallback. Open the saved images too: metrics do not judge artistic quality.

Embed

<iframe
  src="/world-bakery.html?embed&finish=halftone"
  title="A baker rolling dough in a miniature bakery"
  style="width:100%;aspect-ratio:4/3;border:0"
></iframe>

?embed hides standalone controls. Provide equivalent host pause/finish controls, or omit it to keep the built-in controls. Same-origin parents can use the validated message bridge; full examples and the React mount/dispose contract live in the scene API reference. Never mount a browser scene during server rendering.

Know the tradeoffs

A standalone file is about 0.77 MB uncompressed, including Three.js, geometry and generated textures. No runtime network connection is needed. Reduced motion shows the declared still; hidden/offscreen scenes sleep. Missing WebGL shows a readable fallback; the site also supplies a real poster.

These are stylized scenes, not anatomy, clay, ink or optical simulations. Fine face/foliage details can merge on mobile, and screen-space effects do not stick to surfaces. Performance has not been certified across physical phones. For lightweight UI illustrations without WebGL, use Diorama SVG.

Read the Worlds skill source