Diorama Kits

---
name: diorama-kits
description: Build scenery, gear, effects and item icons as catalog-driven kits in Diorama — start a kit with `new-kit`, add pieces to its family files and catalog, generate the sheets with `scenery-items`, `gear-items`, `vfx-items` and `item-icons`, check the joins, the scale and the fit, and make scenes and outfits from them. Use when a project needs a set of related pieces that editors, scenes or characters share, in any genre and look; a one-off prop is diorama-volume.
---

# Kits: scenery, gear, effects and items

A kit describes a set of related assets as data. Four exist: **scenery** (floors, walls, fences, doors, props, decals, and the scenes laid out from them), **gear** (equipment parts and the characters that wear them), **vfx** (effects) and **items** (inventory items and their icons). They share one shape and one workflow, and the rules that are easiest to break are the same in all four. Read `diorama` first, and `diorama-style` if the project has no theme or space profile yet.

## The shape of a kit

A kit is a folder of `src/`:

| File | It is | Read by |
| :--- | :--- | :--- |
| `catalog.ts` | One entry per piece: ids, labels, groups, options with defaults, sizes, material roles | editors (the viewer, an agent) and the generator command |
| `index.ts` | Re-exports the pieces other code needs, so code writes `../gear` and not a path inside the kit | other code (characters, scenes, sheets) |
| family files (`floors.ts`, `walls.ts`, `heads.ts`, `bursts.ts`, `gems.ts`...) | The pieces, grouped by family, one concept per file | `catalog.ts` and `index.ts` |

| Kit | Catalog export | Generator | Writes | First piece of `new-kit` |
| :--- | :--- | :--- | :--- | :--- |
| scenery | `SCENERY` | `scenery-items` | `sheets/scenery/` | a crate prop (`props.ts`) |
| gear | `CATALOG` and `CHARACTERS` | `gear-items` | `sheets/gear/` | a helm (`heads.ts`) and a mannequin body (`bodies.ts`) |
| vfx | `VFX` | `vfx-items` | `sheets/vfx/` | a spark burst (`bursts.ts`) |
| items | `ITEMS` | `item-icons` | `sheets/icons/` | a gem with two rarity tiers (`gems.ts`) |

The generator writes one sheet per catalog entry (scenery: also one per extra state and per clip), each starting with a `Generated by` line. **A generated sheet is never edited.** To change one, change the catalog and run the generator with `--force`; without it, existing sheets are kept. Then export that folder. A scenery piece that already has its own sheet (a hand-written prop) says so in its entry (`asset`).

## Process

