@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/claude/skills/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/claude/skills/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/claude/skills/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 `fp: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.

package/plugins/claude/skills/art/references/sheets.md

@@ -0,0 +1,141 @@
+# Animation sheets
+
+Detail for the sheet step of [2d-assets](2d-assets.md): the grid, the beats, reading what came back, and the
+alignment pass.
+
+## Choose the grid
+
+At most 6 columns and 6 rows, cells square, a canvas the grid divides evenly. One row per state
+where the counts allow; otherwise fill row by row, left to right, and say where each state starts.
+
+| Frames | Grid | Canvas at 256 px cells |
+|---|---|---|
+| 2 | 2×1 | 512 × 256 |
+| 3–4 | 2×2 | 512 × 512 |
+| 5–6 | 3×2 | 768 × 512 |
+| 7–8 | 4×2 | 1024 × 512 |
+| 9 | 3×3 | 768 × 768 |
+| 10–12 | 4×3 | 1024 × 768 |
+| 13–16 | 4×4 | 1024 × 1024 |
+
+Empty trailing cells are fine; inventing frames to fill a grid is not. A hero that needs detail
+gets bigger cells and fewer of them (2×2 at 512 px) rather than sixteen small ones.
+
+## Beats per state
+
+Plan the frame counts up front: after generation the only timing control left is the playback
+speed. Play cycles at 8–12 frames per second.
+
+| State | Frames | Beats |
+|---|---|---|
+| idle | 2–4 | chest rises; holds; settles; holds |
+| walk | 4–6 | contact left; passing, body highest; contact right; passing |
+| run | 4–6 | push off; airborne, legs tucked; contact; recoil |
+| jump | 3 | crouch; tucked in the air; landing |
+| attack | 3–4 | wind up; full extension; recover |
+| hurt | 1–2 | recoil back, eyes shut |
+| effect burst | 4–6 | spark; bloom to full size; break apart; fade |
+
+Identical first and last frames with no motion named asks for a freeze, not a loop. Name the
+motion for each beat.
+
+## The grid spec, as prose
+
+Build it from the style file and the table above. A template, in our words:
+
+> {subject}, {medium}. An animation sheet laid out as a grid of {cols} columns and {rows} rows of
+> equal square cells, read left to right, top to bottom, on one plain field. Every cell shows the
+> same character with identical design, proportions and colours, at the same size, from the same
+> {view}, facing {facing}, feet on the same ground line near the bottom of the cell. Row 1, idle,
+> {n} frames: {beats}. Row 2, run, {n} frames: {beats}; the last frame flows into the first. Leave
+> clear space inside every cell; nothing touches a cell edge. No grid lines, labels, numbers or
+> text.
+
+Pass the hero reference with its role stated ("keep this character's design exactly; change only
+the pose"). With no reference and no seed, a rerun is a different character, so approve one
+sheet before building on it.
+
+## Read what came back
+
+Before slicing, packing or wiring:
+
+1. Count the cells against the grid you asked for. A sheet with the wrong count is regenerated,
+   not sliced creatively.
+2. Count distinct poses per state. A state whose frames are one held pose fails the beats line.
+3. Check every cell edge: a limb or projectile cut by the edge is gone in the game.
+4. Put the first and last frame of each cycle side by side: the step between them should look no
+   bigger than the steps inside the cycle.
+
+An option for 2 and 4 in numbers: `funtools look --sheet` reads each sheet's `animations` and
+reports distinct poses per cycle and, for a loop, the seam (last to first) against the cycle's
+median step. A seam past twice the median that is also the biggest jump pops; one pose in every
+frame is frozen; a last frame equal to the first holds that pose twice. One or two frames are not
+observed, never a pass. Your eye still decides a deliberate snap.
+
+A travelling effect (an arrow, a fireball leaving a hand) never fits a cell; generate the
+projectile as its own sprite and move it in code.
+
+## Alignment is a post step
+
+Wording, margins and layout templates do not keep feet on one line: measured runs drifted by tens
+of pixels between rows, and an 87 px drift survived both anchoring words and a template image.
+When the tool result reports baseline and centre spread, read them. When it does not, measure with
+[measure.md](measure.md) (the `alphaBox` of each cell) and re-lay the frames:
+
+1. For each cell, the alpha bounding box (alpha above 128).
+2. The body centre: the middle of the widest run of columns that are at least 3% occupied. That
+   skips a thin sword or tail that would drag a plain box centre sideways.
+3. Per row, the baseline: the median box bottom of the grounded frames. A frame whose bottom sits
+   more than about 6% of the cell above it is airborne and keeps its offset, so a jump still
+   jumps.
+4. One scale for the whole sheet, the largest that fits every frame in a cell with a margin.
+5. Paste each frame onto a slightly wider canvas: body centre on the cell centre, baseline at 90%
+   of the cell height.
+
+Pass when the baseline spread is under 3% of the cell height and every frame keeps its aspect.
+Do the pass outside the game (a scratch script, never a dependency in the game's package.json,
+which the platform installs) and save the re-laid frames as the files you pack.
+
+If the poses are wrong, not just misplaced, alignment cannot save the sheet: regenerate with the
+failed beats line changed.
+
+## Timing
+
+After generation, timing is the only lever left, so plan it with the frame counts.
+
+- Cycles (idle, walk, run) play evenly at 8–12 frames a second. Tie a walk or run to speed:
+  `animationSpeed = baseSpeed * (moveSpeed / designSpeed)`, so a slower step is a slower cycle
+  and the feet never slide along the ground.
+- One-shots (attack, jump, hurt) are uneven. Give each frame its own duration: a wind-up held
+  longer than the strike (anticipation tells the player it is coming), a one-tick strike, a
+  contact frame held 60–100 ms, then the recovery. Test the hit on the contact frame.
+- A jump starts with a crouch frame and lands on one squashed frame; without them the character
+  teleports between poses. A hurt frame overrides any cycle for its length.
+
+In Pixi, per-frame durations are an `AnimatedSprite` built from `{ texture, time }` objects
+(time in ms) instead of bare textures.
+
+## Wiring a sheet
+
+Pack the frames with `npx @funpixel/tools optimize pack-atlas … --write` and name each cycle in the
+manifest's `animations` map; then
+`new AnimatedSprite(sheet.animations['fox-run'])`, `animationSpeed` from the frame rate you
+planned (`fps / 60`), and `anchor.set(0.5, 1)` so the feet sit on the ground line. Switch cycles
+by state (`sprite.textures = sheet.animations['fox-idle']; sprite.play()`), never by playing every
+frame of the sheet as one loop.
+
+Pixel art: set `TextureSource.defaultOptions.scaleMode = 'nearest'` before loading, init with
+`roundPixels: true`, and scale by whole numbers of the native size.
+
+## Cutting figures off a painted sheet
+
+The first look's locked sheets are painted on paper, and a generated `--transparent` picture comes
+back with a soft halo and stray floor patches. `npx @funpixel/tools cut sheet.jpg --names fox,crab,goat`
+cuts every figure as a clean transparent PNG, local and free: the paper keyed by its own colour
+and grain (the patches between a creature's legs too), the painted floor shadow under the feet
+removed (`--keep-shadows` keeps it), the halo thresholded to a 1 px soft rim whose colour comes
+from inside the figure, stray islands and a ruled cell grid dropped. Each piece says what was
+removed; `parts.json` keeps the boxes and pivots (feet at the bottom centre). Look at the pieces
+on a loud colour before wiring them: a figure painted in the paper's own colour at its edge may
+lose that edge. In 3D, many cut-outs from one atlas draw as one instanced mesh (skill
+`fp:3d`, references/painted-target.md).

package/plugins/claude/skills/art/references/style-file.md

@@ -0,0 +1,39 @@
+# The style file
+
+`assets/style.json`, written before the second prompt. Every prompt is assembled from it (subject +
+`medium` + the family's clause + `never`), copied byte for byte, so a set cannot drift into a
+second look through small edits. A role colour means one thing everywhere.
+
+```json
+{
+  "medium": "Flat vector game art, uniform 4 px dark ink outline, two tones per surface, no gradients, no texture noise, no weathering. Colours: deep teal #0F3D3E background, sand #E8D8B0 play surface, coral #FF6B5A hero, plum #5B2A6E harm, mint #7FE0B0 help, ink #1A1423 outlines.",
+  "roles": { "background": "#0F3D3E", "surface": "#E8D8B0", "hero": "#FF6B5A", "harm": "#5B2A6E", "help": "#7FE0B0", "ink": "#1A1423" },
+  "families": {
+    "sprite": "One object only, whole and uncropped, centred on a plain field, no ground, no shadow, no scene.",
+    "fx": "One effect only, bright shapes on pure black, no object, no ground.",
+    "tile": "Seen straight down, evenly lit, no focal object, the pattern continues across all four edges.",
+    "background": "Full-bleed scene, calm low-contrast middle where play happens, detail toward the edges, no characters.",
+    "ui": "Front-on flat panel, even border, decoration only in the corners, flat centre."
+  },
+  "never": "No text, letters, numbers, logos or watermarks.",
+  "refs": { "target": "design/target.png", "style_frame": "", "hero": "" },
+  "ad_rules": ["two tones per surface", "one 4 px ink outline weight everywhere", "hero coral appears nowhere else", "every sprite reads as one shape at 60 px", "no gradients"],
+  "models": {},
+  "failures": []
+}
+```
+
+- `medium` carries the traits a generator repeats reliably: one outline weight, two tones per
+  surface, flat fills. Gradients, grain and dirt come out different on every call, which is where
+  sets drift. A person who asks for painterly or grimy gets it, told it will drift and cost
+  regenerations.
+- `families` hold what changes with the kind of asset: framing, background, what to leave out.
+- `ad_rules` copies the design note's five AD rules, so a verdict can cite them by number.
+- `refs` hold the accepted anchors. Pass them as references by role (target or style frame for
+  world art, hero for characters) rather than describing them again in words.
+- `ui` (optional) holds the interface's look as data: material, faces, icon family, roles, motion
+  and the UI art and targets ([ui.md](ui.md)).
+- `models` records the bake-off winner per asset type; `failures` records each named failure and
+  the constant added because of it. Add a constant only after a named failure.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.