@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-art/references/judging-frames.md

@@ -0,0 +1,64 @@
+# Judging frames against the targets: a fixed rubric, fixes by module, eye comfort
+
+From a Unity 6 3D racer (Oct 2026) built by several module agents (world, racers, levels) and one
+integrator. An independent judge scored real captures against the painted targets every round; what follows is
+what held up, with its numbers. `funtools score` measures the same frames (layout, palette and light, density,
+comfort); this is the judge that reads what numbers cannot.
+
+## The rubric, fixed before the frames
+
+| Category | Points | What it reads |
+|---|---|---|
+| Composition | 30 | the camera, where the eye goes, what fills the frame, the pack or cast on screen |
+| Light | 25 | a key light, a rim, depth in the air, the contrast range (deep darks under bright cores) |
+| Detail | 25 | authored surfaces (rivets, frost, glass) rather than primitives with a streaky texture |
+| Effects | 20 | trails, glows and weather that read as the target's and do not strain the eye |
+
+- **The same rubric every round**, written before seeing the frames, so a score moves only when a frame changed.
+- **Full-resolution phone captures from the real build** (the player on the target device size, not the editor, not
+  a web stand-in): the racer judged 1172×2532 frames; half-size shots hid the material detail being scored.
+- **Per frame:** a total, the four category scores, the change since last round, and one eye-comfort word
+  (yes, mild, glare, busy, no): could a person look at it for a minute without strain?
+
+## Fix lists tagged by module
+
+Every fix names the module that owns it, `[WORLD]`, `[RACERS]`, `[LEVELS]` (or the game's own lanes), with the
+frame, the pixel region and the number: "[WORLD] the sun bloom washes out the upper right (11% clipped): bloom
+intensity −50%, exposure −0.4 EV". The integrator routes each tag to that module's agent (its lane, where
+`funtools lanes` runs them), so no agent reads another's list. End with the five changes that would raise the average most,
+each with its expected gain; the racer's round-2 list predicted 76–80 from 64.
+
+**Find the owner before assigning a fault.** Capture the same frame with one module turned off (a launch flag
+per module: no world dressing, no racer effects). The fault that disappears belongs to the module that was off;
+a stripe under the racer that stays with the effects off is not the effects agent's.
+
+## Read the categories, not only the total
+
+The racer's round 2 rose 55.6 → 64.2, but composition gave +5.1 and effects +2.2 while light gave +0.7 and
+detail +0.6: the gain came from removing noise (a white halo, crossing speed lines, a fourth trail), not from
+adding quality. Calm is not finished. When light and detail stall, give materials and lighting a round of their
+own (per place: a key light, a rim, a regrade, authored hero surfaces, a bake-off of each hero asset against
+its target) rather than another effects pass.
+
+## Eye comfort: match the targets' quality, not their density
+
+Generated targets are busier than a game should be. The owner rejects crowded, noisy, tiring worlds, and calmer
+frames than the targets are the goal, as long as the quality matches.
+
+- `funtools score` prints each frame's **busyness** (the mean brightness step between neighbouring pixels on a grey
+  copy 360 px on its short side) and **clipped share** (pixels at luma ≤ 2 or ≥ 253) beside its target's, and
+  stamps the zero board's `comfort` counter. It warns, never fails: over 14, over 1.25× the targets' busiest, or
+  over 6% clipped. The racer's painted targets read 9.2–15.4 there and its web frames 6.9–8.5; our liked
+  games' frames 2.0–11.9; one heist game's room read 7.8% clipped before its light round and 0 after.
+- A calm frame has room for detail: add mid-ground surface detail at about half the target's density, low
+  contrast and slow (the racer's near road, on its judge's own scale: a bottom-quarter gradient of about 3,
+  against 1–2 then and 5–6 in the targets).
+- Clip sources are fixes, not taste: blown bloom, a white flash, an emissive that clips to white instead of
+  keeping its colour (clamp it).
+
+## Framing calls are the owner's
+
+A rubric's framing numbers are a judge's proposal. The racer's rubric asked for the racer at 80% of the frame
+width; the owner settled on about 40%. Record the owner's number as a rule in the GDD (a tuning row), tell the
+judge it is fixed and not to mark it down, and judge what fills the space the smaller hero leaves instead. Ask
+the owner before a judge's hero size, camera height or crop becomes a fix.

package/plugins/cursor/skills/funpixel-art/references/look.md

