
pixel-splats
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-splatsRun it inside Claude Code after adding the marketplace with /plugin marketplace add patch-gg/pixel-splats.
Contents
Discovered from sourceSkills 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.
-
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).
-
Start from the closest scene. Copy its
(() => { ... SCENES.push({...}); })();block, give it a newnameandseed, and add the name toORDER(near the end of the shared script) where it should sit in the line-up. -
Build in this order: the base, the hero, the details, the effects, then lights, camera and palette.
-
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 colourOpen every PNG and look. The camera orbits, so the back of the scene is seen as often as the front.
-
Fix the worst thing first, render again, and repeat until it reads at a glance from all three angles.
-
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) andcam.targetuntil 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 (
jit0.12 to 0.25) and large mottling (pat) make the painterly clusters. Above about 0.2, big flat areas such as grass turn noisy: lowerjitand raisepat. - Keep emissive low on lit things. Crystals at
emis0.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.6to3. - Water is a
ghost,two-sided,noGdisc 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(useA.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;
risetakeshard: 1. Sizes of 0.005 to 0.006 give 1 to 2 px sparkles. Fire is ariseofkind: 5flames, aglow, hard embers and a point light withflflicker. - 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
lipto 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 theseedand 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