@funpixel/tools 0.0.0-stage → 0.1.1

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

package/plugins/codex/skills/funpixel-art/references/wiring.md

@@ -0,0 +1,41 @@
+# Packing and wiring accepted art
+
+Detail for step 9 of [2d-assets](2d-assets.md): once an asset is accepted, how it reaches the running
+game at the size its role needs, and how the stand-ins it replaces leave.
+
+## Pack related sprites
+
+When a set shares a scene and benefits from one load, `npx @funpixel/tools optimize pack-atlas
+<sprites…> --write` packs it; add the cycles as a named `animations` map and load
+`assets/atlas.json` once. The path stays relative, so a game hosted in a subfolder (a preview, a
+published version) still finds it. Frame keys are the original filenames. Backdrops stay out of the
+atlas: they are big, opaque and loaded once.
+
+## Wire by role
+
+- Readability and collision bounds follow the genre and camera: decide them at phone size and
+  measure them in play (`capture --viewport phone`, `audit-screens`). A 1024 px coin drawn at raw
+  texture size fills the view.
+- `setupGameResize` from `@funpixel/sdk`, with a stored `baseScale` that animation multiplies:
+  compounding a squash onto the current scale drifts.
+- Compress textures to the resolution the supported displays need
+  (`optimize compress <image> --max-size <px> --write`).
+- `npx @funpixel/tools smoke` warns on a shapes-only game and on stand-ins; read each warning
+  against the medium the game chose (authored shapes can be the look).
+
+```ts
+import { AnimatedSprite, Assets } from 'pixi.js';
+import { setupGameResize } from '@funpixel/sdk';
+
+const sheet = await Assets.load('assets/atlas.json');
+const hero = new AnimatedSprite(sheet.animations['hero-run']);
+hero.anchor.set(0.5, 1);
+let baseScale = 1;
+setupGameResize((w, h) => { baseScale = (h * 0.16) / hero.texture.height; hero.scale.set(baseScale); });
+```
+
+## Finish the integration
+
+Load the assets this task introduced and remove the stand-ins they replace: stand-ins left in
+because the logic passed are how a promised look never reached the game. Keep unrelated existing
+files; name unused candidates and remaining stand-ins in the hand-back, so the person decides.