@@ -0,0 +1,102 @@
+# Art direction for a Funpixel game
+
+Choose a look that serves the player, then prove it in the running game. A simple style still owes
+clear silhouettes, coherent screens and feedback. Name stand-ins as stand-ins.
+
+## Match the scope
+
+For an asset repair or a supplied look, use the accepted asset, style guide and real background.
+Identify what is locked (identity, palette, silhouette) and what may change. A moodboard offers
+possibilities; only the brief or agreed style rules make them binding.
+
+For an unresolved direction, explore a few alternatives, a familiar one and an unexpected one;
+`npx @funpixel/tools variety` shows which games on this machine a choice sits close to. For a new complete
+game, the moves below are what held our bar games' looks together.
+
+## Establish the look
+
+1. **State the choice.** In the design document (`design/GDD.md`, skill `funpixel-gdd`), name
+   the medium, palette roles, camera and why they suit this game's audience and actions. Before a new complete
+   game's code, the style bible (skill `funpixel-gdd`, the greenlight) holds it: several directions
+   tried, a plain one pushed up with a concrete note ("too simple: richer colour, more contrast"),
+   and a route for every asset (generated, authored, or
+   procedural proven by a rendered study; "primitives for now" is a stand-in, not a route).
+   At the first look the world's kit stands beside the hero: sheets of its structures, ground,
+   props and living cast, cut (`npx @funpixel/tools cut`) before the slice is built from them;
+   without it one fresh build coded its world from shapes.
+2. **Write five AD rules.** The critic panel reads them:
+   each checkable in a frame (colour roles, outline weight, light, material, actor readability at
+   a stated phone size); no universal percentage for hero size.
+3. **Make a target frame,** so captures have something to be measured against: `design/target.png`
+   at the real aspect, showing play area, player, threat or puzzle element, an action moment and HUD. It may be drawn, generated or rendered
+   from a small procedural study. Label its origin and status; a mock-up describes intent, never
+   proves gameplay or approval.
+4. **Compare the implementation.** Capture at the target's viewport and measure gaps in
+   play-area share, actor size, HUD coverage and colour roles. Fix framing in layout before
+   paying for new art. Check phone and desktop; a rule revised to excuse a defect stops measuring anything.
+   For a game with a moment ladder, a target frame per moment and captures of the same seconds
+   from a recorded run make a loop: name the biggest difference, fix it, recapture. Judge
+   generated models under the game's own light, where one game's near-black textures were
+   lifted into white blow-outs. Both, with what they found:
+   [prompts.md](prompts.md#target-frames-at-moments-and-the-loop-that-closes-the-gap).
+   Match the targets' quality, not their density (`score` warns on a busy or clipped frame); the rubric,
+   fixes by module and the owner's framing calls: [judging-frames.md](judging-frames.md).
+5. **Direct the UI too.** The HUD and the screens are part of the look: plates of the world's
+   material made as art, a display face, one icon family drawn like the art, a target for the HUD
+   and one for the title, the game's first promise. Undirected, every game kept the scaffold's
+   dark pills: [ui.md](ui.md).
+
+## Tools
+
+- Use `generate_image` for a target or world art, `generate_sprite` for isolated objects;
+  [2d-assets](2d-assets.md) covers sheets, transparency, packing and loading.
+- Check the tool's current estimate, total the planned jobs and follow the brief's spending
+  authorization. Reuse accepted assets first. Candidate batches are optional and reserved for
+  a target, hero or key art where the comparison is worth its cost.
+- Before the game exists, `npx @funpixel/tools look --sheet` puts every sprite at play heights
+  (24, 48, 96 px) on a neutral band and on the real ground colour (`roles.ground` or `--ground`)
+  and measures each against it. One game's sheet found its terracotta army vanishing on the
+  pass floor at 24 px before any game code.
+- A pixel-art look can be exact rather than imitated: `pixelArt` (scale, palette) in
+  `funpixel.json` has `assets process` and `gen` snap every picture to the grid and palette, and
+  `npx @funpixel/tools assets pixels` measures soft edges and stray inks ([2d-assets](2d-assets.md)).
+- For a new asset family, record `assets/style.json` before expanding the set
+  ([style-file.md](style-file.md)). Reuse its medium, family clause and
+  exclusions; vary the intended subject or repair while keeping the other choices stable. Pass a world style frame for scenery and an isolated hero
+  reference for characters. A landscape reference alone tends to produce scenery.
+- Write three to six measurable acceptance lines per asset type before seeing the result.
+  Examples: [prompts.md](prompts.md).
+- Fix the cheapest way that preserves identity: layout, crop/alpha repair, an edit, or a new
+  generation. Keep the source; recheck edges, silhouettes and palette on the real background. One variable per round keeps each change attributable; Scenario's
+  stop rule (three rounds without a clean one, or one line failing two fixes) is where naming the
+  remaining miss usually beats another paid round.
+- Start independent jobs together and collect by id with `get_job`; after a timeout, collect
+  rather than submit again. `npx @funpixel/tools job <id> --wait --out <path>` saves provenance.
+  Without MCP, `gen image|sprite` uses a paid key; lacking a key does not preclude authored art.
+
+## Check before handing back
+
+For a focused repair, compare the accepted baseline and repaired asset on the actual background
+at display size, then the changed in-game view. Check the stated repair and preserved
+identity; no new target or full critic panel is required.
+
+For a new asset family, compare contact sheets on the actual ground and current in-game captures.
+For a complete-game review, the `art-director` checks target consistency and the blind `critic`
+panel judges what shipped. Generation receipts prove origin and spend, not visual quality.
+Name failed jobs, stand-ins and provisional choices. In a 3D game, `npx @funpixel/tools look --3d`
+says whether the heroes are code primitives or models; code-built heroes are a style only when
+funpixel.json `art3d` declares it with its reason and a proof frame (skill `funpixel-3d`).
+
+## Worked example
+
+One game's sandstone rooms wore dark pills: `look --hud` read system type, 20 dark plates and
+the scaffold's glyphs. A `## UI` section chose sandstone plaques, a carved face and an inked icon
+family; a generated plate went in through `border-image`.
+
+## Common mistakes
+
+- Text and glyphs drawn into generated art blur and cannot change (the wordmark excepted).
+- Long prompts and chains of edits: each drifts, so work from the accepted baseline.
+- Calling the declared medium a defect: inconsistent execution is the defect, not the medium.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

package/plugins/cursor/skills/funpixel-art/references/measure.md

@@ -0,0 +1,119 @@
+# Measuring a generated image
+
+Detail for step 6 of [2d-assets](2d-assets.md) and the alignment pass in [sheets.md](sheets.md). Use
+the verdict the tool returns when it returns one; use this when it does not, or to check a
+suspicious pass.
+
+The snippet needs no dependencies. Paste it into the running game's page (`npx @funpixel/tools
+dev`, then your browser tool's evaluate step or the devtools console) and call it with the served
+path. It reads pixels only; it changes nothing.
+
+```js
+async function measure(url, { roles = [], cols = 1, rows = 1 } = {}) {
+  const img = await createImageBitmap(await (await fetch(url)).blob());
+  const c = new OffscreenCanvas(img.width, img.height);
+  const g = c.getContext('2d');
+  g.drawImage(img, 0, 0);
+  const { data, width: W, height: H } = g.getImageData(0, 0, img.width, img.height);
+  const px = (x, y) => { const i = (y * W + x) * 4; return [data[i], data[i + 1], data[i + 2], data[i + 3]]; };
+  const hsl = ([r, gg, b]) => {
+    r /= 255; gg /= 255; b /= 255;
+    const mx = Math.max(r, gg, b), mn = Math.min(r, gg, b), l = (mx + mn) / 2, d = mx - mn;
+    if (!d) return [0, 0, l];
+    const s = d / (1 - Math.abs(2 * l - 1));
+    const h = mx === r ? ((gg - b) / d) % 6 : mx === gg ? (b - r) / d + 2 : (r - gg) / d + 4;
+    return [(h * 60 + 360) % 360, s, l];
+  };
+  const hexHue = (hex) => hsl([1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)))[0];
+  const roleHues = roles.map(hexHue);
+  const hueDist = (a, b) => Math.min(Math.abs(a - b), 360 - Math.abs(a - b));
+
+  let clear = 0, coloured = 0, onRole = 0;
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const p = px(x, y);
+    if (p[3] < 16) { clear++; continue; }
+    const [h, s] = hsl(p);
+    if (s < 0.15) continue; // ink, greys and whites carry no hue
+    coloured++;
+    if (roleHues.some((rh) => hueDist(h, rh) <= 20)) onRole++;
+  }
+  const corner = (x0, y0) => {
+    let a = 0, n = 0; const hs = [];
+    for (let y = y0; y < y0 + 8; y++) for (let x = x0; x < x0 + 8; x++) { const p = px(x, y); a += p[3]; n++; hs.push(hsl(p)[0]); }
+    return { alpha: Math.round(a / n), hue: Math.round(hs.sort((p, q) => p - q)[hs.length >> 1]) };
+  };
+  const cw = Math.floor(W / cols), ch = Math.floor(H / rows), cells = [];
+  for (let r = 0; r < rows; r++) for (let k = 0; k < cols; k++) {
+    let x0 = cw, y0 = ch, x1 = -1, y1 = -1; const colFill = new Array(cw).fill(0);
+    for (let y = 0; y < ch; y++) for (let x = 0; x < cw; x++) {
+      if (px(k * cw + x, r * ch + y)[3] > 128) { x0 = Math.min(x0, x); x1 = Math.max(x1, x); y0 = Math.min(y0, y); y1 = Math.max(y1, y); colFill[x]++; }
+    }
+    let best = [0, -1], run = null; // widest run of columns at least 3% occupied
+    colFill.forEach((n, x) => { if (n >= ch * 0.03) { run ??= x; if (x - run > best[1] - best[0]) best = [run, x]; } else run = null; });
+    cells.push(x1 < 0 ? { empty: true } : {
+      box: [x0, y0, x1, y1], bottom: y1, centre: best[1] < 0 ? (x0 + x1) / 2 : (best[0] + best[1]) / 2,
+      touchesEdge: x0 === 0 || y0 === 0 || x1 === cw - 1 || y1 === ch - 1,
+    });
+  }
+  return {
+    size: [W, H],
+    transparentShare: +(clear / (W * H)).toFixed(3),
+    corners: [corner(0, 0), corner(W - 8, 0), corner(0, H - 8), corner(W - 8, H - 8)],
+    onRoleShare: coloured ? +(onRole / coloured).toFixed(3) : null,
+    cells,
+  };
+}
+
+// await measure('assets/fox.png', { roles: ['#FF6B5A', '#E8D8B0', '#7FE0B0'] })
+// await measure('assets/fox-sheet.png', { cols: 4, rows: 2 })
+```
+
+## Reading it
+
+| Check | Pass | A fail means |
+|---|---|---|
+| `transparentShare` on a sprite asked to be transparent | 0.12 or more for a compact object; a failed key often reads under 0.05 | Inspect the plate; repair alpha if the subject can be preserved, otherwise regenerate |
+| `corners` alpha on a transparent sprite | all four near 0 | The subject or its scene reaches the edge |
+| `corners` hue on an opaque plate before keying | all four within about 20° | The model drew a scene, not a subject on a field |
+| `onRoleShare` | 0.85 or more | Inspect the mismatch; repair a local colour error or refine the generation clause |
+| `cells[i].touchesEdge` | false for every cell | Check actual clipping; repair if complete source pixels exist, otherwise regenerate or separate the effect |
+| `cells[i].bottom` spread across grounded frames | under 3% of the cell height | Feet jump; run the alignment pass |
+| `cells` count and `empty` | as many filled cells as frames asked for | Inspect indexing and slicing first; repair the layout or regenerate missing content |
+| `box` aspect | close to the brief (a tall knight is taller than wide) | Wrong framing, or a contact sheet of parts |
+
+Hue, not RGB distance, decides the palette check: the same colour in light and shadow is far apart
+in RGB and close in hue. Whites, greys and the ink outline carry no reliable hue, which is why
+pixels below 15% saturation are skipped.
+
+Numbers are the floor, not the verdict. A sprite that passes every row can still be the wrong
+character; compare it with the hero reference and the style frame on one sheet before wiring.
+
+Two optional checks see what numbers cannot, each one seat on your own agent (funtools calls no
+model; a seat reads each picture once, a few thousand tokens):
+
+- **Structure.** An artifact score has praised a car with two different wheels. `npx @funpixel/tools
+  judge structure <file|folder> --prompt "what it should be"` asks five fixed yes/no questions with
+  evidence: matched pairs, part counts, attachment, lettering, the frame. Any no fails, and it is
+  never averaged into a look score. On one generated four-pose bee set it caught tangled antennae
+  in one pose. Worth it for a hero, a face the player stares at, or anything with lettering.
+- **Identity.** `judge identity <frames|folder> --concept hero.png` holds every pose to the hero on
+  silhouette, palette, key features and proportions, and names the worst frame per trait. Major
+  drift fails, minor is said; an expression the pose asks for is animation, not drift.
+
+`judge report` reads the answer back: exit 0 pass, 1 fail, 2 not observed (nothing filed, a
+question left without evidence, or the picture changed since).
+
+When a check fails, diagnose the cause before choosing a repair. For an accepted sprite with an
+alpha fringe, preserve the original and repair the alpha or edge without changing its silhouette,
+colours or identity. A crop is appropriate only when it removes unwanted border content and
+leaves the subject and required anchors whole. Record the transformation so it is reproducible;
+then remeasure and inspect at the real display size on the actual game background.
+
+Use `edit_image` for a generative edit when needed. Regenerate from the accepted reference only
+when the defect cannot be repaired without losing the intended identity or missing the brief;
+change the failing clause, not the entire direction. A passing numeric check alone is not approval.
+
+**Which route says no, measured.** `npx @funpixel/tools jobs --refusals` tallies, per tool, how often your
+own jobs were refused and by what (policy, the asset gate, bad input) over the latest 500. A route that
+refuses often wants plainer, generic descriptors; judge our routes by these numbers, not by any vendor's
+reputation for strictness.

package/plugins/cursor/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.