Diorama

# Diorama

Gives an AI agent a playbook and code to copy in for building detailed Three.js dioramas, tiny staged scenes with a pixel or toon look. For web and creative developers.

Made by sloemo01 on GitHub. These notes are Mindket's, written from its README; the project's own files and license are in its repository.

## About

What it is: Diorama is a written playbook plus code for an AI agent to follow when it builds detailed Three.js dioramas. A diorama here is a miniature staged scene on a slab, with a three-quarter hero camera you can reset and orbit freely. Before it makes anything, the agent asks which of three looks you want and whether models should come from libraries or be built from your own geometry.

Who it suits: It suits developers and creators who want a small, polished 3D scene and are happy to let an AI agent do the building.

```table
Industry | Who uses it | How they use it | Example
Web development | Front-end and creative developers | Build a staged 3D scene for a site or a demo | A swimming pool scene with toy-sized people on a slab
Game prototyping | Indie developers | Sketch a small arena or battle scene | An arena battle with a resettable hero camera
Content creation | Creators of short looping clips | Capture a scene as a loop | A bank job scene captured as a loop of about a minute
Design | Designers who pick a visual style | Choose between pixel, stroked toon, or pixel plus stroke | Ask for stroked toon instead of the pixel default
```

People who want a ready-made 3D model library, or who do not use an AI agent, can skip it.

Where to use it: You use it through an AI agent, and the finished scene runs in a browser.

- An AI agent that can run shell commands, with or without a skills directory
- Your own Three.js project, where the agent copies in the modules it needs
- A browser, where the scene shows a hero camera with free orbit

```table
Use case | Who | What they get back
Build a scene | A web developer | A staged slab scene with a camera, a cast and a chosen look
Choose a look | A designer | Pixel, stroked toon, or pixel plus stroke, with pixel as the default
Source assets | A developer | Licensed assets with hand-built gaps, or models from the internet or made by the agent
Check a frame | A reviewer | Frames that can be frozen, screenshotted and compared
```

How to set it up: You need an agent that can run shell commands and download files.

- An AI agent with a shell and network access
- A folder for the playbook, with ~/skills/diorama as the suggested default
- A Three.js project to build the scene in

1. Paste the install prompt from the project's README into your agent. It asks where to put the folder and waits for your answer.
2. The agent downloads the whole repository, not only SKILL.md. That includes the templates, the QA scripts and the worked examples.
3. It checks that the main files and folders are there and prints the version it installed. If it has no shell or network, it says so and stops.
4. If the agent has a skills directory, it installs the playbook there so later sessions can load it by name.
5. The agent studies the playbook and its templates, then summarizes what it found before building.

```bash
git -C "<target>" rev-parse --short HEAD
```

How to use it: Tell the agent what the first diorama should be. It does not ask you to fill in the design sheet. It researches the subject first, covering frames, assets and motion. It then fills DESIGN.md from the defaults, copies the modules it needs into your project, and builds through the pipeline. A separate update prompt keeps your local edits, fetches the latest main branch and lists the changes, and it does this before it touches any of your projects.

```table
Tool | What it does
SKILL.md | The playbook, and the source of truth for the workflow, the looks, the pipeline, the QA checks and the pitfalls
references/ | The same material split into topic files for long sessions
templates/ | Code to copy into a project, plus the design, sources and credits templates and the QA scripts
verify/ | Worked examples
refs/SOURCES.md and CREDITS.md | The evidence that each asset allows commercial use and redistribution
```

Example: You ask for a night market diorama. The agent researches the subject, fills in the design sheet, copies in the modules it needs and builds the scene. It runs the QA scripts before it shows you anything. You get the paths of the frames it kept and what each one proves.

For newcomers and experts: A diorama here is a small staged scene that you can orbit in a browser. A good first try is to install the kit, choose a simple subject such as a pool, and answer the two questions about the look and the models.

Each frame depends only on the time value t, so you can freeze any frame, take a screenshot and compare it. A screenshot counts as evidence, not a lucky capture. The default sourcing is hybrid, with licensed assets and hand-built gaps. The other options are all from the internet, or all modelled by the agent. SKILL.md stays the source of truth, and the agent copies modules instead of editing the installed copy.

```flow
The agent asks for the look and the model sources
It researches the subject first
It fills DESIGN.md and copies in the modules
It builds through the pipeline
QA scripts run before it shows you frames
```

Good to know:

- The three looks are pixel, stroked toon, and pixel plus stroke, and silence means pixel
- Each asset's license must permit commercial use and redistribution, and the proof goes in refs/SOURCES.md and CREDITS.md
- The agent must prove the install before it describes the playbook
- Four example scenes run from 26 to 48 seconds
- The README lists the skill at version 5.7.0 and three.js at r170

## On GitHub, 7 November 2026

- Stars: 342
- Forks: 23
- Open issues and pull requests: 0
- Language: JavaScript
- License: MIT
- Topics: agent-skill, agent-skill-repository, agent-skills, ai-agents, creative-coding, diorama, game-art, pixel-art, pixelation, procedural-art, procedural-generation, skill

## Links

- Code: https://github.com/sloemo01/diorama
- Releases: https://github.com/sloemo01/diorama/releases
- Issues: https://github.com/sloemo01/diorama/issues
- Star history: https://www.star-history.com/#sloemo01/diorama&Date

## Get the code

```
git clone https://github.com/sloemo01/diorama.git
```

Then follow the setup in its README. Nothing in this kit runs by itself.

README.md  6 KB