A skill to make pixel-art Gaussian splat dioramas: model a scene as SDFs, render stills, look, refine, and film it.

GitHub stars
5

Install

/plugin install pixel-splats@pixel-splats

Run it inside Claude Code after adding the marketplace with /plugin marketplace add patch-gg/pixel-splats.

Contents

Discovered from source

Skills 1

pixel splats

Everything lives in index.html: the SDF library, the splat sampler, the scenes, the WebGL2 renderer and the pixel pass. No build step and no packages. A diorama is one object pushed onto SCENES inside <script id="shared">; the page builds its splats in a web worker in about half a second and renders it live.

The API is in REFERENCE.md. Read it before writing a scene.

The loop

You can't judge a diorama from its code. Render it, look at it, fix the worst thing, render again.

  1. Pick the idea. One hero with a silhouette that reads at about 200 px tall, on a round base about 2 units across, one palette family with one or two accents, and one thing that moves (a beam, a chomp, fish, a flame, breathing).

  2. Start from the closest scene. Copy its (() => { ... SCENES.push({...}); })(); block, give it a new name and seed, and add the name to ORDER (near the end of the shared script) where it should sit in the line-up.

  3. Build in this order: the base, the hero, the details, the effects, then lights, camera and palette.

  4. Render stills (needs Node 22+ and Chrome; it serves the folder itself):

    node tools/shot.mjs <name> --angles 3                 # three views around it, 4x, in out/shots/
    node tools/shot.mjs <name> --crop 150,40,90,70        # canvas pixels from the top left, at 6x
    node tools/shot.mjs <name> --mode clay --size 768x432 --scale 1   # the shapes alone, no colour
    

    Open every PNG and look. The camera orbits, so the back of the scene is seen as often as the front.

  5. Fix the worst thing first, render again, and repeat until it reads at a glance from all three angles.

  6. Film it when it's done (needs ffmpeg): node tools/film.mjs <name> --seconds 8, or --out out/<name>.gif.

Open the page with python3 -m http.server and http://localhost:8000/#<name> to see it live; P turns the pixel pass off.

What makes it look right

These came from building the five scenes, each one learned the hard way.

  • Fill the frame. At the scene's own camera the diorama should take about three quarters of the frame's height. Set cam.dist (about 3.2 to 4.6) and cam.target until it does.
  • Silhouettes first. At 216 px tall a hero is 60 to 120 px. A sleeping, curled-up fox was an orange blob; the same fox sitting up with big ears reads at once. Exaggerate ears, horns, teeth and eyes, scale heroes up, and pose them so their outline says what they are.
  • Hand-made palettes. 3 to 5 ramps of 4 to 9 colours, dark to light, hue-shifted (shadows cooler, lights warmer), plus the background and halo colours, 48 at most. Every material should land on a ramp. The pixel pass picks the nearest palette colour and the one that best brackets the pixel, then dithers between them. If a soft gradient passes through a wrong colour (a yellow beam over navy got a green fringe), add the in-between colours of the right hue or change the light's colour. Don't add generic greys.
  • Dithering. Sky and glows dither freely (lam, default 0.15). Surfaces get only flat colour or a 50% checker (lamS, default 3; lower it for more texture). Busy diamond patterns on a surface mean its colour sits between two palette colours: move the material's colour or add a palette step.
  • Speckle is the texture. Per-splat jitter (jit 0.12 to 0.25) and large mottling (pat) make the painterly clusters. Above about 0.2, big flat areas such as grass turn noisy: lower jit and raise pat.
  • Keep emissive low on lit things. Crystals at emis 0.1 to 0.2 still show their facets; at 0.5 they flatten into one pink shape. Save high values for lamps, eyes, embers and fire.
  • Thin parts need density. Rails, teeth, reeds, ears and pupils thinner than the splat spacing break up: give them density: 1.6 to 3.
  • Water is a ghost, two-sided, noG disc at about 0.08 opacity a splat, so the fish under it still show and the outline pass ignores it.
  • Beams are glow splats with a dir (use A.beam). They fade when they point at the camera, so a head-on sweep is a flash, not a blob.
  • Particles are hard pixels. Fireflies and rain always are; rise takes hard: 1. Sizes of 0.005 to 0.006 give 1 to 2 px sparkles. Fire is a rise of kind: 5 flames, a glow, hard embers and a point light with fl flicker.
  • Outlines darken a pixel on the near side of a depth edge (outline, default 0.38). Separate parts at different depths get them for free; parts that touch don't.

Pitfalls

  • A part has holes: its SDF isn't a true distance (displacement, smooth unions). Raise lip to 1.5 to 1.7.
  • A part is missing: its splats are buried inside another part and get dropped. Move it out, or make the other part a ghost.
  • Everything moved after a small edit: the scene's random stream (A.R()) is shared, so adding or removing a call reshuffles everything after it. Keep the seed and re-check all angles.
  • Animated parts look wrong from behind: ambient occlusion and the material are baked at the rest pose; keep deformations small, or move whole groups with G.pose.
  • Slow to build: keep a scene under a few hundred parts and about 80,000 splats; coarser h (0.02) halves the count.
  • A new scene appears first: its name isn't in ORDER.

Sponsors

Details

Marketplace
patch-gg/pixel-splats
Category
Gamedev