edenfunf / pixel-art

Pixel art engine

Every frame is a pure function of t. Shots draw into a 480×270 software framebuffer (world unit = one art
pixel), ENGINE.end upscales it ×4 to 1920×1080 with nearest-neighbour, and window.overlayHook draws crisp pixel
captions on top at full res. Same render contract and render.mjs CLI as painted-animation.

Workflow

1. Scaffold: bash .claude/skills/pixel-art/scripts/new_project.sh <project-dir> [--keep-demo], then **read
   GUIDE.md in full** (look rules, full API, character system, review loop). Look at docs/model-faces.png,
   docs/model-views.png, docs/kit-sheet.png, docs/demo-sheet.jpg.

2. Storyboard with reads per shot (as in painted-animation). Pick a palette per shot (pal('day'|'dusk'|'night'))
   and a colour arc.

3. Build one file per shot in src/scenes/, IIFE-wrapped, ending with shots([[t0, fn], ...]); add a <script> in
   studio.html (replace the demo). Scenes call only the library + cast; never redraw a character's body.

4. Review every shot (sheet, strips of every action and transition, crops of faces), fix, repeat:
   `bash
   node render.mjs --sheet=0.5,1,1.5,2 --cols=4 --w=480 --out=out/check/a.jpg
   node render.mjs --strip=3.3:4.3 --cols=6 --w=320 --out=out/check/jump.jpg
   node render.mjs --sheet=4.5 --crop=780,380,700,560 --w=700 --out=out/check/face.jpg
   node render.mjs --loop=faces --stills=0.5 --out=out/sheets # model sheets: faces | views | kit | wipes
   `

5. Render: node render.mjs --frames --workers=4 && node render.mjs --encode --out=out/video.mp4 [--audio=...].

API in one screen (details in GUIDE.md)

• Camera/layers: camAt(cx, cy) (snapped), layer(f) parallax, screenSpace(), punch(2, x, y) integer punch-in
  (medium shots), shake(t, amt), clip()/noclip(), measure(fn) (dry-run a draw to get positions).

• Colour: pal(name) → P (ramps: sky cloud far mid grass earth stone wood light sun accent cool, ink paper rim),
  shade(c, ±k) walks the ramp (hue-shifted beyond it), regRamp([...]), dith(x,y,d), qd(d).

• Primitives: px rect line(w) pline curve disc oval ring poly ball sprite(rows,map,x,y) tile tilemap tinyText,
  all with optional dither density d. Outlines: beginSpr(); part(); … endSpr({tint,z,flash}) or outlined(fn).

• World: sky sunDisc stars clouds hills forest city ground tree bush; light: glow light shadowAt vignette;
  weather/fx: rain snow sparkles fireflies birds petals puff; emote(kind, x, y, {age}).

• Transitions (call last, screen space): dissolve(k), iris(k, x, y, {shape}), diamonds(k, {dir}),
  blocks(k, {dir}), crossDither(k, drawA, drawB).

• Captions (overlay): say(c, t, t0, t1, text, { name }) RPG box + typewriter; pxText(c, text, x, y);
  declare strings with useText('…') at load.

• Cast: pip(x, y, o) (round, 40 px), juno(x, y, o) (tall, 65 px); `o = { t, face, view, flip, look, sq, dy, arm,
  bend, hold, walk, air, drag, wind, emote, emoteAge, emoteSide, tint, z }→{ head, top, hands, face }`.
  act(t, keys) acted expression changes, walkTo() foot-planted walks, st(t) 12 fps sprite time, vel(f, t),
  PROP.kite/spool/lantern/flower/balloon/mug/letter/star/umbrella, ARM.down/low/out/up/high, footShadow().

Rules that matter most

1. Pixel discipline. Everything goes through the library (it snaps to whole art pixels). Never draw with G/Canvas
   paths, never scale by non-integers, no anti-aliasing, no gradients except dithered ones, colours from P/CR ramps.

2. Motion on steps: poses, walk frames, blinks, weather use st(t) (12 fps); positions and camera may move every
   frame (snapped). Squash/stretch, jump anticipation, follow-through (drag via vel) as in any cartoon.

3. Big enough to read: wide shots at 1× for establishing; do the acting in punch(2) medium shots (characters
   ≈ half the frame height). Cut to a punch on an action or a take, never mid-stillness.

4. Transitions at every seam — dither dissolve in/out, diamond wipe, iris, blocks; wipe-in direction continues the
   wipe-out direction.

5. Text only via the overlay caption box (one line at a time, typewriter), or tinyText for in-world signs/SFX.

Engine gotchas

• Don't declare globals that clash with kit.js or pixel.js names (W H G P C st px rect line …): wrap scenes in IIFEs.
• act(...) overrides use 'emote' in over, so { emote: null } removes an expression's default emote.
• Transitions/punch are post-effects on the low-res buffer: call punch() before transitions in the shot.

• Held props: draw via hold: [fnBack, fnFront] so they join the character outline; in side view an arm raised above
  ~0.6 rad crosses the face — do reaches in front view (hands go beside the head).

• The dialogue caption box sits over the bottom ~20 % of frame: keep feet/props above it while it's up.
• Speed: 3–40 ms/frame; a full 10 s demo renders in ~10 s with 4 workers.