@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-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
+`funpixel-3d`, references/painted-target.md).

package/templates/common/.agents/skills/funpixel-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.

package/templates/common/.agents/skills/funpixel-art/references/three.md

@@ -0,0 +1,232 @@
+# Three.js effect recipes
+
+Each recipe ran in a scratch scaffold on **three 0.170.0** (the scaffold pins `^0.170.0`), was captured
+at 844×390 on a phone viewport and profiled with `npx @funpixel/tools profile`, on a desktop GPU and
+on the software renderer (`--software --repeat 3`). A recipe takes the world and returns a per-frame
+update; one that post-processes replaces `world.render`. Expose `window.__THREEJS_RENDERER__` and
+`window.__THREEJS_SCENE__` so `profile` can read the renderer and the scene.
+
+```ts
+import * as THREE from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
+import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js';
+
+export type Recipe = (world: World) => (dt: number, t: number) => void;
+const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
+const phone = matchMedia('(pointer: coarse)').matches;
+```
+
+`World` in the lab is `{ renderer, scene, camera, sun, hemi, hero, lanterns, ground, trees, render }`.
+
+## Bloom
+
+1. Bloom that picks what glows: emissive above the threshold blooms, the rest does not.
+
+```ts
+//    Half-resolution bloom on phones; OutputPass does tone mapping and sRGB at the end.
+export function bloomComposer(world: World, strength = 0.9) {
+  const { renderer, scene, camera } = world;
+  const composer = new EffectComposer(renderer);
+  composer.addPass(new RenderPass(scene, camera));
+  const size = renderer.getSize(new THREE.Vector2()).multiplyScalar(phone ? 0.5 : 1);
+  const bloom = new UnrealBloomPass(size, strength, 0.4, 0.85); // strength, radius, threshold
+  composer.addPass(bloom);
+  composer.addPass(new OutputPass());
+  world.render = () => composer.render();
+  addEventListener('resize', () => composer.setSize(innerWidth, innerHeight));
+  return { composer, bloom };
+}
+export const bloom: Recipe = (world) => {
+  world.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  bloomComposer(world);
+  return (_dt, t) => world.lanterns.forEach((l, i) => { (l.material as THREE.MeshStandardMaterial).emissiveIntensity = 2.5 + Math.sin(t * 2 + i); });
+};
+```
+
+Measured: 29 draw calls (base 15), 5182 triangles (base 5168); software renderer, median of 3 runs: frame p50 49.9 ms (base 16.7).
+
+## Atmosphere
+
+2. Atmosphere: fog in the sky's colour (distance reads as depth) and a gradient sky dome.
+
+```ts
+export function skyDome(top: number, horizon: number): THREE.Mesh {
+  const mat = new THREE.ShaderMaterial({
+    side: THREE.BackSide, depthWrite: false, fog: false,
+    uniforms: { top: { value: new THREE.Color(top) }, horizon: { value: new THREE.Color(horizon) } },
+    vertexShader: 'varying vec3 vP; void main(){ vP = normalize(position); gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }',
+    fragmentShader: 'uniform vec3 top; uniform vec3 horizon; varying vec3 vP; void main(){ gl_FragColor = vec4(mix(horizon, top, pow(max(vP.y, 0.0), 0.6)), 1.0); }',
+  });
+  const dome = new THREE.Mesh(new THREE.SphereGeometry(90, 24, 12), mat);
+  dome.name = 'sky';
+  return dome;
+}
+export const atmosphere: Recipe = (world) => {
+  const horizon = 0xf3c9a4;
+  world.scene.add(skyDome(0x4a6fb0, horizon));
+  world.scene.fog = new THREE.FogExp2(horizon, 0.045);
+  world.scene.background = new THREE.Color(horizon);
+  return () => {};
+};
+```
+
+Measured: 16 draw calls (base 15), 5696 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## Shadows
+
+3. Shadows that stay sharp and cheap: one caster, a shadow camera fitted to the play area, 1024 map.
+
+```ts
+export const shadows: Recipe = (world) => {
+  const { renderer, sun } = world;
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFShadowMap; // PCFSoftShadowMap is gone since r186; soften with shadow.radius
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(phone ? 1024 : 2048, phone ? 1024 : 2048);
+  Object.assign(sun.shadow.camera, { left: -12, right: 12, top: 12, bottom: -12, near: 1, far: 40 });
+  sun.shadow.bias = -0.0005; sun.shadow.normalBias = 0.02; sun.shadow.radius = 3;
+  world.scene.traverse((o) => { if ((o as THREE.Mesh).isMesh) { o.castShadow = o.name !== 'ground' && o.name !== 'pond'; o.receiveShadow = true; } });
+  return (_dt, t) => { world.hero.position.x = Math.sin(t) * 3; };
+};
+```
+
+Measured: 28 draw calls (base 15), 10256 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+3b. The cheaper stand-in: a blob shadow (a soft dark disc) under each actor. No shadow map at all.
+
+```ts
+export function blobShadow(radius = 0.6): THREE.Mesh {
+  const c = document.createElement('canvas'); c.width = c.height = 64;
+  const g = c.getContext('2d')!, rg = g.createRadialGradient(32, 32, 0, 32, 32, 32);
+  rg.addColorStop(0, 'rgba(0,0,0,0.55)'); rg.addColorStop(1, 'rgba(0,0,0,0)');
+  g.fillStyle = rg; g.fillRect(0, 0, 64, 64);
+  const m = new THREE.Mesh(new THREE.PlaneGeometry(radius * 2, radius * 2).rotateX(-Math.PI / 2), new THREE.MeshBasicMaterial({ map: new THREE.CanvasTexture(c), transparent: true, depthWrite: false }));
+  m.position.y = 0.01; m.name = 'blob-shadow';
+  return m;
+}
+export const blob: Recipe = (world) => {
+  world.hero.add(blobShadow());
+  return (_dt, t) => { world.hero.position.x = Math.sin(t) * 3; };
+};
+```
+
+Measured: 16 draw calls (base 15), 5170 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## Tone mapping
+
+4. Tone mapping and exposure: the whole image's response curve. AgX keeps saturated lights from clipping to white.
+
+```ts
+export const tonemap: Recipe = (world) => {
+  world.renderer.toneMapping = THREE.AgXToneMapping;
+  world.renderer.toneMappingExposure = 1.1;
+  return () => {};
+};
+```
+
+Measured: 15 draw calls (base 15), 5168 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## Particles
+
+5. Particles: one Points object, additive, a soft round sprite, a fixed pool; reduced motion = fewer.
+
+```ts
+export function softDot(): THREE.Texture {
+  const c = document.createElement('canvas'); c.width = c.height = 64;
+  const g = c.getContext('2d')!, rg = g.createRadialGradient(32, 32, 0, 32, 32, 32);
+  rg.addColorStop(0, 'rgba(255,255,255,1)'); rg.addColorStop(0.4, 'rgba(255,255,255,0.4)'); rg.addColorStop(1, 'rgba(255,255,255,0)');
+  g.fillStyle = rg; g.fillRect(0, 0, 64, 64);
+  return new THREE.CanvasTexture(c);
+}
+export const particles: Recipe = (world) => {
+  const N = reduced ? 150 : 1200;
+  const pos = new Float32Array(N * 3), vel = new Float32Array(N);
+  for (let i = 0; i < N; i++) { pos[i * 3] = (Math.random() - 0.5) * 30; pos[i * 3 + 1] = Math.random() * 6; pos[i * 3 + 2] = (Math.random() - 0.5) * 20 - 3; vel[i] = 0.2 + Math.random() * 0.6; }
+  const geo = new THREE.BufferGeometry(); geo.setAttribute('position', new THREE.BufferAttribute(pos, 3));
+  const pts = new THREE.Points(geo, new THREE.PointsMaterial({ size: 0.25, map: softDot(), color: 0xfff0a0, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, sizeAttenuation: true }));
+  pts.name = 'fireflies';
+  world.scene.add(pts);
+  return (dt, t) => {
+    for (let i = 0; i < N; i++) {
+      pos[i * 3 + 1] += vel[i] * dt; pos[i * 3] += Math.sin(t + i) * dt * 0.3;
+      if (pos[i * 3 + 1] > 6) pos[i * 3 + 1] = 0;
+    }
+    geo.attributes.position.needsUpdate = true;
+  };
+};
+```
+
+Measured: 16 draw calls (base 15), 5168 triangles (base 5168), 1200 points; software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## Outline
+
+6. An outline that costs one extra draw per actor: the inverted hull (back faces, pushed out along normals).
+
+```ts
+export function inkHull(mesh: THREE.Mesh, width = 0.04, color = 0x1b1330): THREE.Mesh {
+  const hull = new THREE.Mesh(mesh.geometry, new THREE.ShaderMaterial({
+    side: THREE.BackSide, uniforms: { w: { value: width }, c: { value: new THREE.Color(color) } },
+    vertexShader: 'uniform float w; void main(){ gl_Position = projectionMatrix * modelViewMatrix * vec4(position + normal * w, 1.0); }',
+    fragmentShader: 'uniform vec3 c; void main(){ gl_FragColor = vec4(c, 1.0); }',
+  }));
+  hull.name = (mesh.name || 'mesh') + '-outline';
+  mesh.add(hull);
+  return hull;
+}
+export const outline: Recipe = (world) => {
+  world.hero.traverse((o) => { if ((o as THREE.Mesh).isMesh && !o.name.endsWith('-outline')) inkHull(o as THREE.Mesh); });
+  return () => {};
+};
+```
+
+Measured: 16 draw calls (base 15), 5576 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## Time of day
+
+7. Time of day: the sun's angle drives its colour, the ambient, fog and background from four keyframes.
+
+```ts
+const KEYS: Array<[number, number, number, number]> = [ // [hour, sun colour, sky colour, sun intensity]
+  [6, 0xffb27a, 0xf2b28f, 1.2], [12, 0xfff4e0, 0x9fc3e6, 2.4], [18, 0xff8a50, 0xe08a6a, 1.0], [22, 0x6070c0, 0x1c2244, 0.25],
+];
+function keyAt(hour: number) {
+  const i = KEYS.findIndex(([h]) => h > hour), b = KEYS[(i + KEYS.length) % KEYS.length], a = KEYS[(i - 1 + KEYS.length) % KEYS.length];
+  const k = ((hour - a[0] + 24) % 24) / (((b[0] - a[0] + 24) % 24) || 24);
+  return { sun: new THREE.Color(a[1]).lerp(new THREE.Color(b[1]), k), sky: new THREE.Color(a[2]).lerp(new THREE.Color(b[2]), k), power: a[3] + (b[3] - a[3]) * k };
+}
+export const dayCycle: Recipe = (world) => {
+  world.scene.fog = new THREE.Fog(0x9fc3e6, 12, 45);
+  return (_dt, t) => {
+    const hour = (16 + t * 0.6) % 24, { sun, sky, power } = keyAt(hour), ang = ((hour - 6) / 12) * Math.PI;
+    world.sun.position.set(Math.cos(ang) * 15, Math.max(0.5, Math.sin(ang) * 15), 5);
+    world.sun.color.copy(sun); world.sun.intensity = power;
+    world.hemi.intensity = 0.3 + power * 0.35;
+    (world.scene.background as THREE.Color).copy(sky); world.scene.fog!.color.copy(sky);
+  };
+};
+```
+
+Measured: 15 draw calls (base 15), 5168 triangles (base 5168); software renderer, median of 3 runs: frame p50 16.7 ms (base 16.7).
+
+## The wow beat
+
+8. The wow beat: the camera eases in, the bloom swells, a burst of sparks rises, then all settle.
+
+```ts
+export const wow: Recipe = (world) => {
+  world.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  const { bloom: b } = bloomComposer(world, 0.6);
+  const sparks = particles(world);
+  const from = world.camera.position.clone(), to = new THREE.Vector3(0, 2.2, 6);
+  return (dt, t) => {
+    const k = reduced ? 1 : Math.min(1, t / 2.2), ease = 1 - Math.pow(1 - k, 3);
+    world.camera.position.lerpVectors(from, to, ease); world.camera.lookAt(0, 1.2, -2);
+    b.strength = 0.6 + 1.4 * Math.sin(Math.min(1, t / 1.5) * Math.PI);  // swell and settle
+    sparks(dt, t);
+  };
+};
+```
+
+Measured: 30 draw calls (base 15), 5182 triangles (base 5168), 1200 points; software renderer, median of 3 runs: frame p50 66.7 ms (base 16.7).