1. **Prerequisites.** The theme declares `CAMERA` and `VOLUMES` (`new-kit` says what is missing). A scenery kit, and any piece sized against a character, should use a space profile (`src/space.ts`, [volume guide 04 §1](../../../docs/guides/volume/04-scenery-kits.md#1-the-space-profile)); the kits use it when the project has one. The gear kit's `CHARACTERS` lists the characters that can be dressed.
2. **Start the kit** with `npm run new-kit -- <project> scenery|gear|vfx|items`. It writes `catalog.ts`, `index.ts` and the first piece, drawn with the theme and sized by the space profile, so the generator, the export and `npm run check -- <project> --strict` pass on it at once. It is a block-out to make the project's own. It refuses to overwrite a kit: `--force` rewrites the kit's own files, so never use it on a kit that already holds your pieces.
3. **Add a piece.** Draw it in the family file, add its entry to the catalog in the same change, then run the generator and export the folder:

   ```bash
   npm run scenery-items -- my-game
   npm run export -- my-game scenery/
   ```

   What an entry needs, per kit:
   - **scenery** (`ScenePieceInfo`, [volume guide 04 §5](../../../docs/guides/volume/04-scenery-kits.md#5-the-catalog-and-exports)): id, label, group (`floor`, `wall`, `fence`, `prop`, `decal`, `door`), connection, variants with one `variantLabel` each, footprint and facings, true roles and options with defaults, a `height` so `inspect` can check the scale, and a `cell` when the piece needs more room. Pieces with states and clips: [guide 05](../../../docs/guides/volume/05-living-scenery.md).
   - **gear** (`PartInfo`, [rig guide 05 §5](../../../docs/guides/rig/05-gear-and-outfits.md)): id, label, group, the slots it fits, the roles it reads, every option with its default, `requires` for add-ons, `kind` and `equip`. A part that is held also says how (`wield`); that is in the guide.
   - **vfx** (`EffectInfo`, [volume guide 06 §1](../../../docs/guides/volume/06-effects-items-and-hud.md)): `kind`, frames and fps, `events`, `size`, `height`, `layer`, `directions`, and for a projectile `travel` and `follows`.
   - **items** (`ItemInfo`, [volume guide 06 §2](../../../docs/guides/volume/06-effects-items-and-hud.md)): id, label, kind, rarity, stack, and the gear part it equips or the piece drawn for its icon; the catalog sets the rarities, the icon square and the frame.
4. **Make things from the kit.**
   - A scene (`SceneData`, saved by the viewer's Scenery tab or written as JSON): `npm run new-scene -- <project> <name> --scene <file.json>` validates it against the catalog and writes `src/scenes/<name>.ts` and its sheet; then export `scenes/`.
   - An outfit (`OutfitData`, saved by the viewer's Customize tab): `npm run new-outfit-character -- <project> <name> --from <character> --outfit <file.json>` writes a character that wears it; then export `characters/<name>/`.
   - A character that cues an effect names it in `defineCharacter({ effects })` (volume guide 06 §1.1).

## Rules

- **Material roles, not `VOLUMES`.** A piece reads `ctx.materials.<role>` and never imports `VOLUMES` or palette colors, so the kit can be re-materialed. The roles are the kit's own vocabulary, listed in its `index.ts` and mapped to theme materials in the catalog (`defaultMaterials`). Add a role when no existing one plays the material.
- **Sizes come from the space profile.** Read `SPACE.scale` (`character`, `cell`, `wall`, `door`, `fence`) and `SPACE.grid`; change a proportion in `src/space.ts`, never piece by piece.
- **The catalog and the code move together.** An option missing from the entry cannot be edited, a wrong default changes saved scenes and outfits, and a role the entry does not list cannot be re-materialed. Update the entry whenever the piece changes.
- **One concept per file, kebab-case, no underscores.** `npm run check -- <project>` reports a `catalog.ts` without an `index.ts`.
- **Deterministic.** Variation comes from the frame's seed (`pieceRng(ctx)` for scenery, `effectRng(ctx, salt)` for effects), never `Math.random`.
- **A piece draws one frame, never one place** (scenery): it is built at the world origin, so a frame looks the same in its sheet, in a scene, in the editor and in a game. Variation between placements is a variant.
- **Not a kit piece:** a one-off prop is `npm run new-asset` (`diorama-volume`); a HUD piece is written by hand in `src/ui/` with a one-line sheet; a character is `diorama-rig`.

## Checks that must pass

1. `npm run check -- <project> --strict` after the export: types, layout, determinism, every sheet exported.
2. The generator accepted the catalog (the scenery, effect and item generators validate it and refuse one with problems), and `inspect` is clean on each exported sheet or each warning is explained (an `off scale` warning means the piece or its `height` is wrong).
3. **Scenery:** `npm run scenery-test -- <project> <piece>` through every join, zoomed at 3×; `--field` for a floor alone (no lattice, no repeated motif at 1×), `--on <floor>` for what it stands on; walls and fences join at every mask and keep their height at cell borders; the piece is judged next to the scale figure and in the viewer's Scenery tab, painted into a scene. Floors read calmer than the actors.
4. **Gear:** every part reads in all 8 facings, on both sides, during a twist, a pitch and lying down; the viewer's Customize tab swaps each slot without a piece showing through the body; `new-outfit-character` produces a character that exports.
5. **Effects:** a one-shot ends empty, a loop closes, events sit on the frame a game reacts on, a projectile has travel and an impact; the effect's Details window shows its size ring and flight, and the character that cues it plays it in the Playground at its socket.
6. **Items:** every icon fills its square the same way and reads at 1×; rarity shows in the frame, not in the item; the Details window of an icon shows the inventory.

## Reporting

Report the pieces added with their catalog entries, the generator commands run, the exported folders, and each check with its result.