diorama-pixel

Diorama Pixel: a pixel-art miniature that moves

You are making one small place, a stall, a pier, a garden plot or a doorway, seen from a fixed isometric camera and drawn as pixel art: the whole frame is rendered at 320 x 240 and enlarged with nearest-neighbour pixels, every surface is quantized to a short ramp of muted colours through an 8 x 8 Bayer matrix, the materials carry procedural texture (plank lines, thatch streaks, stones, stippled grass, blotchy water), the ground's edge dissolves into the white page, the sun throws soft shadows, and one or two tiny people do one clear thing in a loop. The three scenes in examples/ are the bar, and they are in the format you will write.

This skill is one of three. diorama draws vector SVG illustrations (UI scenes, line art, empty states, themes); diorama-worlds renders detailed Three.js worlds with articulated people and four finishes. Use this one when the person wants pixels, dithering, a retro or 16-bit feel, or a pixel scene that must stay small and dependency-free.

You write one thing: the scene, a .js file. The kernel (kit/pixel.js) and the page (kit/page.html) are fixed. Never edit them, never paste a changed copy, and never write again what the kernel gives you (the camera, the light, shadows, textures, dithering, the ground, a person rig, trees and bushes, a clock that sleeps offscreen, the pointer).

Every file named below is in this skill's folder. Write the scene and the built page in the person's working directory, and run the scripts from there by their path in this folder.

1. Concept

Write the concept in one line before any code:

Name. The place and what is in it. The one action a person does, and what else moves. What the pointer and a tap do.

Pick a place with a story and a use: a market stall, a jetty, a bakery door, an allotment, a bus stop, a rooftop garden. One action carries the scene (tying a bouquet, fishing, watering, kneading), with anticipation and a pause, and two or three quiet loops around it (cloth, water, leaves, a flag). Then write the parts list in four lines: ground (zones: grass, paving, water, sand, soil, a path), structure (what stands: a stall, a shed, a fence), people (who, where, facing where, doing what), life (what sways, bobs or shimmers). A scene runs to 10–25 objects. If the list reads thin, the scene will too.

Offer two or three concepts when there is someone to ask, and wait. If there is nobody to ask, take the one with the strongest still frame and say which.

2. Build

1. Read references/art-direction.md: palette, materials, dithering, the ground edge, the scale of people, what makes a frame read as a pixel miniature rather than a blurry render.
2. Read references/scene-api.md: every primitive, material, helper and the tick contract. Do not read kit/pixel.js below its index comment.
3. Read the nearest example: examples/flower-stall.js (paving and grass, a striped awning, two people, a pennant), examples/pier.js (water and a shore, a seated person with a rod, a boat, a thatched shed) or examples/allotment.js (soil, a brick path, raised beds, a gardener watering, a scarecrow).
4. Write <name>.js: one Pixel.scene({ … }) with name, title, means (one sentence, at most 140 characters), hint (what to hover, what to tap), duration, still, ground, optional materials, build(P) returning parts (with parts.hot, each hot group named) and tick(ctx) posing everything from ctx.t / ctx.q.
5. Build: node <skill>/scripts/build.mjs <name>.js writes pixel-<name>.html, one self-contained page with no network request.

3. Check

1. node <skill>/scripts/validate.mjs <name>.js pixel-<name>.html: the declaration, the clock, self-containment, no URLs, the kernel byte for byte, the size budget and the pointer. Fix every FAIL.
2. npm ci --ignore-scripts --prefix <skill> once, then node <skill>/scripts/look.mjs <name>.js <outdir>. It opens the page in headless Chromium with the network blocked and writes <name>-look.json, the still, four moments of the loop, the hover, the press and a mobile view, and checks fill, motion, the loop seam, picking, hover, press, reduced motion, frame cost and mobile overflow. Frame cost is judged against the scene's frame budget (41.7 ms at 24 fps); --throttle 4 looks at it on a CPU four times slower, as a CI runner or a phone. CHROME_PATH selects a browser; otherwise it uses an installed Chrome or Chromium.
3. Open the PNGs and look. Passing checks do not make a picture. Ask of the still: does the action read at this size (hands, the tool, the thing being worked on)? Is anyone hidden behind a post or a roof? Does every surface show its material? Does the ground fade into the page on every side, with nothing cut by the frame? Are the shadows on the ground where the sun says? Then fix the scene, not the kernel, and look again.

Do not hand over a page the validator rejects. Do not claim the look is done if you did not open the images. Without a browser, say so plainly and hand over with the look unverified.

4. Hand over

Give pixel-<name>.html the way the person asked (the file, or an artifact if you can publish one). Then, one line each: the concept; the still second and why; the size (about 50 KB, no dependency); how to embed it (references/scene-api.md, "Embedding": a <canvas>, the kernel and the scene in two <script> tags and Pixel.mount, or the React component there); anything you could not verify.

5. Adjust

When the person asks for a change, edit only <name>.js, build, validate and look again.

What goes wrong

If you catch yourself	Do this instead
reaching for three.js, WebGL or an image file	there is none: the kernel rasterizes solids on a 2D canvas; use P.box, P.cyl, P.ball, P.wedge, P.line
writing requestAnimationFrame, setTimeout or Math.random	pose everything from ctx.t / ctx.q in tick; use P.hash(i, j) for variety that stays put
position.x += speed * dt	a position from P.phase(t, period), so the still frame and the loop seam are exact
a person hidden behind a counter, a post or a roof	move them, lower the counter, raise the roof: the camera is fixed and they are the story
arms that read as one blob with the body	a pose with the forearms out (P.pose(p, 'work' / 'hold')), the hands holding something with a colour of its own
a tree as one big ball	P.tree and P.bush: clusters of round-shaded leaf clumps
a flat colour on a big surface	a textured material: 'wood', 'thatch', 'stone', 'paving', 'leaf', 'cloth', or a ramp with tex
a hard edge where the ground ends	the ground is ground: { rx, rz, wobble, fade }: it already dissolves; never add a slab or a plinth
a scene wider than its ground	keep everything inside rx and rz; the frame fits the ground
more than 480 px of internal width	320 x 240 is the look; more pixels look like a render, not pixel art
editing kit/pixel.js to make a scene work	the scene is wrong; change the scene

References

• references/scene-api.md: the declaration, P (primitives, materials, people, poses, trees, noise), the tick context and the pointer, the runtime and embedding.
• references/art-direction.md: palette and ramps, materials and textures, dithering, the ground edge, light and shadow, people at pixel scale, composition.