package/templates/common/.agents/skills/funpixel-art/references/ui.md

@@ -0,0 +1,163 @@
+# The UI belongs to the world
+
+The HUD, every screen and the controls are part of the game. They are designed in the GDD, made
+in the game's world, played on a real phone and judged every round with the same care as the
+characters and the levels, never a layer added at the end. The controls count too: the gesture
+on the play, how it feels and how it answers, is part of the look.
+
+The owner played our games on an iPhone (30 Sep 2026) and named the same fault in each. A puzzle
+game's warm sandstone rooms wore a HUD of dark app pills with cyan outlines and system type, and
+its title was a white bold wordmark over the scene with a cyan pill and three icon circles. An ice puzzle's
+frosty board sat under the same pills and stock glyphs ("better icons, not emojis"). A racer had
+heavy navy slabs; a toy game's title stacked panels over its basket; a night game's title floated a
+small dark board in an empty sky. One game looked better only because its creator happened to
+carve its HUD from its world's wood. The cause was ours: the look's direction covered the world,
+the cast and the target frames, but not the interface, so every game fell back to the scaffold's
+dark pill. Three of them still ship the scaffold's own glyphs.
+
+We had the answer already. One of our games' GDD: "Every screen is drawn in the factory's own
+kit (riveted steel plates, one hazard stripe, stencil type) and speaks in the world's voice. A
+screen that isn't specified gets invented by whoever reaches it first." So the look covers the UI
+by default, and the GDD specifies every screen in the world's kit: the screen list (title, how to
+play, play, pause, settings, win, loss) with each screen's look beside its job. It is an offer like
+every other line: a creator who wants a plain overlay says so, and the decline is kept.
+
+## UI pieces are art
+
+Panels, buttons, frames, icons and the wordmark are assets made from the game's style frame, the
+same way its characters and tiles are; CSS only places and scales them. A recoloured pill is still
+the scaffold's pill. They go in the art budget beside the cast (skill `funpixel-gdd`,
+plan-at-size): a plate, a button in its states, a frame for cards, the icon family, the wordmark.
+
+- **Plates and buttons** follow Scenario's panel recipe (MIT, research 05): front-on and flat, a
+  border of even thickness with decoration only in the four corners and a plain band between
+  them, one flat fill in the centre, no text. Sliced nine ways (CSS `border-image`, Pixi's
+  `NineSliceSprite`), the corners stay sharp at any size. Generate them with the accepted world
+  frame as the style reference, so the plates, the backgrounds and the textures share one anchor.
+- **The wordmark** is the one text worth making as art: carved into the world's stone, stitched in
+  its felt, lit in its lanterns. Generate it alone on a plain field, read every letter, and redraw
+  once when a letter is wrong (`gen` warns when a prompt carries the title because models misspell
+  names; short names in capitals hold best). If it still misspells, letter it in the display face
+  as SVG with the carving done in CSS. Either way the page keeps the name as text for readers
+  (`alt`, an `aria-label`).
+- **Everything else lettered** stays in code, in pinned hex colours from the roles: numbers change,
+  and letters baked into a picture blur.
+- **Icons** are one family drawn like the art (below), as inline SVG so they take the palette.
+
+## The UI section of the look: five choices
+
+1. **Material and edge, from the world.** Sandstone plaques with a chiselled bevel, frosted ice
+   with a bright rim, carved cedar with an inked outline, paper on bamboo, stitched felt. Say what
+   it is not ("no glass, no pills"). Depth is part of it: blur-behind reads as glass over the
+   scene, a hard opaque plate as machinery, flat colour with a crisp border as print; pick the one
+   the world implies, then keep one radius, one border and one shadow language on every surface.
+   The play stays the hero: plates are small and sit at the edges.
+2. **Two faces.** A display face with character for the wordmark, banners and big numbers, and a
+   plain body face for sentences. Tag each by mood and case: a condensed serif may be fine in
+   capitals and poor in a sentence; a rounded face may carry numbers but not a threat. They ship
+   with the game (two families at most); a system stack is a choice to name, not a default.
+3. **One icon family, drawn like the art.** Pause, sound, hint, undo, stars and the currency are
+   one set: the art's outline weight, its corner radius, its two-tone fill, the palette's roles, a
+   motif of the world (a sun banner, a snowflake). Never a stock glyph set or emoji.
+   Read them at 24 and 48 px on the plate they sit on.
+4. **Colour roles from the palette.** Plate, plate edge, ink on the plate, the one accent (and what
+   it means), harm. Contrast is computed: 4.5:1 for text, 3:1 for icons (skill
+   `funpixel-mobile-ui`, contrast).
+5. **Motion and touch.** How a panel enters and leaves, in the world's physics: a plaque drops and
+   settles with a dust puff, ice slides in and frosts over, a lantern swings once and glows. How a
+   press answers: a carved button sinks 2 px, a lantern brightens. How the gesture on the play
+   feels: its preview, its answer on a miss. Nothing snaps; the title is never inert (something
+   drifts, breathes or flickers). Under reduced motion it fades.
+
+Write them under `## UI` in the style bible, or in the GDD's HUD and screens section.
+
+## The look as data: the style file's `ui` block
+
+The five choices live in `assets/style.json` beside the world's style: one value the game reads,
+changed as data, never by rewriting the HUD's code. This game's data, not a preset: a shared preset
+is how every game ends up with the same HUD.
+
+```json
+"ui": {
+  "framework": "objects of the world",
+  "material": "sandstone plaque, chiselled bevel, darker lower edge, faint grain",
+  "never": "no glass, no pills, no cyan outlines on stone",
+  "type": { "display": { "family": "Cinzel", "case": "capitals", "mood": "carved, calm" },
+            "body": { "family": "Nunito", "case": "sentence", "mood": "warm, plain" } },
+  "icons": { "stroke": 2.5, "corner": 2, "fill": "two tones", "motif": "the sun banner" },
+  "roles": { "plate": "#C9A171", "plate-edge": "#7A5433", "plate-ink": "#3A2618", "accent": "#FFB238", "harm": "#FF4FA3" },
+  "motion": "plaques drop 12 px and settle in 220 ms; a press sinks 2 px",
+  "art": { "plate": "public/ui/plaque.png", "slice": 40, "wordmark": "public/ui/wordmark.png" },
+  "targets": { "hud": "design/first-look/ui-hud.png", "title": "design/first-look/ui-title.png" }
+}
+```
+
+Change the block, then carry its roles and faces into `src/look.json`, the value the game reads
+(`npx @funpixel/tools look set plate-ink=#3A2618`). Each write is checked whole: an unknown token is
+refused with the closest name, and a failing contrast pair gets a passing ink proposed.
+
+## Choose a framework before drawing
+
+A UI designed from nothing drifts to the default; a proven shape dressed in this world reads
+better. Five that fit most genres:
+
+| Framework | What it is | Fits |
+|---|---|---|
+| Objects of the world | plates, plaques, tags and buttons made of the world's material | puzzle, adventure, cosy, 3D rooms |
+| The frame holds the numbers | the board's or jar's own frame carries score and next | merge, match, board puzzles |
+| The thin bar | one slim strip along an edge, everything else on the actors | cards, strategy, roguelikes |
+| On the actor | health and state on the hero or the tool (a horror game: "the suit is the HUD", a wrist gauge strapped to her arm) | action, platformers, 3D |
+| Paper and ink | margin notes, stamps, torn labels, a hand-drawn line | narrative, cosy, crafting |
+
+Then make it this game's: `npx @funpixel/tools variety` sets the title screen beside the other
+games on this machine and says when two HUDs both kept the scaffold's clothes (after `look --hud`).
+
+## Hits whose UI belongs to their world
+
+From the kit's HUD shelf (skill `funpixel-mobile-ui`, hud-genres) and research 18:
+- **Hollow Knight**: health is a row of masks that crack when lost, beside a vessel of soul. Look
+  at how the pieces are drawn with the world's own ink and shapes, not as a bar.
+- **Slay the Spire**: each enemy shows its next move as an icon with a number over its head
+  (research 18, confirmed on the game's wiki), and the rest is one thin bar. Look at how few
+  plates there are.
+- **Dead Cells**: a skill's cooldown is a sweep across its own icon, so one glance reads both.
+- **Celeste**: the dash state is the colour of her hair; the glass carries almost nothing.
+
+Monument Valley and Alto's Adventure are often named here too; our research does not check their
+UI yet, so look at their store stills: what the title shares with a level, how little sits on the glass.
+
+## Targets: the title first, then the HUD in play
+
+The first look (skill `funpixel-gdd`) adds UI targets beside the world's frames, drawn in this
+game's style from its style frame and saved under `design/first-look/`; each is shown in the chat with
+the plan and judged like the HUD:
+- **The title** is the game's first promise and the frame a player judges first. Title key art:
+  the game's own scene, never a board preview floating on a flat colour. The overlay comes from the
+  world: the wordmark carved into or lit on its surface, the start as a thing of the world (a
+  glowing fold: step in to start), menu buttons of the world's material, icons drawn like
+  its motifs, the caption in the display face. Ask of it what a player asks: does it make me want
+  to press Play? A white bold wordmark over a pill and three icon circles is the overlay the
+  owner called plain, however good the scene behind it.
+- **The HUD in play**: a target frame with the HUD drawn over it at the phone's aspect, a
+  generated image or the HTML mockup (`hud.html`) dressed in the plates, faces and icons.
+- Pause, the win card and the settings join when the creator wants them.
+
+## How it is judged
+
+- The chat shows the UI section and each screen's target with the plan, where the person's notes land.
+- `greenlight` notes a bible with no UI section or no title target as an offer, never a problem.
+- `playtest`'s UI fidelity seat sets the built title and HUD beside these targets (skill
+  `funpixel-verify`, fidelity).
+- `npx @funpixel/tools look --hud` reads the play and the title for the scaffold's clothes: the
+  system type stack, dark neutral plates, the scaffold's own glyphs, icons typed as characters (a
+  "★" or an emoji in a label, what the owner called "emojis" on one game), a wordmark that is plain
+  system text (a gradient washed over it is still system text: one game's R4 title). It informs; a creator who chose any of them names why in the hand-back.
+
+How to dress the scaffold's HUD and screens, with worked examples: skill `funpixel-mobile-ui`, its
+reference `restyle-ui.md`.
+
+The panel recipe and the one style frame behind world and UI are adapted from scenario-labs/skills
+(MIT); see THIRD_PARTY_NOTICES.md. The surface levers come from Funpixel's own platform prompt
+(`sections/base/ui.txt`). The theme held as one value and changed only as data, the frameworks
+chosen before designing and the check against sameness are adapted ideas from Higgsfield, in our
+own words.

package/templates/common/.agents/skills/funpixel-art/references/unity.md

@@ -0,0 +1,78 @@
+# 2D art, text and glyphs in Unity
+
+2D art fails quietly in Unity: the picture still shows, but it ships uncompressed, blurred, or with a missing letter. One splash image that was not a power of two, imported with mipmaps, added 10.3 MB of raw RGBA32 to every game, even with an explicit ASTC override. This skill covers making the art, importing it by role, and proving text has every glyph.
+
+## Tools
+
+Have the build method refuse to build without `Assets/_Game/Art/Icon/app_icon.png`, imported at 1024, uncompressed, no alpha. Not shipped by the kit: the Unity starter, its checks and the studio scripts (`key_green.py`, `cut_sheet.py`, a font builder). Do the rest with what exists:
+
+- Generate with the hosted `generate_image` or `generate_sprite`, or `npx @funpixel/tools gen sprite "<prompt>" --size 1024x1024 --references target.png --unity .`: into `Assets/_Game/Generated/Sprites/` (`Images/` for plates, `Textures/` for tiles), imported on first sight as Sprite, no mipmaps, ASTC 5×5 (plates 6×6), by the rule it writes beside them (`Generated/Editor/FunpixelGenImport.cs`; no `.meta` written). Sign in once with `npx @funpixel/tools login`. Give the size: a 9:16 default made a 720×1280 icon. The studio's `gen_image.py` calls the provider with a `.env` key: no metering, no cost log.
+- Key with the hosted `key_sprite`, or ask for `--transparent` art; cut a sheet with `npx @funpixel/tools parts sheet.png --grid 4x2 --key auto` (or `cut` for a painted reference sheet).
+- `dwebp` converts the web build's WebP to PNG.
+- Write the game's own import rules: an `AssetPostprocessor` in `Assets/Editor/` (or the game's `Setup` script) that sets sprites, atlases and plates by role and scales any other mipmapped art to a power of two.
+- Bake TextMeshPro (TMP) SDF font assets with TMP's Font Asset Creator, or a small editor script around `TMP_FontAsset.CreateFontAsset`; keep one copy in the project, not one per game.
+- astcenc round-trips an atlas to measure PSNR per block size.
+
+Checks: `texture_audit`, `glyph_coverage`, `tmp_assets_small` and `import_clean` are proposed, not built (a report-only texture audit exists in one game). Until then, read the Editor's build report (`Editor.log` after a batch build) for texture sizes and formats, and test glyphs with `TMP_FontAsset.HasCharacters` in an Edit Mode test.
+
+## Procedure
+
+1. Generate sheets against the game's target image, on a green screen, and key them (`key_sprite`, or `--transparent` art). Background removal with BiRefNet ate white objects (a whole plate).
+2. Read every word in generated art by OCR; a misspelt logo got through. Which OCR tool is not in the report.
+3. Check sprite fill: 0.85 or more of the canvas. One sprite filled only 73%. How to measure fill is not in the report.
+4. Rasterise at the size the sprite is drawn. The reason is not in the report.
+5. Reuse web art: `dwebp` to PNG, pivots from the web's anchors at 100 pixels per unit.
+6. Set import rules in code (an AssetPostprocessor, the game's own setup script, or the one `gen --unity` writes, which sets a file once and leaves it yours). A hand-edited `.meta` is silently reverted by an every-import rule on the next import.
+
+   | Kind | Setting |
+   |---|---|
+   | Sprites and UI | ASTC 4×4–5×5, no mipmaps, max 1024–2048 |
+   | Backgrounds and plates | ASTC 6×6–8×8 |
+   | Splash, any mipmapped art | scaled to power of two |
+   | App icon | 1024×1024, uncompressed, no alpha |
+
+7. Pick the ASTC block by role and measure it: round-trip each atlas with astcenc, and use 4×4 if it scores under 35 dB. 6×6 put ringing on one game's ink outlines (27–35 dB); 4×4 everywhere costs +2.4 MB.
+8. Use one material per atlas.
+9. Match colour space to the source renderer on day one. Pixi and canvas blend in gamma; under Linear their translucent overlays were about 2× too strong.
+10. After swapping a PNG, check its sprite rect. A PNG of a new size keeps the old rect and Unity drops the sprite; re-importing an atlas regenerates sprite ids. `import_clean`: a fresh import gives 0 `.meta` diffs and every rect fits its texture.
+11. Run `texture_audit` on the build: 0 unwhitelisted textures shipped RGBA32 or non-power-of-two with mipmaps; RGBA32 total under 1 MB.
+
+Text and glyphs:
+
+12. Import TMP Essential Resources first, once in the Editor, or `CreateFontAsset` returns null (`funtools doctor` fails a project without them).
+13. Build fonts from the full font file. A web subset lacked Ş, Ğ and İ; Nunito lacks ▶, ◀ and ★.
+14. Run `glyph_coverage`: every character in UI strings and names exists in the atlas, 0 missing.
+15. Warm every glyph behind the title screen. First-use baking cost 183–266 ms in one game and 50–270 ms in another (17–20 ms after warm-up); a missing glyph was a third game's last 48 ms hitch.
+16. Atlases are 1024×1024 SDF, sampling 64–90, padding 8–12. The report does not settle static against dynamic.
+
+   | Atlas | Cost | Seen in |
+   |---|---|---|
+   | Static | about 5 MB for 1024² atlases | one game, which then went dynamic |
+   | Dynamic | rewritten by every batch run, conflicts on every merge, 8 MB each in git after captures | one game (`Nunito ExtraBold SDF.asset`) |
+
+   If dynamic, clear the atlases after captures. `tmp_assets_small`: every `*SDF.asset` in git under 50 KB.
+17. Ship TMP outline and underlay variants as material assets (`Resources/UiFontVariants`). Variants of materials made at runtime are stripped from release builds.
+18. Use `textWrappingMode`; `enableWordWrapping` is obsolete in Unity 6 (`funtools doctor` warns).
+19. Judge icon candidates small and against competitors: one game masked them at 100, 60 and 40 px in a mock search row with 41 competitor icons, for $5.95.
+
+## Worked example
+
+A 2D port from Pixi, texture pass:
+
+1. Web sprites as PNG; pivots from the web's anchors at 100 pixels per unit, set in the game's setup script.
+2. Colour space switched from Linear to Gamma, because translucent overlays were about 2× too strong.
+3. ASTC by role: painted plates 8×8, sprites 6×6, hero and HUD art 5×5.
+4. Result: textures 69 → 50 MB with no visible change.
+5. The power-of-two splash fix made every game 7–8 MiB smaller; one game's resources went 11.7 → 3.8 MB.
+
+## Common mistakes
+
+- A mipmapped texture that is not a power of two. The splash shipped 10.3 MB raw in every game.
+- One block size for everything. 6×6 rang the ink outlines on one game's atlases.
+- Text in generated art not read: a misspelt logo (game not named).
+- Art that does not fill its canvas: spool art at 73% fill (game not named).
+- A swapped PNG that kept its old sprite rect: an empty logo on TestFlight (game not named).
+- A subset font: "KARABAŞ" broke (game not named).
+- Outline variants not shipped: outlined numbers drew as cream blobs in one game's player build.
+- Dynamic atlases left after captures: 8 MB each in git. Two review builds carried uncommitted reimports of 4 TMP font assets, so main no longer matched what Apple reviewed.
+- Icons by prompt: one game spent $21.46 over 7 rounds before a pick; round one came out 720×1280 from the 9:16 default.