@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-art/references/pipeline.md

@@ -0,0 +1,185 @@
+# A re-runnable asset pipeline (optional)
+
+When a game makes more than a handful of assets from text, the games that shipped best kept them
+as data: what each piece is, one style file, and a record of what made each file. Four of our
+games arrived at the same shape on their own.
+`funtools assets` is that shape, on the shelf. Use all of it, part of it, or none: hand-made,
+procedural and one-off `gen` assets need no manifest, and nothing checks for one.
+
+## Why it saves you work
+
+- **Regenerate, never retouch.** A piece re-made from its line comes back in the set's style; a
+  retouched file drifts from the set and cannot be made again. `status` calls a file changed by
+  hand `edited`, so you know which pieces are no longer reproducible.
+- **Only what changed is made.** Each item's request (the composed prompt and its options) is
+  hashed; a changed subject, family clause or `medium` makes that item `stale` and nothing else.
+  The server keys each item by its content too, so a rerun after a crash collects the jobs
+  already paid for instead of paying again.
+- **The spend is on record.** Credits per item and per family live in the lock; `--max-credits`
+  stops a run that would pass your budget, before anything is sent.
+- **A few draws beat most prompt edits.** In our games' notes the best of three or four draws
+  beat most rewordings (on one prompt, a corner spread of 3 against 119). `draws: 3` keeps the
+  first draw the asset gate accepts and saves every draw in `.funtools/assets/draws/<name>/` to
+  look at.
+- **Art becomes data.** `process` writes each picture's size, anchor points and a brightness tint
+  into `src/art/assets.json`, so a regenerated or brighter redraw drops in with no code change.
+
+## The files
+
+`assets/assets.json` (the scaffold ships `assets/assets.example.json` to copy):
+
+```json
+{ "items": [
+  { "name": "hero", "kind": "sprite", "subject": "a round blue slime with a leaf hat",
+    "role": { "h": 96 }, "draws": 3, "atlas": "chars", "anchors": { "hat": [0.5, 0.12] } },
+  { "name": "meadow", "kind": "image", "family": "background", "subject": "a meadow at noon", "depth": "far" },
+  { "name": "hop", "kind": "sound", "subject": "a soft rubbery hop", "variants": ["a", "b"],
+    "params": { "duration_seconds": 0.4 } },
+  { "name": "hero3d", "kind": "model3d", "from": "hero", "params": { "style": "lowpoly" } }
+] }
+```
+
+| Field | Meaning |
+|---|---|
+| `kind` | `image`, `sprite`, `sheet`, `texture`, `strip`, `sound`, `music`, `model3d`; `pose` (an edit of the cast master), `rig` (rig → motions → retarget on a made model), `parts` (cut from a `sheet`, free) |
+| `subject` | the world's words; composed as subject, `medium`, the family's clause, `never` |
+| `prompt` | sent as written, for a piece the style file does not describe |
+| `family` | which clause of `assets/style.json` `families` (default by kind: `sprite`, `tile`, `background`) |
+| `role` | the size it ships at, `{ "h": px }` or `{ "w": px }`; `process` shrinks to it |
+| `draws` | 1–4 candidates for a picture |
+| `atlas` | a group name; `process` packs the group with the local optimizer |
+| `anchors` | named points, fractions of the trimmed picture; `feet`, `center`, `top` are measured |
+| `depth` | `far`, `mid`, `near`: a backdrop plane loses saturation (0.65, 0.75, 0.85) so play reads first |
+| `variants` | takes of one cue: `hop_a`, `hop_b` |
+| `from` | another item whose picture starts this one (a sheet from a sprite, a model from a concept) |
+| `params` | the tool's own fields for sounds, music, sheets and models |
+| `box` | where the game draws it, `{ "w": px, "h": px, "anchor": [x, y] }`; recorded at first land when absent |
+| `references` | the sheets it is drawn to; absent = its kind's default (below), `[]` = none |
+| `cast` | the cast member it is of (`design/cast/<id>/`); absent = the id its name starts with ([cast.md](cast.md)) |
+| `change` | what it may change against the master ("the pose and the expression") |
+
+`.funtools/assets.lock.json` is the record, never shipped: per item the request hash, job and
+asset ids, credits, the file's sha256, the gate's verdict, the kept draw and every earlier version
+(the old files stay in `.funtools/assets/history/`).
+
+## The loop
+
+```
+npx @funpixel/tools assets status          # free and offline: fresh | stale | missing | rejected | edited
+npx @funpixel/tools assets gen --dry-run   # every prompt as it will be sent, and the estimate
+npx @funpixel/tools assets gen             # asks above 50 credits (--yes); --only, --family, --stale narrow it
+npx @funpixel/tools assets regen hero --because "the hat came out on the side"
+npx @funpixel/tools assets process         # key, trim, size by role, desaturate depth, atlas, data
+```
+
+`regen` keeps the reason in the lock and in the style file's `failures`, the place a new constant
+belongs once a failure has a name. A `rejected` item (the gate refused every draw) usually wants a
+changed subject; `gen --only <name>` tries the same words again.
+
+## At scale: the asset script
+
+Our own games carry 70 to 250 assets (one heist game: 116 paintings, 183 sounds, 11 music cues, 25
+models). Nobody calls a tool 200 times by hand. The plan's `## Asset script` is the list, one row
+per family with a count, and it becomes the manifest:
+
+```markdown
+| ID | What | Kind | Count | Cast | Beat it serves | Locks used | Cost | Status |
+|---|---|---|---|---|---|---|---|---|
+| REN | Ren, the hero: idle, step, act, hit, step2 | character | 5 | ren | every screen | REF-REN | | |
+| REN3D | Ren, the hero, walks | model | 1 | ren | the 3D hero | | | |
+| CRATE | a cargo crate | prop | 6 | | the harbour | | | |
+| SFX | footstep on planks; crate thud; bell | sound | 3 | | | | | |
+```
+
+```
+npx @funpixel/tools assets script --write        # rows → items (hand-written items are kept)
+npx @funpixel/tools assets budget 600 --by owner # the owner's credits for them, set at the lock
+npx @funpixel/tools assets gen --dry-run         # every prompt, the estimate, the batches
+npx @funpixel/tools assets gen --yes             # batches of 24, each priced before it is sent
+```
+
+A character row is a pose set (named after the colon, or the role's default), a model row a model
+(a hero's is a bake-off of three, a mover's gets a rig item), prop/structure/icon rows cut-outs,
+place rows pictures. A batch that would pass the budget waits for the next run; a failure mid-run
+leaves its jobs on record, and the rerun collects them instead of paying again. The progress card
+counts made against planned and names any cast picture still off its master.
+
+## Load by relative URL
+
+A game that hard-coded `/assets/…` broke when it was hosted in a subfolder: the leading slash
+points at the domain's root, not the game's. The data file holds relative URLs
+(`assets/sprites/hero.png`), as the scaffold's `src/assets.ts` does; code that builds its own
+paths works in more places when it does the same.
+
+```ts
+import { Assets, Sprite } from 'pixi.js';
+
+// Bundled by Vite without a JSON import setting; empty until `assets process` has run.
+const art = Object.values(import.meta.glob('./art/assets.json', { eager: true, import: 'default' }))[0] as
+  { items: Record<string, { url: string; anchors: Record<string, [number, number]>; tint: number; frame?: string; box?: Box }> } | undefined;
+
+const hero = art?.items.hero;
+if (hero) {
+  const sprite = new Sprite(await Assets.load(hero.url));
+  const fit = fitInBox(sprite.texture.width, sprite.texture.height, hero.box!);   // src/assets.ts
+  sprite.anchor.set(...fit.anchor);          // feet on the position for a character
+  sprite.scale.set(fit.scale);               // the box decides the size, never the picture
+  // tint: a brightness multiplier toward the family's median (0.7–1.35), for a brightness filter.
+}
+```
+
+An atlas item's `url` is the atlas JSON and `frame` its key inside it.
+
+## Same box, same id
+
+A placeholder upgrade or a regen must not move the game. Each picture gets a `box` in the data: the
+manifest's when declared, else its processed size the first time it lands, kept on every re-make.
+Code draws the picture fitted inside its box, so a redraw at 1.3x the pixels lands where the old
+one stood, at the same id. A different shape says so in `process`'s notes; change the box on
+purpose by declaring it.
+
+## Which sheets a picture inherits
+
+A picture that names no `references` is drawn to its kind's default sheets (`REFERENCE_RULE` in
+`assets/manifest.ts`; `status` and `gen --dry-run` name them):
+
+| Picture | Takes by default | Why |
+|---|---|---|
+| a `ref-*` sheet | nothing | drawn from the draft it names |
+| sprite, sheet; character, face, part | its own sheet (`ref-<name>`) only | a world picture redraws a body into scenery |
+| image, strip, texture (background, tile, ui, prop, fx) | its own sheet, then `ref-world*`, `ref-style*`, `ref-place*` | world pieces share one light and palette |
+| `look-*`, poster, key art | the world sheets | the frame names which of the cast is in it |
+
+Named `references` always win; `[]` opts out. A picture made before its default sheet existed is
+kept as made until `regen` draws it to the sheet.
+
+The same rule holds on the hosted path, outside the manifest: pin the sheets on the game once
+(`create_game` with `sheets`, or `generate_batch` with `lock: {style, sheets}`; each sheet an
+`import_asset` id), and every `generate_image` / `generate_sprite` naming the `game_id` (and a `name`, or `cast` for the member outright)
+or batch item with no `references` is drawn to its lane's sheet. A picture drawn to none comes back
+flagged `unlocked`, and the progress card counts them.
+
+## A pixel-art lane (optional)
+
+An image model asked for pixel art draws a large picture whose pixels only look chunky: soft
+edges, hundreds of in-between colours, blocks that drift off any grid. A game that wants real
+pixel art declares it in `funpixel.json`:
+
+```json
+"pixelArt": { "scale": 4, "palette": ["#1a1c2c", "#5d275d", "#b13e53", "#ef7d57", "#ffcd75"] }
+```
+
+`scale` is screen pixels per art pixel; `palette` (optional) is the game's inks. With it, `assets
+process` snaps each picture instead of shrinking it: its role size divided by `scale` gives the art
+pixels, each takes the palette ink most of its source pixels are nearest to, alpha becomes all or
+nothing, and the file is written at `scale` so it ships at its role size. `gen image|sprite|texture`
+snaps what it saves the same way, keeping the original under `.funtools/pixel/raw/`.
+
+`npx @funpixel/tools assets pixels` measures every PNG under `public/assets/` (or the files named):
+grid blocks that are not one colour (fails over 2%), soft-edged pixels (over 1%) and pixels off the
+palette (over 1%, the worst inks named). A part with nothing to measure (no palette, scale 1, an
+empty picture) is not observed, never a pass. `--snap` fixes a hand-made or older file in place.
+Sheets are measured as the server packed them, not snapped.
+
+Draw the art at whole multiples of its size with nearest filtering (Pixi `scaleMode: 'nearest'`,
+Three `NearestFilter`, CSS `image-rendering: pixelated`), or the browser blurs the grid back.

package/plugins/kiro/skills/funpixel-art/references/pixi.md

@@ -0,0 +1,277 @@
+# Pixi 8 effect recipes
+
+Each recipe ran in a scratch scaffold on **pixi.js 8.21.0 + pixi-filters 6.1.5** (`npm i pixi-filters@6`;
+the core-only ones need nothing extra), was captured at 844×390 on a phone viewport and profiled
+with `npx @funpixel/tools profile`. A recipe is a function of the app and the world returning a per-frame
+update. The counts ("measured") come from that run on a desktop GPU; [cost.md](cost.md) has timings.
+
+Shared imports and the two canvas textures the recipes use:
+
+```ts
+import {
+  Application, BlurFilter, ColorMatrixFilter, Container, DisplacementFilter, Filter, GlProgram, Graphics,
+  MeshRope, Particle, ParticleContainer, Point, Sprite, Texture,
+} from 'pixi.js';
+import { AdvancedBloomFilter, GodrayFilter, OutlineFilter, ShockwaveFilter } from 'pixi-filters';
+
+export type Recipe = (app: Application, world: World) => (dt: number, t: number) => void;
+const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+/** A vertical gradient texture from a canvas: cheap skies and fades. */
+export function gradientTexture(stops: Array<[number, string]>, h = 256): Texture {
+  const c = document.createElement('canvas'); c.width = 4; c.height = h;
+  const g = c.getContext('2d')!, lg = g.createLinearGradient(0, 0, 0, h);
+  for (const [at, col] of stops) lg.addColorStop(at, col);
+  g.fillStyle = lg; g.fillRect(0, 0, 4, h);
+  return Texture.from(c);
+}
+
+/** A soft round light: white centre fading to clear. Tint it; blend it 'add'. */
+export function glowTexture(size = 128): Texture {
+  const c = document.createElement('canvas'); c.width = c.height = size;
+  const g = c.getContext('2d')!, r = size / 2;
+  const rg = g.createRadialGradient(r, r, 0, r, r, r);
+  rg.addColorStop(0, 'rgba(255,255,255,1)'); rg.addColorStop(0.35, 'rgba(255,255,255,0.45)'); rg.addColorStop(1, 'rgba(255,255,255,0)');
+  g.fillStyle = rg; g.fillRect(0, 0, size, size);
+  return Texture.from(c);
+}
+```
+
+`World` in the lab is `{ root, sky, far, near, water, hero, lanterns, w, h }`: containers of the place.
+
+## Glow and bloom
+
+1. Glow without a filter: an additive light sprite behind each bright thing. One texture, one batch.
+
+```ts
+export const glow: Recipe = (_app, world) => {
+  const halo = glowTexture();
+  const lights = world.lanterns.children.filter((c) => c instanceof Sprite).map((l) => {
+    const s = new Sprite({ texture: halo, anchor: 0.5, tint: 0xffb347, blendMode: 'add' });
+    s.position.copyFrom(l.position); s.scale.set(1.4);
+    world.lanterns.addChildAt(s, 0);
+    return s;
+  });
+  return (_dt, t) => lights.forEach((s, i) => { s.alpha = 0.55 + 0.25 * Math.sin(t * 2.3 + i); });
+};
+```
+
+Measured: 3 draw calls (base 1), 0.2 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+2. Bloom on the bright layer only (pixi-filters): never on the stage, and at half resolution on phones.
+
+```ts
+export const bloom: Recipe = (_app, world) => {
+  const f = new AdvancedBloomFilter({ threshold: 0.45, bloomScale: 1.2, brightness: 1, blur: 6, quality: 4 });
+  f.resolution = Math.min(devicePixelRatio, 2) / 2;
+  world.lanterns.filters = [f];
+  return () => {};
+};
+```
+
+Measured: 9 draw calls (base 1), 2.1 MB of textures (base 0.1), JS work p95 0.3 ms.
+
+## Outline
+
+3. A readable hero: an outline in the world's ink colour.
+
+```ts
+export const outline: Recipe = (_app, world) => {
+  world.hero.filters = [new OutlineFilter({ thickness: 3, color: 0x1b1330, quality: 0.2 })];
+  return (_dt, t) => { world.hero.y = world.h * 0.8 + Math.sin(t * 3) * 2; };
+};
+```
+
+Measured: 3 draw calls (base 1), 0.1 MB of textures (base 0.1), JS work p95 0.3 ms.
+
+## Grade
+
+4. Grade: a ColorMatrix (warmth, contrast) plus a custom vignette filter, on the world container.
+
+```ts
+const VERTEX = `in vec2 aPosition; out vec2 vTextureCoord; out vec2 vUv;
+uniform vec4 uInputSize; uniform vec4 uOutputFrame; uniform vec4 uOutputTexture;
+void main() {
+  vec2 p = aPosition * uOutputFrame.zw + uOutputFrame.xy;
+  p.x = p.x * (2.0 / uOutputTexture.x) - 1.0;
+  p.y = p.y * (2.0 * uOutputTexture.z / uOutputTexture.y) - uOutputTexture.z;
+  gl_Position = vec4(p, 0.0, 1.0);
+  vTextureCoord = aPosition * (uOutputFrame.zw * uInputSize.zw);
+  vUv = aPosition;                                              // 0..1 across the filtered area
+}`;
+// Uniforms shared with the vertex stage (uInputSize…) differ in precision there: pass what the
+// fragment needs as a varying (vUv) instead of redeclaring them, or the program fails to link.
+const VIGNETTE = `in vec2 vTextureCoord; in vec2 vUv; out vec4 finalColor;
+uniform sampler2D uTexture; uniform float uStrength; uniform vec3 uShadowTint;
+void main() {
+  vec4 c = texture(uTexture, vTextureCoord);
+  float v = smoothstep(0.85, 0.25, distance(vUv, vec2(0.5)));
+  float lum = dot(c.rgb, vec3(0.299, 0.587, 0.114));
+  c.rgb = mix(c.rgb * uShadowTint, c.rgb, smoothstep(0.0, 0.6, lum)); // tint the shadows
+  finalColor = vec4(c.rgb * mix(1.0 - uStrength, 1.0, v), c.a);
+}`;
+export function vignetteFilter(strength = 0.45, shadowTint: [number, number, number] = [0.75, 0.8, 1.1]): Filter {
+  return new Filter({
+    glProgram: GlProgram.from({ vertex: VERTEX, fragment: VIGNETTE, name: 'vignette' }),
+    resources: { grade: { uStrength: { value: strength, type: 'f32' }, uShadowTint: { value: new Float32Array(shadowTint), type: 'vec3<f32>' } } },
+  });
+}
+export const grade: Recipe = (_app, world) => {
+  const cm = new ColorMatrixFilter();
+  cm.saturate(0.15, true); cm.contrast(0.12, true);
+  const vig = vignetteFilter();
+  // Filters render at resolution 1 by default: soft on a DPR 2 phone. 'inherit' is crisp and costs 4x the pixels.
+  cm.resolution = vig.resolution = 'inherit';
+  world.root.filters = [cm, vig];
+  return () => {};
+};
+```
+
+Measured: 3 draw calls (base 1), 10.2 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+## Water
+
+5. Water / heat haze: a displacement map that scrolls. The map sprite must be on the stage (hidden is fine).
+
+```ts
+export function noiseTexture(size = 128): Texture {
+  const c = document.createElement('canvas'); c.width = c.height = size;
+  const g = c.getContext('2d')!, img = g.createImageData(size, size);
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    const i = (y * size + x) * 4, v = 128 + 60 * Math.sin(x * 0.2) * Math.cos(y * 0.15) + 40 * Math.sin((x + y) * 0.09);
+    img.data[i] = img.data[i + 1] = v; img.data[i + 2] = 128; img.data[i + 3] = 255;
+  }
+  g.putImageData(img, 0, 0);
+  const t = Texture.from(c); t.source.addressMode = 'repeat';
+  return t;
+}
+export const water: Recipe = (_app, world) => {
+  const map = new Sprite({ texture: noiseTexture(), label: 'ripple-map' });
+  map.renderable = false; world.root.addChild(map);
+  const f = new DisplacementFilter({ sprite: map, scale: 10 });
+  world.water.filters = [f];
+  return (dt) => { if (!reduced) { map.x += dt * 20; map.y += dt * 8; } };
+};
+```
+
+Measured: 4 draw calls (base 1), 0.3 MB of textures (base 0.1), JS work p95 0.3 ms.
+
+## Particles
+
+6. Particles: one ParticleContainer, a fixed pool, the budget a constant. Reduced motion = fewer, slower.
+
+```ts
+export const particles: Recipe = (_app, world) => {
+  const BUDGET = reduced ? 60 : 400;
+  const tex = glowTexture(32);
+  const box = new ParticleContainer({ label: 'fireflies', dynamicProperties: { position: true, color: true } });
+  box.blendMode = 'add';
+  const ps: Array<{ p: Particle; vx: number; vy: number; life: number }> = [];
+  for (let i = 0; i < BUDGET; i++) {
+    const p = new Particle({ texture: tex, x: Math.random() * world.w, y: world.h * (0.4 + Math.random() * 0.5), anchorX: 0.5, anchorY: 0.5, scaleX: 0.4, scaleY: 0.4, tint: 0xfff0a0 });
+    box.addParticle(p); ps.push({ p, vx: (Math.random() - 0.5) * 30, vy: -10 - Math.random() * 20, life: Math.random() });
+  }
+  world.root.addChild(box);
+  return (dt, t) => {
+    for (const q of ps) {
+      q.life += dt * 0.3; if (q.life > 1) { q.life = 0; q.p.x = Math.random() * world.w; q.p.y = world.h * 0.9; }
+      q.p.x += (q.vx + Math.sin(t + q.vy) * 10) * dt; q.p.y += q.vy * dt;
+      q.p.alpha = Math.sin(q.life * Math.PI);
+    }
+  };
+};
+```
+
+Measured: 2 draw calls (base 1), 0.1 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+## Trail
+
+7. A trail: a MeshRope along the last N positions, fading toward the tail.
+
+```ts
+export const trail: Recipe = (_app, world) => {
+  const N = 24, pts = Array.from({ length: N }, () => new Point(world.hero.x, world.hero.y));
+  const rope = new MeshRope({ texture: gradientTexture([[0, 'rgba(255,255,255,1)'], [1, 'rgba(255,255,255,1)']], 8), points: pts, textureScale: 0 });
+  rope.tint = 0x9fe8ff; rope.blendMode = 'add'; rope.alpha = 0.8; rope.label = 'trail';
+  world.root.addChild(rope);
+  return (_dt, t) => {
+    world.hero.position.set(world.w * (0.5 + 0.3 * Math.sin(t * 1.3)), world.h * (0.7 + 0.08 * Math.sin(t * 2.6)));
+    for (let i = N - 1; i > 0; i--) pts[i].copyFrom(pts[i - 1]);
+    pts[0].set(world.hero.x, world.hero.y);
+  };
+};
+```
+
+Measured: 2 draw calls (base 1), 0.1 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+## Night
+
+8. Night and 2D lights: darken the world with a multiply layer, then add light where the lanterns are.
+
+```ts
+export const night: Recipe = (app, world) => {
+  const dark = new Graphics({ label: 'night' }).rect(0, 0, world.w, world.h).fill(0x1a2350);
+  dark.blendMode = 'multiply';
+  const lights = new Container({ label: 'lights' });
+  const tex = glowTexture(256);
+  for (const l of world.lanterns.children.filter((c) => c instanceof Sprite)) {
+    const s = new Sprite({ texture: tex, anchor: 0.5, tint: 0xffa860, blendMode: 'add', alpha: 0.9 });
+    s.position.copyFrom(l.position); s.scale.set(0.8); lights.addChild(s);
+  }
+  const heroLight = new Sprite({ texture: tex, anchor: 0.5, tint: 0x8fb8ff, blendMode: 'add', alpha: 0.6 });
+  lights.addChild(heroLight);
+  world.root.addChild(dark, lights);
+  return () => heroLight.position.copyFrom(world.hero.position);
+};
+```
+
+Measured: 3 draw calls (base 1), 0.4 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+## Time of day
+
+9. Time of day: keyframes of (sky tint, world tint), eased between. One ColorMatrix on the world.
+
+```ts
+const DAY: Array<[number, number, number]> = [ // [hour, sky tint, world tint]
+  [6, 0xffc9a0, 0xffd8c0], [12, 0xffffff, 0xffffff], [18, 0xff9a70, 0xffb090], [22, 0x39407a, 0x5a6aa8],
+];
+const lerpColor = (a: number, b: number, k: number) => {
+  const ch = (s: number) => Math.round(((a >> s) & 255) + (((b >> s) & 255) - ((a >> s) & 255)) * k) << s;
+  return ch(16) | ch(8) | ch(0);
+};
+export function tintAt(hour: number): [number, number] {
+  const i = DAY.findIndex(([h]) => h > hour), b = DAY[(i + DAY.length) % DAY.length], a = DAY[(i - 1 + DAY.length) % DAY.length];
+  const span = (b[0] - a[0] + 24) % 24 || 24, k = ((hour - a[0] + 24) % 24) / span;
+  return [lerpColor(a[1], b[1], k), lerpColor(a[2], b[2], k)];
+}
+export const dayCycle: Recipe = (_app, world) => {
+  const tintWorld = (c: Container, col: number) => c.children.forEach((g) => { (g as any).tint = col; });
+  return (_dt, t) => {
+    const hour = (18 + t * 0.5) % 24; // 2 game hours a real second, starting at dusk
+    const [sky, land] = tintAt(hour);
+    world.sky.tint = sky; tintWorld(world.far, land); tintWorld(world.near, land); world.water.tint = land;
+  };
+};
+```
+
+Measured: 1 draw calls (base 1), 0.1 MB of textures (base 0.1), JS work p95 0.2 ms.
+
+## The wow beat
+
+10. The wow beat: a shockwave from the hero, godrays for the reveal, a brief bloom swell.
+
+```ts
+export const wow: Recipe = (_app, world) => {
+  const wave = new ShockwaveFilter({ center: { x: world.hero.x, y: world.hero.y }, amplitude: 24, wavelength: 140, speed: 420, brightness: 1.15, radius: -1 });
+  const rays = new GodrayFilter({ angle: 25, gain: 0.45, lacunarity: 2.6, alpha: 0.8, parallel: true });
+  const soft = new BlurFilter({ strength: 0 });
+  world.root.filters = [rays, wave, soft];
+  return (dt, t) => {
+    wave.time = (t % 2.5);                       // replay every 2.5 s in the lab
+    rays.time += dt;
+    soft.strength = reduced ? 0 : Math.max(0, 2 - wave.time * 4);
+  };
+};
+```
+
+Measured: 8 draw calls (base 1), 8.1 MB of textures (base 0.1), JS work p95 0.3 ms.

package/plugins/kiro/skills/funpixel-art/references/planes.md

@@ -0,0 +1,27 @@
+# Tiles, parallax planes and panels
+
+## Tiles
+- Flat even light, no vignette, no focal object; the pattern continues across all four edges.
+- Lay it 3×3 before wiring it. A visible seam fails; regenerate with the seam clause changed.
+
+## Parallax planes
+- One plane per call, with the same camera, horizon and light wording in each, plus what the
+  plane leaves out ("no sky, no ground").
+- The far plane is opaque; near planes are transparent. Each is as wide as the screen plus its
+  scroll range.
+- Never mirror a strip to loop it: mirrored seams grow faces and symmetrical rocks.
+- Back planes are darker and greyer by depth. A tint only darkens, so decide brightness in the art,
+  not in code.
+
+## Panels, frames and buttons
+- Even border, decoration only in the corners, plain edges, a flat centre, no text.
+- Wire as `NineSliceSprite` (or CSS `border-image`) with insets of about a quarter of the short
+  side, so the corners never stretch.
+- Standard control glyphs (pause, mute, arrows, close) are inline SVG in code, not generated art:
+  generated glyphs read as clip art and cost credits.
+
+## Backdrops
+- One per scene, `generate_image`, opaque, at the screen's aspect, with the style frame as its
+  reference: a calm, low-contrast middle where play happens and detail toward the edges.
+- Check it under the HUD and the sprites before accepting: a busy middle hides what the player
+  steers, which is a layout finding the critic panel will file.

package/plugins/kiro/skills/funpixel-art/references/prompts.md

@@ -0,0 +1,171 @@
+# Prompts, references, rubrics and bake-offs
+
+Detail for [look](look.md). Read it when writing the first prompt
+of a new family, running a bake-off, or writing a rubric.
+
+## Prompt shape
+
+Order: the subject in one plain sentence, then the `medium` sentence, then the family clause, then
+the `never` line. Nothing else unless a rubric line failed and needs its own clause.
+
+- **Subject first, in the world's words.** "A hermit crab carrying a cracked teacup as its shell,
+  three-quarter view, claws raised." Name the material and the shape; the style is already in
+  `medium`.
+- **Name the light once** in `medium` ("soft light from the upper left, short shadow to the lower
+  right"). Unnamed light is filled with the model's average, and sets lit from different sides
+  never sit together.
+- **State positives.** "Plain mid-grey field" works; "no busy background" mostly does not.
+  Negatives are kept only for the `never` line, where a single clear sentence holds.
+- **Keep it short.** About 200 words is the ceiling; past a handful of distinct requirements some
+  are dropped without notice. If a prompt needs more, the asset is two assets.
+- **One change per refinement.** A refinement prompt names the one thing to change and lists what
+  must stay ("same shell, same claws, same colours; only the claws now hold a pearl").
+- **Materials, not names.** Never a game, franchise, studio, artist or living person. They pull
+  in someone else's look and trip content refusals.
+- **No words.** Titles, numbers, labels and speech bubbles are drawn by the game in real fonts.
+  In a target image the HUD is panels and icon shapes only.
+- **Not even the game's own name.** Given a name, the model tries to letter it and garbles it.
+  `funtools gen` and `assets gen` warn when a picture prompt carries the `funpixel.json` name;
+  `gen --strip-title` sends it without. Keep it only when you want the letters drawn, and check them.
+
+## Reference roles
+
+A reference with no stated role blurs into the subject. Say what each one is for, in the prompt:
+
+- Style frame: "The reference image is this game's approved art. Match its line weight, shading,
+  palette and level of detail; do not copy its subject, layout or objects."
+- Hero: "The reference image is the approved design of this character. Keep its face,
+  proportions, colours and silhouette exactly; change only the pose."
+
+Pass at most two: the style reference plus the item's own. A third reference tends to copy its
+own mistakes into every result. A reference that shows several objects gets them merged into a
+hybrid, so a reference for a single object is that object alone on a plain field.
+
+Genre-leader screenshots as style references are the person's call, not yours: they are other
+publishers' images. Used, they steer style only (framing, saturation, how chunky the pieces are),
+never pieces, characters or marks.
+
+## Writing a rubric
+
+Lines a viewer can check in the image, each pass or fail:
+
+| Good line | Why it works |
+|---|---|
+| One object, whole, centred, on a plain field | Checkable at a glance |
+| Only the colours in `roles` | Checkable by hue |
+| Outline the same width all round | Visible at 2× zoom |
+| No letters, numbers or marks | Binary |
+| Reads as one shape at 60 px | Shrink it and look |
+| Board fills 60–70% of the screen height | A measurement |
+
+Taste words ("vibrant", "polished", "better") are not rubric lines. A loop that chases "better"
+sands off whatever made the look distinct. Write the rubric before the first generation: written
+after, it adopts the first result's flaws as the standard.
+
+Verdict format, one line per image: `crab-3: fail, line 3 (outline thickens on the left claw)`.
+
+## Fix routing
+
+Cheapest fix first, one per round, rerun from the baseline:
+
+| The verdict says | Change |
+|---|---|
+| Wrong content or framing | The change clause at the end of the baseline prompt |
+| Wrong colours | Add one explicit colour sentence naming the role hexes; one such sentence has fixed misses a style string alone did not |
+| Drifted from the look | Re-attach the style or hero reference and state its role |
+| Every line failing | Another model or tier, same prompt |
+| One line failed twice under two different fixes | Stop; it is the model, not luck. Report it |
+
+## Candidates
+
+For the target, style frame, hero and key art only. Ask for three or four in one set, lay them on
+one contact sheet, and pick against the line written before generating. Say which you picked and
+why in one line; when nobody is there to choose, pick by the line and call it provisional. A
+second set for the same slot needs a new reason (the person rejected the first, or the rubric
+changed).
+
+## Bake-off per new asset type
+
+The first time the game needs a kind of asset it has not made yet (icon, tile, sheet, UI panel,
+background layer):
+
+1. Pick the candidates the tool offers: its models, or its quality tiers when it offers one model.
+2. Same prompt, same reference, same size for each. Change nothing else, or the comparison says
+   nothing.
+3. Lay the results on one contact sheet next to the target (and, for sprites, over a crop of the
+   real game background, where a halo or a wrong value shows).
+4. Judge by the rubric. Icons at 60 px and 120 px: at 60 px only one bold shape with one face or
+   symbol survives.
+5. Write the winner into `assets/style.json` under `models`, keyed by family, with one line of
+   why. Later assets of that family use it without another bake-off.
+
+Keep bake-offs cheap: run them at the lowest tier on which every rubric line can still be judged,
+and price them in the step-2 line with everything else.
+
+## Comparing a capture to the target
+
+Capture at the target's aspect and viewport. Set them side by side and write numbers, not
+impressions:
+
+- play area height as a share of the screen (the most common gap: a board at 45% against a target
+  at 68% is a layout bug);
+- hero height as a share of the screen;
+- HUD cover: how much of the play area panels hide;
+- camera height and pitch: which one is higher, and by roughly how much;
+- colours outside the roles, and where they sit.
+
+Framing and layout gaps are code fixes. Colour and style gaps route through the fix table above.
+Taste goes to the `critic` agent, which grades craft within the declared style.
+
+## Target frames at moments, and the loop that closes the gap
+
+A three.js horror game (29 Sep 2026) made its target frames for moments of the GDD's
+moment ladder (0:10 the moon pool, 1:00 the first enemy, 2:00 the dodge, 3:00 the splice, 5:00 the
+seam), so each capture has one picture it should match. The loop that closed its look gap:
+
+1. Capture the game at those moments from a recorded run, so the same second is the same frame
+   every time (`capture --view`, with a view whose `enter()` drives the game to the beat).
+2. Put each capture beside its target and name the single biggest difference.
+3. Fix that one thing; recapture; repeat. Keep a page of the pairs and grade honestly on it.
+
+What the loop found that no score would name: a light cone pointing backwards (so it never showed),
+squashed wall modules, an enemy with no face, rivets blooming into an "LED matrix" (a roughness
+floor fixed it), a camera inside lockers the hero could walk into (collision), a camera flipping
+inside a door. The owner's note that started the second art pass was the same comparison: "what
+we imagined was better; we must get close to it".
+
+A capture only counts if it shows the moment. That game's third panel scored 4.9 because every
+view silently sat at t = 0 behind the opening shot after a refactor; looking at the captures before
+reading the score found it.
+
+## Judging generated art in the game's own light
+
+A generator's preview is lit for the generator. Under its own light that game's generated
+textures read near-black, so the enemy's albedo was lifted ×1.9 to read in the dark; a few metres
+into the torch's spot it then went pure white with no face. Albedo above 1 has nowhere to go under
+a strong light. The lift went back to 1.05 and a cold rim light did the reading-in-the-dark job
+(no measurable frame cost), which the critics then called readable. The loader fixes that stuck:
+metalness down on the suit (it read as chrome), cloth at metalness 0 and 72% albedo so it did not
+burn white. Code for the loader: skill `funpixel-3d`, its three-loading reference.
+
+When something white appears that should not, suspect a light first and hide one thing at a time
+([effects](effects.md), its frames reference).
+
+## A rubric for a 3D cast, written before generating
+
+The horror game wrote ten lines before its first 3D model, each tied to an AD rule or a target frame, and
+turned every model on a turntable against them. Three show the shape: "light is the palette:
+surfaces desaturated, the only saturated hues amber (station), cyan (hero, safe tech), coral
+(enemies)"; "reads at phone size: at about 120 px tall the silhouette alone says what it is";
+"unsettling, never gory: a cut end shows coral, not meat". A line that fails is a redo or a reject;
+the provider bake-off ran only for the hero, and everything after used the winner.
+
+## A reference board before the first look
+
+`npx @funpixel/tools board search "<the feeling of the first look>"` lists open-licence pictures
+(Openverse; free, no key); keep the ones that lend something with `--keep 2,5 --lends light,palette
+--note "the cold rim light"`; `board wander R2` follows one kept picture to related ones; `board add`
+takes your own photos and links with a `--licence`. Each kept picture names one or two things it lends
+(palette, shape, light, composition, material, motion, mood, type). `board` draws `design/board/board.html`
+and fails when a board picture was copied into `public/` or `assets/`: a reference informs the first
+look, the game's own art is drawn from what it lends.