Pixel dioramas

Pixel dioramas

Polished isometric pixel-art places for a browser game: describe a ground, place boxes, spheres, trees and people, and get hue-shifted light, dither, hard shadows and wind. It's Amir Mushich's Pixel Plays, with his five small games to play.

The renderer, the look and all five games are the work of Amir Mushich: Pixel Plays, MIT, © 2026 Amir Mushich. Concept by abhi, game by AmirMushich. Go and play the originals, with their music. The style itself is his too, and his README credits its visual reference: shawn.'s Small plays, with "no assets or subjects copied". Patch only tidied his engine into something you can call, and added a sun you can turn, a wind strength and times of day.

It's its own small renderer, not a post effect. It draws into a low-resolution picture of its own on a plain 2D canvas, with no WebGL. It can't draw into a three.js game or restyle one: a whole game has to be drawn with it. Its camera is one fixed 30-degree view, and the world doesn't scroll. That suits one small place at a time.

Make a diorama

Copy engine/diorama.js into your game. It's one file with no dependencies.

<div style="position: fixed; inset: 0; background: #fff"><canvas id="c" style="position: absolute; image-rendering: pixelated"></canvas></div>

import { createDiorama, fitCanvas, hash, noise, rampOf, rgb, clamp, KIND_GRASS, GRASS } from './engine/diorama.js';

const canvas = document.getElementById('c');
const d = createDiorama(canvas, { originY: 20, shadowX: 1.1, shadowY: -.3 });

// 1. The ground: a colour for each pixel, or 0 for nothing. Keep tones close, and wear the edge away into the white.
d.paintGround((x, y, ix, iy, i) => {
  const edge = Math.hypot(x / 14, y / 9) + (noise(x * 1.3, y * 1.3) - .5) * .13;
  if (edge > 1.04 || (edge > .93 && hash(ix, iy) < (edge - .93) / .11)) return 0;
  d.kinds[i] = KIND_GRASS; // grass grows tufts that sway
  const t = noise(x * .9, y * .9) * 1.15 + (hash(ix, iy) - .5) * .55 - .08;
  return rgb(...GRASS[clamp(Math.floor(t * 4.2), 0, 3)]);
});

// 2. What stands still. Draw as much as you like: it's baked once and costs nothing per frame.
d.box(-3, -5, 0, 1, -2, 2.4, [214, 196, 160], 1);  // x0 y0 z0 x1 y1 z1, a colour, a seed for its grain
d.sphere(3, 2, .3, .7, [216, 206, 184], 'rough');  // a boulder
d.tree(-7, 2, .8, 300);                            // x, y, scale, leaves
for (let x = -3; x <= 1; x += .5) for (let y = -5; y <= -2; y += .5) for (let z = .3; z <= 2.4; z += .7) d.castShadow(x, y, z, .55);
d.castShadow(3, 2, .4, .7);
d.finishBake();

// 3. Scale it up with sharp pixels, on the box around what you drew.
fitCanvas(canvas, { x: 0, y: 0, width: innerWidth, height: innerHeight }, d.contentBox());

// 4. Every frame: what moves goes in objects. Grass, leaves, shadows and edges happen by themselves.
const person = { shirt: [188, 60, 44], stripe: [240, 232, 214], legs: [48, 47, 58], hair: [38, 28, 24], skin: [222, 170, 132] };
function frame(ms) {
  const time = ms / 1000;
  d.render({
    time,
    objects() {
      d.figure(4 + Math.sin(time) * 2, 4, 0, { armR: .2, stance: .15 }, person);
      d.sphere(1, 5, .3, .3, [232, 200, 62], 'gloss');
      d.castShadow(1, 5, 0, .3, 2, 0);
    },
  });
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

World units: x runs down and to the right, y down and to the left, z up. A person is about 2.8 tall, and one unit is 10 pixels across. The default picture is 360 x 280 and shows about 30 units across.

The light comes from the far left: on a box, the top is brightest, the +y face (towards you on the left) is in between and the +x face (towards you on the right) is darkest. Keep the same order on surfaces you plot yourself.

What to call

Keeping the look

These are Amir's rules, from his README. They are most of why it looks the way it does:

• One small place floating on pure white, with no interface around it.
• Long, hard shadows, all falling the same way. One readable physical action per game.
• Large flat surfaces use closely spaced tones: wide steps make the dither read as a checkerboard. See SAND_TONES in games/balote.js and CLAY_TONES in games/tie-break.js.
• Colours should come from rampOf, so shadows drift to violet and lights to warm yellow.
• Characters stay sharp: flat bands with no dither, and patterns at least 3 pixels wide.
• Motion stays in the plants, in whole pixels at 8 frames a second. It stops for people who ask their system for reduced motion.

The five games are worked examples

Each is one file you can read top to bottom, with the same shape: constants, groundColor, a bake, a game state G, then update and draw.

To start something new, copy games/balote.js, and replace its groundColor, its bake and then its rules. demo.js shows the loop around a game: sharp scaling, input, and pausing when it can't be seen.

There's no wedge or roof primitive: make slopes by plot in two loops, as roof in games/stari-most.js does. examples/campsite/ is a plain diorama with no game, about 100 lines: a tent, a fire and a person. An agent made it from this README as a test of it, on its first try.

How much it costs

About 1 to 2 ms a frame on a fast PC, on one CPU core. A bake is about 30 ms, plus some the first time the browser runs it. The JavaScript is 90 KB (38 KB gzipped), with no images. A bigger picture costs more: it's every pixel, every frame. It runs on any graphics card, since it doesn't use one.

What you can't do

• Draw into three.js, or be a post effect in one. A shader with the same colour steps, dither and edges would be different work.
• Move the camera. It's a fixed 30-degree view, and the bake is one picture.
• Light things fully from a new side. setSun swings every shadow and turns the light on figures and other moving things, but what's baked keeps its shading.

The demo

Pick a game on the page and play it right there. Each shows its controls in one small line, and Reset or Restart starts it over. Picking a game always starts it fresh.

For people (the block page shows these):

Trigger: Restart (restart): starts this game again from the beginning.

For agents (in recipe.json with every range and default):

What Patch changed in the games: the storm in Rooftop Laundry waits for your first touch, so opening it never starts with lost washing. A Balote turn can't wait for ever on a ball balanced on another. The wind control reaches the diver and the laundry. Everything else, rules and numbers, is Amir's. His background music is left out (see below), so the demo has only the sound effects.

Build it

npm install
npm run build        # recipe.json, then dist/: the demo exactly as released, index.html at the top

Credits and licences

• Amir Mushich: Pixel Plays, at commit 0c2a70f, MIT. The renderer, the look and the five games. Keep the notice in LICENSE, and his credit line: "Concept by abhi / Game by AmirMushich".
• Patch: the tidy, the demo, the sun, wind and times of day, and the pictures, MIT.

Code: MIT (LICENSE). Art: there are no art files: everything is drawn by code, so it's MIT too. The music is not included and not MIT. Pixel Plays' five tracks were generated with Suno and aren't licensed for reuse outside that project, so they aren't in this repo or its history. Add your own if you want music. Details are in LICENCE-NOTES.md.