package/plugins/codex/skills/funpixel-audio/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: funpixel-audio
+description: Use when a game needs sound effects or music, or its sound is being wired, mixed or found missing (too quiet, nothing beeps when you win). Covers a cue or silence per juice row, one music identity, adaptive music, loudness, gapless loops and the SDK AudioEngine. In Unity (a silent TestFlight build, the AudioListener, 48 kHz), follow references/unity.md.
+---
+
+# Sound and music for a Funpixel game
+
+Sound is half of how a game feels. Study the hits: Hades plays its music in stems and drops the
+drums when a fight ends; Mini Metro's score is played by the trains themselves. A game with one
+sound identity, a voice for its core verb and music that follows play is remembered. This skill
+briefs, levels, wires (`@funpixel/sdk/audio`) and proves it. The trap: a silent game passes every screenshot and bot, and four of ours reached testers silent.
+
+## Tools
+
+- `generate_sound` makes one effect per call (0.5–30 s; `loop` for a steady hum). About 2 credits.
+- `generate_music` makes a loop or a theme (`length` clip, about 30 s, or full). Set `instrumental`
+  to true for anything under gameplay. About 8 credits a clip, 16 a full track.
+- `get_job` collects them by id; `npx @funpixel/tools job <id> --wait --out <file>` saves one.
+  Start them together and write code meanwhile.
+- Local: `npx @funpixel/tools verify` checks the game and listens for sound (step 7);
+  `npx @funpixel/tools gen sound|music "…"` generates with a paid key. Web Audio synthesis is a style
+  of its own (chiptune, sfxr-style blips); name a synthesized placeholder as one.
+
+## The procedure
+
+1. **A sound for each action the design gives one, from the juice list.** Each juice row whose
+   sound column names a cue (skill `funpixel-game-feel`), and each event the design gives a feel
+   ("the lid clacks shut"), gets its own effect briefed from that line; count those rows against
+   files. Intentional silence needs no file. The core verb and its answer carry the most; a payoff
+   that is the loudest, longest sound in the game reads as the payoff.
+2. **Brief an effect: source, material, action, space.** Add the intensity and length, and end
+   with "one event, no music, no voice". Use the world's own nouns: "small brass bell struck once
+   with a felt mallet, dry close room, soft, short tail" rather than "ding"; "wet canvas sack
+   dropped on a wooden deck, close, heavy" rather than "whoosh". One event per clip; clips are at
+   least 0.5 s, so ask 0.5 for a tick and check its onset.
+3. **One music identity, briefed as a loop.** Write the game's sound in one line first (lead
+   instruments, what it never uses, a key) and repeat it in every track; only tempo and energy
+   move between title, play and the ending (our robot game: "brass and xylophone, no synths").
+   Each brief: genre, mood, instruments,
+   tempo in bpm, key, then "steady tempo, no intro swell, no ending, seamless loop". Pass
+   `instrumental` as true: it defaults to false, and "no vocals" in prose is unreliable. A clip
+   suits loops; a full track is often past the size cap.
+4. **Refusals.** Retry a refused music prompt once as written, then with plainer nouns (drop
+   battle or blood). A dropped connection is not a refusal: collect the job by id.
+5. **Pick without listening, and say so.** For the core verb and the win, two takes are cheap;
+   keep the one that starts within about 50 ms, does not clip, and is nearest the length asked
+   for. Snippet and thresholds: [references/measure.md](references/measure.md). Tell the person
+   which files to listen to.
+6. **Levels and files.** Targets by class: one-shots −16 LUFS, loops −22, music −18, peaks at
+   or below −1 dBFS. Each file 1 MiB or less, `.mp3` or `.m4a`: Safari will not play Ogg. The
+   tools master to these; a loop ships as `.mp3` with its LAME header, gapless in every
+   browser. Mixing your own files: loops about 6 dB under one-shots, music about 2 dB under; a short duck
+   under the payoff lets it own the moment.
+7. **Wire through the engine.** One `AudioEngine` per game, `{ iosPatch: false }` so the iPhone
+   ringer switch mutes it (`true` for games where sound is the point); every source through
+   `audio.master`, which the mute drives. Unlock on `click`, `pointerup` or `keydown`: WebKit may
+   not resume on `pointerdown` alone. Decode each file at load; a clip first decoded on its first
+   play is silent that time. Put a mute on the first screen and in the HUD, kept across reloads. The module, with voice caps, a per-contact cooldown and a music duck,
+   and why each piece is there: [references/engine.md](references/engine.md).
+8. **Prove it is not silent.** Set `window.__FPX_AUDIO__ = { sfx: [...], music: true }` and verify
+   fails a run in which no sound starts at all. Mark each sounding mechanic's check
+   `"sound": true`: it fails when its drive starts none, and its `sound_cues` count each cue, so
+   `buffer#1 x4` is one hit playing four times. Then press the real start control and read the
+   `audio` block's context state as `running`.
+9. **Music that follows the game, when the design wants it.** Takes of one identity that differ
+   in energy (calm, tense, wonder), layered when their lengths match or switched on the bar line,
+   with a stinger on the payoff and a low-pass for danger. The mixer, briefs, a measured run and
+   `funtools sim`'s follows-play check: [references/adaptive-music.md](references/adaptive-music.md).
+
+## Worked example
+
+A tide-pool matching game; its juice list: a shell flips, a match chimes, a mismatch clunks, the
+pool clears. Briefs: "cockle shell flipped over on wet sand, close, light, short" and "three
+small glass wind chimes brushed once, open beach air, one event, no music, no voice". Music: "gentle marimba and nylon guitar, soft shaker, 92 bpm, D major, steady tempo, no
+intro swell, no ending, seamless loop", a clip, `instrumental` true. Six jobs start together
+(about 18 credits) while the board code is written.
+
+Two takes of the flip: A starts 180 ms late, B at 12 ms; B is kept. The check `{ "mechanic": "flipping makes a sound", "verb": "flip", "field": "sounds",
+"expect": "increases" }` passes; one match reads `sounds` rising by 4 (the chime fired on every
+frame of the match flash); a 50 ms cooldown makes it 1. Front door: after pressing Play,
+`audio` reads `running`. Hand-back: "Listen to the flip and the chime; the flip is a pick by onset,
+not by ear."
+
+## Common mistakes
+
+- `new Audio(...)` or a source on `ctx.destination`: the mute misses it, and an `<audio loop>`
+  gaps at every seam. Loop a `BufferSource` instead.
+- "No vocals" in the prompt instead of the flag: a singer under the gameplay.
+- A passing verify as proof of sound: until it reports audio, it measured none.
+
+Where this comes from: the brief grammar and pick-by-onset from scenario-labs/skills (MIT; see
+THIRD_PARTY_NOTICES.md); levels, loops, the engine and the checks from our own games.

package/plugins/codex/skills/funpixel-audio/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-audio"
+  short_description: "a game needs sound effects or music, or its sound is being wired, mixed or found missing (too quiet, nothing beeps when "
+policy:
+  allow_implicit_invocation: true
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"