@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-3d/references/textures.md

@@ -0,0 +1,71 @@
+# Textures for ground and structures: free surfaces first
+
+A big flat-coloured triangle near the camera is what `funtools boxes` calls unfinished. The cheapest
+fix is detail at hand size, not a new model.
+
+## The free set
+
+The 3D starter's `surfaces.ts` draws six tiling detail textures in code, once, on a canvas:
+
+| Surface | What it draws | Size of one tile |
+|---|---|---|
+| `grass` | blades | 2 m |
+| `moss` | short blades | 2 m |
+| `sand` | ripples and grain | 3 m |
+| `snow` | ripples and grain | 4 m |
+| `cobble` | rounded stones in offset rows | 1.5 m |
+| `flagstone` | large slabs | 2.5 m |
+
+Each is greys around white, multiplied over the mesh's vertex colours, so the palette stays the
+place's. Each costs one texture of at most 256² and no extra draw call. A place picks its ground with
+`"surface"` in `src/places.json`; the platforms wear `flagstone`, with UVs in metres on every face
+(`metric()` in `world.ts`), so a slab is the same size on a wall and a floor.
+
+Rules for any surface, generated or drawn:
+
+- **Hand-sized detail repeats every 0.3–2 m near the camera.** A tile you can count (one big pattern
+  repeating every 10 m) reads as wallpaper.
+- **The texture carries darks.** A base map with no darks cannot be lit into contrast.
+- **The map's colour space is sRGB and it is mipmapped.** Wrap is repeat and anisotropy 4: a ground
+  seen at a glancing angle blurs to mush without it.
+- **One surface per material class.** Ground, stone, wood and metal each get one map shared by every
+  mesh of that class. One material per mesh multiplies draw calls.
+
+## The paid route: a seamless tile (the creator's choice, priced first)
+
+When the place's material is its identity (oxblood velvet, Delft tile, wet slate), a generated tile
+can be worth one image. Price it first.
+
+1. **Ask for a flat, evenly lit, top-down swatch of the material and nothing else.**
+   - No perspective, no shadows baked in, no objects on it.
+   - Name the scale ("each tile about 30 cm"), the colours from the place's palette, and the style
+     lock.
+   - Use `npx @funpixel/tools gen texture`, which makes a seamless tile and refuses (uncharged) one
+     that shows a seam. Or use `edit_image` from a photo the creator owns.
+2. **Check the seam yourself too.**
+   - Offset the picture by half its size in both directions (in any editor) and look at the cross
+     where the edges now meet.
+   - A visible step there shows as a grid across the whole ground: regenerate, or blend the seam
+     before shipping.
+3. **Make the darks and the value range right before the colour.** Desaturate the tile and compare
+   it with the place's target. A tile lighter than the target's ground is the most common miss.
+4. **Wire it into the surface.**
+   - Replace `map` on the material `surfaceMaterial()` returns, and keep `vertexColors` for the
+     place's variation.
+   - Set `repeat` to world metres over the tile size.
+   - Ship it as WebP at 512² or 1024², through `npx @funpixel/tools optimize`.
+5. **Add PBR maps only when the light needs them.** A normal map earns its place when the key light
+   is low (`dusk`, `dawn`) and the surface is near the camera. The 3D bench's `apply_texture` bakes
+   textures onto a model with its geometry checked before and after
+   ([bench](bench.md)). Roughness and AO maps rarely show at phone size.
+6. **Measure it.**
+   - `funtools boxes` should stop naming that mesh.
+   - `funtools profile` should show no new draw calls.
+   - `funtools score --target` should move the density axis.
+
+## Free alternatives before paying
+
+- Poly Haven textures (`find_material` / `get_material`, CC0, PBR sets) at 1k for ground, stone and
+  wood. Tint them with vertex colours to the place's palette.
+- The procedural set above with a second detail scale: multiply a 0.5 m tile over the 2 m one at half
+  strength, which breaks the repeat for free.

package/plugins/codex/skills/funpixel-3d/references/three-loading.md

@@ -0,0 +1,199 @@
+# Loading a generated GLB in Three.js
+
+Every rule here comes from a game that built green, loaded without an error and still shipped
+broken. Wire all of it the first time you write the loader.
+
+## Decoders, same origin
+
+Platform GLBs are Draco- or meshopt-compressed and carry KTX2 textures. Without all three decoders
+every load throws, and a loader that swallows the error shows primitives or nothing. The decoder
+files must be served by the game itself (`public/draco/`, `public/basis/`), never from a CDN: a
+path that does not exist gets `index.html` back from the server and the loader hangs with a green
+build.
+
+```ts
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
+import { clone as cloneSkinned } from 'three/addons/utils/SkeletonUtils.js';
+
+const manager = new THREE.LoadingManager();          // drives the loading overlay
+const loader = new GLTFLoader(manager);
+loader.setDRACOLoader(new DRACOLoader().setDecoderPath('/draco/'));
+const ktx2 = new KTX2Loader().setTranscoderPath('/basis/');
+ktx2.detectSupport(renderer);                         // after the renderer exists, before any load
+loader.setKTX2Loader(ktx2);
+loader.setMeshoptDecoder(MeshoptDecoder);
+```
+
+A missing-module error on any of these means the path or the dependency is wrong. Fix it; deleting
+the import makes every model fail at runtime instead.
+
+## Light it like a generated model
+
+Generated GLBs export near-full metalness, and a metallic material with nothing to reflect renders
+flat grey. Give the scene an environment map, turn metalness down on load, add tone mapping, and
+then cut the analytic lights, or the scene blows out white.
+
+```ts
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+scene.environment = new THREE.PMREMGenerator(renderer).fromScene(new RoomEnvironment(), 0.04).texture;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;   // NeutralToneMapping keeps a literal palette
+renderer.toneMappingExposure = 1.0;
+scene.add(new THREE.AmbientLight(0xffffff, 0.25), keyLight /* DirectionalLight at about 0.5 */);
+root.traverse((o) => { const m = (o as THREE.Mesh).material as THREE.MeshStandardMaterial;
+  if (m && 'metalness' in m) m.metalness = Math.min(m.metalness, 0.2); });
+```
+
+A free HDRI, when the game has one, replaces `RoomEnvironment` as both lighting and sky.
+
+Judge the result in the game's own light, not the generator's preview. A dark three.js
+horror game (29 Sep 2026) tuned every material in its loader rather than in the files: the hero's
+suit to metalness 0.3 (it read as chrome under the torch), the crew's cloth to metalness 0 and 72%
+albedo (it burnt white in the beam). Its generated textures read near-black, and lifting the
+enemy's albedo ×1.9 made it go pure white a few metres into a spotlight: a colour above 1 has
+nowhere to go under a strong light. A lift of about 1.05 plus a rim light read better and cost no
+measurable frame time.
+
+## Optional shared toon treatment
+
+For a game that chose a uniform illustrated look, apply a shared material family and outline.
+For other directions preserve appropriate PBR or authored materials. This example is a technique,
+not a requirement to overwrite every model's material. Inspect the result in the actual scene.
+
+```ts
+import { OutlineEffect } from 'three/addons/effects/OutlineEffect.js';
+const ramp = new THREE.DataTexture(new Uint8Array([90, 170, 255]), 3, 1, THREE.RedFormat);
+ramp.minFilter = ramp.magFilter = THREE.NearestFilter; ramp.needsUpdate = true;
+const INK = [0.1, 0.08, 0.06];                       // one dark line colour for everything
+const toon = (color: THREE.ColorRepresentation, map: THREE.Texture | null = null) =>
+  new THREE.MeshToonMaterial({ color, map, gradientMap: ramp });
+root.traverse((o) => { const m = o as THREE.Mesh; if (!m.isMesh) return;
+  const old = m.material as THREE.MeshStandardMaterial;
+  m.material = toon(old.color ?? 0xffffff, old.map ?? null); });          // a generated model
+const crate = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), toon(PALETTE.wood)); // a code prop
+const outline = new OutlineEffect(renderer, { defaultThickness: 0.004, defaultColor: INK });
+// in the loop: outline.render(scene, camera) instead of renderer.render(scene, camera)
+```
+
+- One line weight and one line colour. A lighter line on dark models, tried to lift them, read as
+  a cut-out fringe; lift a dark model with a calmer backdrop behind it instead.
+- `OutlineEffect` draws the scene twice. For a crowd, give each kind one inverted hull instead: a
+  coarse copy of the mesh, back faces only, pushed out along smoothed normals, drawn in the ink
+  colour, instanced like the bodies (one draw call for the bodies and one for the ink).
+- A game with a painted or realistic look can keep one standard material setup instead (below);
+  a mix of families is what reads as two games in one scene.
+
+## Clips and the mixer
+
+Each clip arrives as its own file sharing the base skeleton (`knight.run.glb`). Bind one mixer to
+the object you add to the scene, and update it every frame with dt in seconds.
+
+```ts
+const gltf = await loader.loadAsync('assets/models/knight.glb');
+const root = gltf.scene; root.name = 'player_knight'; scene.add(root);
+const mixer = new THREE.AnimationMixer(root);        // never gltf.scene.scene
+const clips: Record<string, THREE.AnimationClip> = {};
+for (const a of ['idle', 'run', 'jump'])
+  clips[a] = (await loader.loadAsync(`assets/models/knight.${a}.glb`)).animations[0];
+let current = '';
+function play(name: string) {
+  if (!clips[name] || name === current) return;
+  const next = mixer.clipAction(clips[name]);
+  next.enabled = true; next.setEffectiveTimeScale(1); next.setEffectiveWeight(1);
+  next.reset().fadeIn(0.3).play();
+  if (current) mixer.clipAction(clips[current]).fadeOut(0.3);
+  current = name;
+}
+// in the loop: mixer.update(dt);
+```
+
+- Weight before `fadeIn`: a fade multiplies the base weight, so an action parked at weight 0 plays
+  invisibly and the skeleton freezes once the previous one fades out.
+- A clip file that 404s (its step failed on the server) is skipped; idle keeps the model alive.
+- Feet match the ground. A walk or run clip was authored at one travel speed; played at another
+  the feet skate. Measure the clip's own speed once (distance the root or a foot covers per loop
+  over the clip's duration) and each frame set `setEffectiveTimeScale(speed / clipSpeed)`, kept
+  within about 0.6 to 1.6; past that, cross-fade to the other clip. Standing still plays idle,
+  where a walk at time scale 0 freezes mid-stride. `audit_clips` reports a planted foot that slides.
+- Zero clips on a character whose role moves is a constraint, and code motion can supply what
+  the role promises: a stride oscillator driving bob, lean and sway; a lunge that overshoots and
+  settles; a hit response; a tumble on death. A prop may stay still.
+
+## Copies
+
+`Object3D.clone()` on a skinned model shares the original skeleton, so every copy drives the same
+bones and all of them stand still. Materials are shared too, so a hit flash on one lights the
+whole horde.
+
+```ts
+const enemy = cloneSkinned(root);
+enemy.traverse((o) => {
+  const m = o as THREE.Mesh; if (!m.isMesh) return;
+  m.material = Array.isArray(m.material) ? m.material.map((x) => x.clone()) : m.material.clone();
+  (m.userData.baseEmissive ??= new THREE.Color()).copy((m.material as THREE.MeshStandardMaterial).emissive);
+});
+const enemyMixer = new THREE.AnimationMixer(enemy);   // its own mixer, its own pose
+```
+
+Restore the cached emissive after a flash: a hard-coded black erases a material that glowed.
+
+## Size, facing and the floor
+
+The default bounding box reads each mesh in bind pose; on these rigs the drawn skin can be about
+100 times that box. When the tool result states a measured size, use it; otherwise measure the
+posed bounds:
+
+```ts
+root.updateMatrixWorld(true);
+const size = new THREE.Box3().setFromObject(root, true).getSize(new THREE.Vector3());
+root.scale.multiplyScalar(TARGET_HEIGHT / size.y);
+```
+
+Ground per clip, not once: a walk clip can move the lowest point 0.3 to 0.5 m, so a model grounded
+in bind pose sinks or hovers when the clip plays.
+
+```ts
+function floorOffset(mixer: THREE.AnimationMixer, clip: THREE.AnimationClip) {
+  const action = mixer.clipAction(clip); action.play();
+  let minY = Infinity;
+  for (let t = 0; t < clip.duration; t += clip.duration / 6) {
+    mixer.setTime(t); root.updateMatrixWorld(true);
+    minY = Math.min(minY, new THREE.Box3().setFromObject(root, true).min.y);
+  }
+  action.stop(); mixer.setTime(0);
+  return -minY;                                        // add to root.position.y while this clip runs
+}
+```
+
+Optimized GLBs are often quantized: positions stored as normalized int16, the real scale carried in
+the node. Baking a node transform into that geometry (`geometry.applyMatrix4`) clamps every vertex
+to ±1; one game's 3 m wall modules stood 1 m tall for a whole pass. Keep transforms in the object
+or instance matrix. The same quantization moves each mesh's scale into its node, so a part scaled
+at runtime (a gauge's fill) has that scale baked back first, or `scale.y = fraction` is not literal.
+
+A skinned mesh keeps `frustumCulled = false` (its bind-pose bounds lie), so nothing culls a crowd
+of them: every one animates and casts shadows everywhere. Cull them by distance and screen yourself
+(skill `funpixel-art`, its frames reference, has one game's numbers).
+
+Generated models usually face +Z, but not always. Wrap each in a group; yaw the inner model once
+at load (a vehicle whose posed size has x greater than z was authored sideways), and keep steering
+on the outer group. Check the nose leads in a screenshot.
+
+## Colliders
+
+The mesh box is for scale and framing only. Collide the actor as a capsule on an invisible helper
+(radius about 0.28 times the height), and give painted scenery a hand-placed box the size of its
+gameplay footprint. A skybox or a tiled ground texture is not a floor until it has a collider.
+
+## Loading screen
+
+GLBs are several megabytes. Drive an HTML overlay (logo, progress bar, a one-line tip) from the
+shared `LoadingManager`; enable the start control on `onLoad`; show a retry state when a required
+model fails. A loop started before every model is in plays its first seconds with holes in the scene.
+
+## Exports for the checks
+
+Name every root and instance (`player_knight`, `enemy_3`) and set `window.__THREEJS_SCENE__`,
+`window.camera` and `window.THREE`, so verify can tell whether the player can be seen.

package/plugins/codex/skills/funpixel-3d/references/unity.md

@@ -0,0 +1,78 @@
+# 3D models from generator to Unity
+
+A 3D model can fail in Unity without an error. glTFast (the glTF importer, package `com.unity.cloud.gltfast`) decodes textures embedded in a GLB to raw RGBA32, 4–16 MB each, and imports a web GLB packed with meshopt or WebP as nothing. That made the 3D games 3–5× bigger than the 2D ones: one idle game was 386 MB before this pipeline and 106 MB after. This skill takes a model from the generator to a compressed, collidable asset.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, its checks and the studio scripts (`blender_prep.py`, `render_glb.py`, a collision audit, a size audit). Do the rest with what exists:
+
+- Generate into the project: `npx @funpixel/tools gen model3d "<subject>" --image-asset concept.png --unity .` (after `npx @funpixel/tools login`) asks for the engine's own GLB (`--raw`: glTFast reads no Draco, meshopt or KTX2 without three more packages), splits it into `.gltf` + `.bin` + `model__basecolor`/`__normal`/`__mr` textures in `Assets/_Game/Generated/Models/<name>/` (the studio's `glb_split.py`, ported), and writes an import rule that sets those textures once, ASTC 6×6 at most 1024, sRGB only for colour, and keeps `__normal` a NormalMap. Checked on 6000.6 with a Meshy and a Hunyuan model: meshes and textures import. The studio's `gen_3d.py` calls fal with a `.env` key: no metering, no cost log.
+
+- Prepare in Blender through the kit's bench: `npx @funpixel/tools model --local normalize hero.glb --height-m 1` (unit height), `model --local decimate hero.glb --target-triangles 3000`, `model --local inspect hero.glb` (triangle count). The hosted `inspect_model`, `optimize_model` and `fracture_model` do the same on a model a job made. Joining meshes and moving the origin to the base centre are not in the bench; do them in Blender by hand or in your own script.
+- Proof render: the hosted `render_model`, or `npx @funpixel/tools model --local render hero.glb --frames 3`, gives the three angles.
+- Split a GLB for Unity with gltf-transform (`gltf-transform copy model.glb model.gltf` writes `.gltf` + `.bin` + texture files); name the textures by role (`model__basecolor`, `model__normal`, `model__mr`) so the import rule can find them. gltf-transform also decodes web GLBs (meshopt + WebP).
+- Name split textures by role and keep them under `Art/` or `Models/`, so the import rule finds them: write it as an `AssetPostprocessor` in `Assets/Editor/`, or use the one `gen --unity` writes.
+- Collision and size audits are your own Edit Mode tests until the checks ship: compare each prop's `Renderer.bounds` with its `Collider.bounds`, and read the Editor's build report for texture formats.
+
+Checks: `texture_audit`, `drawn_vs_solid`, `glb_import`, `tri_budget` and `lfs_audit` are proposed, not built (partial versions exist in single games). Until then `model --local inspect` gives the triangle count.
+
+## Procedure
+
+1. Pick the generator from the bake-off: same GPT-Image input, 3-angle Blender render.
+
+   | Generator | Triangles | Result |
+   |---|---|---|
+   | Meshy v7.1 | 31K | won: crisp detail, rig in the same call |
+   | Hunyuan3D v3.1 Pro | 500K | best fidelity, hero option, $0.38 per mesh |
+   | Trellis 2 | not in the report | muddy |
+   | Tripo H3.1 | 1.4M | artefacts |
+
+2. Pin glTFast at 6.20.0. The "latest" tag pointed at an experimental 7.0.
+3. Decode a web GLB with gltf-transform before import, and keep the original in `design/art-source/`. glTFast imports meshopt and WebP GLBs as nothing, with no error; `funtools doctor` fails on one under Assets. `gen --unity` never hands Unity one: it asks for the raw GLB.
+4. Prepare the model (normalize, decimate, then join and re-origin in Blender). Conventions to leave: static fronts face −Z, characters face +Z, one material named `<name>_Mat`, emissive parts separate, scale checked against a 1 m cube. Nothing is baked for props; the generator's textures are kept.
+5. Reduce triangles by kind of model; each method breaks something different.
+
+   | Model | Method | What goes wrong otherwise |
+   |---|---|---|
+   | Small prop | Meshy remesh (re-bakes textures onto the new mesh) | plain decimation tears UVs (`RAMEN` became `RMEN`) |
+   | Big signage | not in the report | remesh garbles lettering (`SATAY` became `CATAY`) and decimation tears it too |
+   | Thin rims | keep 4K triangles or more | rims tear below 4K |
+
+   Budget (`tri_budget`, proposed): a prop at most 2.5–7K by shape, a scene at most 300K. Which shape gets which figure inside 2.5–7K is not in the report.
+6. Render the proof (`render_model` or `model --local render`) and read the three angles: lettering legible, rims whole, count in budget.
+7. Split the GLB (gltf-transform) and import the split `.gltf`. Your import rule then applies. Change the rule in code, not the `.meta`: the rule reverts a hand edit on the next import.
+
+   | Kind | Setting |
+   |---|---|
+   | Model textures | ASTC 6×6, mipmaps, sRGB only for basecolor and emissive, max 512 (props) or 1024 (stalls) |
+   | 3D models | default glTFast import of the split `.gltf`; no LODs except one game's mid LOD |
+   | Rigged characters (FBX) | Generic rig, root `Hips`, Loop Time on, Apply Root Motion off, in-place clips at 30 fps |
+
+8. Confirm the import (`glb_import`): every GLB yields at least 1 mesh with more than 0 vertices, and no `.webp` or `.woff2` sits under Assets.
+9. Size and place the model from its measured bounds. Guessed widths were 20–70% off the real model.
+10. Give it a collider that matches what is drawn, and run `drawn_vs_solid`: drawn mesh bounds against collider bounds per prop and mover, at or under the baseline per category.
+11. Reference material assets from code. `Shader.Find` on an unreferenced shader is null on device (stripped; `funtools doctor` warns). Runtime-created materials need `multi_compile_local`, not `shader_feature`.
+12. Audit the build (`texture_audit`): 0 unwhitelisted RGBA32 textures, RGBA32 total under 1 MB. Mipmapped textures must be power of two; Unity 6000.6 ships a mipmapped non-power-of-two texture as RGBA32 even with an ASTC override.
+13. Store baked binary data as `.bytes` in LFS (`lfs_audit`: 0 tracked binaries over 500 KB outside LFS, no untracked paid art).
+
+Rigs: one shared skeleton gives one Animator for the whole cast. Large crowds use no rigs at runtime: one game bakes rigged GLBs to vertex-animation textures.
+
+## Worked example
+
+A new 3D idle game, done with the studio's own scripts (proposed for the kit). Steps 2–4 are the report's general pipeline; it does not log them per game.
+
+1. Props and stalls as generated GLB; characters as Meshy-rigged FBX (the auto-rig survived import 7 of 7).
+2. Blender prep at 3,000 triangles: joined, unit height, origin at base centre.
+3. A 3-angle proof render and the triangle count.
+4. Split: `.gltf` + `.bin` + `model__basecolor`, `model__normal`, `model__mr` PNGs.
+5. The texture import rule: ASTC 6×6, max 512 for props and 1024 for stalls.
+6. Result: data 315 → 61 MB; the app 386 → 106 MB with the build size settings also on. Another game went 229 → 75 MB.
+
+## Common mistakes
+
+- Importing a web GLB as it is. One game's 12 heads "did not import at all", with no error.
+- A prop with no collider, or art bigger than its collider. 42 props in one game could be walked through; another's paperweight art was 54 px taller than its collider; a head drawn 1.15× its hitbox was removed.
+- `shader_feature` on a runtime-created material. One game's instanced sets drew at the origin on device.
+- Baked data as serialised YAML in git. One game's vertex-animation crowd assets are about 70 MB of YAML (minotaur 13.0 MB, cyclops 11.8 MB), and every re-bake adds about 70 MB to history.
+- Paid generations outside LFS: about 840 MB lived on one Mac.
+- Trusting Meshy's Idle preset. It bowed the head to the chest and was re-keyed in Blender.

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

@@ -0,0 +1,104 @@
+---
+name: funpixel-art
+description: Use when choosing or checking a game's look (style, colours, a target frame, eye comfort), making 2D art (sprites, sheets, poses, backdrops, tiles, icons; a little pixel knight), or adding light and effects (glow, bloom, particles, fog, night), or when captures drift from the target or effects cost frames. In Unity (sprites, atlases, TextMeshPro glyphs), follow references/unity.md.
+---
+
+# The look: direction, 2D art and effects
+
+Choose a look that serves the player, make every asset from it, and prove it in the running game.
+A simple style still owes clear silhouettes, one family and feedback; a generated image is a draft
+until it is measured and wired (an opaque "transparent" plate, a 1024 px coin drawn at 40 px and
+art never loaded all build green). Effects are how a flat scene becomes a place at a time of day,
+and the easiest way to lose a phone's frame rate. Name stand-ins as stand-ins.
+
+## Route by the job
+
+| The job | Read |
+|---|---|
+| Choose or check the look: the target frame, five AD rules, UI as art, judging captures | [look](references/look.md), [judging frames](references/judging-frames.md), [ui](references/ui.md) |
+| Make, repair or wire 2D art: which tool, keying, animation, atlases | [2d-assets](references/2d-assets.md), [animation](references/animation.md), [wiring](references/wiring.md) |
+| An asset family that stays one family | [style-file](references/style-file.md), [prompts](references/prompts.md), [cast](references/cast.md) |
+| Light, grading, particles, the reveal, and what each costs | [effects](references/effects.md), [pixi](references/pixi.md), [three](references/three.md), [cost](references/cost.md) |
+
+## Tools
+
+- `generate_image`: a target frame, backdrops, tiles (`kind: "texture"`, seamless), panel art.
+  `generate_sprite`: one transparent object (hero, enemy, pickup, prop, icon; a glow on pure black).
+- `edit_image`: the same character in a new pose or state (`mode: "pose"`). `generate_spritesheet`:
+  a character's cycles as one packed sheet from its accepted sprite.
+- `list_characters`, `get_character`, `restyle_character`: ready-made characters that already
+  fit; `slice_sheet` cuts a sheet into frames; `accept_asset` measures an image for its role, free;
+  `import_asset` brings in art no job made, free.
+- `get_job` collects a job by id; after a timeout, collect rather than submit again.
+- `capture_view` and `inspect_scene` show the look and the effects in the running game;
+  `generate_skybox` and `get_material` for 3D skies and HDRIs.
+- Local and free: `npx @funpixel/tools look --sheet` (every sprite at play heights on the real
+  ground), `look --read`, `variety` (which games a choice sits close to), `score --target`,
+  `cut` and `parts` (cut a painted sheet), `assets pixels` (an exact pixel-art grid),
+  `optimize pack-atlas|compress`, `profile --views <name>` (draw calls, texture memory, frame times)
+  and `smoke`. `npx @funpixel/tools job <id> --wait --out <path>` saves a job with provenance.
+- Without the MCP: `npx @funpixel/tools gen image|sprite|edit|sheet "…"` with a paid key; lacking a
+  key does not preclude authored or procedural art.
+
+## The look first
+
+1. **Match the scope.** A repair or a supplied look works from the accepted asset, its style guide
+   and the real background; name what is locked (identity, palette, silhouette). An open direction
+   explores a familiar option and an unexpected one; the creator's locked choices win.
+2. **State the choice** in the GDD (skill `funpixel-gdd`): medium, palette roles, camera and why;
+   a route for every asset (generated, authored, or procedural proven by a rendered study;
+   "primitives for now" is a stand-in). **Five AD rules**, each checkable in one frame.
+3. **A target frame,** `design/target.png` at the real aspect, with play area, player, threat,
+   an action moment and HUD, labelled. Capture at its viewport and measure gaps
+   in play-area share, actor size, HUD coverage and colour roles; fix framing before paying for art.
+   Match the target's quality, not its density (`score` warns on a busy or clipped frame).
+4. **Direct the UI too:** plates of the world's material, a display face, one icon family, a
+   target for the HUD and one for the title ([ui](references/ui.md)).
+
+## Making 2D art
+
+1. **List what the player sees** and start the jobs together; reuse, author or generate each.
+2. **Anchor every prompt to the style file** (`assets/style.json`): subject + medium + the family
+   clause + `never`, with the style frame (world art) or the hero reference (characters) passed as a
+   reference. A set stays one set because every item is anchored to the same accepted images.
+3. **Write the rubric first:** three to six pass/fail lines citing the AD rules ("one 4 px ink
+   outline", "reads at 48 px"). A line written after seeing the result grades the result.
+4. **Transparency:** native alpha first; glows on pure black, keyed by luminance. A pale subject on
+   white is eaten by the key: ask for a dark outline and a field colour the subject lacks.
+5. **Measure, then repair or regenerate,** one clause changed per round from the baseline. After
+   three rounds without a clean result, or two fixes failing one line, keep the best and name the
+   miss (Scenario's stop rule).
+6. **Same identity, new state:** a hurt or powered-up hero is `edit_image` of the accepted sprite;
+   a fresh `generate_sprite` redraws another character.
+7. **Pack, wire by role, finish:** one atlas per scene, sized at phone size with `setupGameResize`,
+   compressed to the displays you support, stand-ins removed ([wiring](references/wiring.md)).
+
+## Light and effects
+
+Start from the frame you want (the time of day, the light source, what glows); an effect not in
+that sentence is probably noise. Put a filter on the layer that needs it, not the whole stage; pool
+particles behind one number per quality tier; under `prefers-reduced-motion` keep light and colour
+and drop shake and big distortion. Profile the view before and after on the same seed and read the
+counts, then look at it at phone size. The shelf of recipes with measured costs:
+[effects](references/effects.md).
+
+## Worked example
+
+A side-scrolling fox, target and style file in place. AD rules include "one 4 px ink outline" and
+"coral only on the fox". Six jobs start together, each anchored to the style frame or the fox; the
+fox's `generate_spritesheet` (idle 4, run 6, hit 2) comes back aligned and `edit_image` adds its
+blink. Packed and sized (fox 16% of screen height, hitbox 70%), the `Graphics` stand-in deleted.
+At dusk, additive halos on five lanterns take the view from 1 to 3 draw calls and read as warm
+light; a full-screen grade at resolution 1 holds 4.1 MB of filter textures, against 10.2 MB at
+`'inherit'`. Smoke is clean.
+
+## Common mistakes
+
+- Text and glyphs drawn into generated art: they blur and cannot change (the wordmark excepted).
+- "Sprite sheet, walk cycle, 8 frames" as the whole prompt: you get a picture of a sheet.
+- Trusting "transparent" without measuring: a whole family has shipped at alpha 255.
+- Calling the declared medium a defect: inconsistent execution is the defect, not the medium.
+- A filter or bloom on the whole stage when one layer needed it: every pixel pays, every frame.
+- A white starburst on contact: it reads as glare; a small warm glow for about 0.16 s answers a hit.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

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

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-art"
+  short_description: "choosing or checking a game's look (style, colours, a target frame, eye comfort), making 2D art (sprites, sheets, poses,"
+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"

package/plugins/codex/skills/funpixel-art/references/2d-assets.md

@@ -0,0 +1,108 @@
+# 2D assets for a Funpixel game
+
+The art is what players see first. Study how the hits hold together:
+Hollow Knight's hand-drawn cast reads by silhouette, Dead Cells animates tiny heroes pose to pose,
+Ori glows white over painted parallax. One family, the hero clearest, motion by state. Generated,
+authored and procedural art all qualify ([look](look.md) sets the look). A generated image
+is a draft until measured and wired: an opaque "transparent" plate, feet that jump between frames, a
+1024 px coin drawn at 40 px and art never loaded all build green.
+
+## Tools
+
+- `generate_sprite`: one transparent object (hero, enemy, pickup, prop, icon).
+- `generate_image`: opaque art (backdrops, the far parallax plane, tiles, panel art).
+- `edit_image`: a second drawing of an accepted picture, the same character (`mode: "pose"`, [cast](cast.md)). `generate_spritesheet`: a character's cycles as one packed
+  sheet and a manifest, every frame an edit of one base (`body`: biped, quadruped, flyer).
+- `list_characters`, `get_character`, `restyle_character`: [the character library](characters.md).
+- `slice_sheet` cuts a sheet into frames, one animation per row; `npx @funpixel/tools parts` cuts
+  a character sheet into parts or poses, an item sheet into items; a 2D hero in 3D: `funpixel-3d` references/painted-target.md. `accept_asset`
+  measures an image for its role; free.
+- `npx @funpixel/tools job <id> --wait --out public/assets/<file>` saves a job.
+- Local and free: `npx @funpixel/tools optimize pack-atlas|compress` (step 9) and
+  `npx @funpixel/tools smoke`, which warns on a shapes-only game.
+- Without the MCP: `npx @funpixel/tools gen sprite|image|edit|sheet "…"` with a paid key.
+- A manifest that re-makes only what changed: `npx @funpixel/tools assets gen` (optional;
+  [pipeline.md](pipeline.md)).
+
+## Which tool, which background
+
+| Asset | Tool | Background | Notes |
+|---|---|---|---|
+| Hero, enemy, pickup, prop | `generate_sprite` | transparent | hero reference for characters |
+| A character the library fits | `get_character` | transparent | restyle it |
+| Idle, walk, attack, hit, death cycle | `generate_spritesheet` | transparent | from the accepted sprite, step 5 |
+| Blink, hurt face, happy pose | `edit_image`, mode `pose` | kept | step 8 |
+| Effect cycle | `generate_image` | transparent | grid spec, [sheets.md](sheets.md) |
+| Glow, spark, smoke, flash | `generate_sprite` | pure black | luminance key, step 6 |
+| Backdrop, far parallax plane | `generate_image` | opaque | screen aspect, style frame reference |
+| Near parallax plane, panel art | `generate_sprite` | transparent | [planes.md](planes.md) |
+| Floor or wall tile | `generate_image`, `kind: "texture"` | opaque | seamless (a seam is refused, uncharged; `gen texture` without the MCP), same reference |
+| Pause, mute, arrows, close | none | none | inline SVG in code |
+
+## The checklist
+
+1. **Use the direction the job needs.** A new family starts from a target and a style file
+   ([look](look.md)); a repair or a supplied style works from the accepted references and
+   the real background.
+
+2. **List what the player sees.** From the target: backdrop, player, threats, pickups and effects.
+   Reuse, author or generate each; jobs started together arrive while you code.
+
+3. **Build every prompt from the style file, anchored.** Subject + `medium` + the family's clause
+   + `never` from the style file or supplied brief; vary only the intended change. Pass the style
+   frame (world art) or the hero reference (characters) as a reference: a set stays one set
+   because every item is anchored to the same accepted images, not because the words match.
+
+4. **Write the rubric before each asset type.** Three to six pass/fail lines a viewer can check,
+   citing the AD rules ("one 4 px ink outline", "reads as one shape at 48 px"). A line written after
+   seeing the result grades the result, not the brief.
+
+5. **Animate for the role and promised state changes.** A walking character wants readable
+   locomotion, an attack its warning, contact and recovery; a board token may rest still. Cycles
+   from `generate_spritesheet` of the accepted sprite, a pose from `edit_image`, or authored motion,
+   switched by state. Techniques, code and what `scene --motion` can and cannot say:
+   [animation.md](animation.md).
+
+6. **Transparency and keying.** Native alpha first: the transparent flag, and "the subject alone on
+   a plain field". Glows: pure black, then luminance as alpha, or additive blend on purpose. A pale
+   subject on white, or a green one under a green key, gets eaten: ask for a dark outline and a
+   field colour the subject lacks.
+
+7. **Measure, then repair or regenerate.** Read the verdict the tool returns; where there is
+   none, measure ([measure.md](measure.md)): transparent share, clear
+   corners, hues inside the style roles, the trimmed box fits its role. Each verdict cites a rubric
+   line. One clause changed per round, each from the baseline, keeps a change and its effect
+   paired. After three rounds without a clean result, or two fixes failing one line, keeping the
+   best and naming the miss usually beats another respin (Scenario's stop rule). Repair on a copy
+   and recheck it on the real background.
+
+8. **Same identity, new state.** A hurt, happy or powered-up hero is `edit_image` of the
+   accepted sprite (`pose` for a pose, `edit` for a change): a fresh `generate_sprite` redraws
+   another character. Art no job made: `import_asset` (free), `gen … --asset <file>`.
+
+9. **Pack, wire by role, finish.** Pack sprites that share a scene into one atlas
+   (`optimize pack-atlas`, loaded once by a relative path), size and collide by role at phone size
+   with `setupGameResize` and a stored `baseScale`, compress to the displays you support (or deliver
+   at that size: `target_size`), and remove the stand-ins the new art replaces. Steps, code and
+   why: [wiring.md](wiring.md).
+
+## Worked example
+
+A side-scrolling fox; the target and style file exist. The list: meadow backdrop, fox, crow,
+berry, log, a spark burst. Rubric: "one 4 px ink outline", "reads at 48 px", "coral only on
+the fox". All six jobs start together, the style frame or fox as reference. The fox passes; the
+fox's `generate_spritesheet` (idle 4, run 6, hit 2) comes back aligned, and `edit_image` adds
+its blink. Everything is packed and sized (fox 16% of
+screen height, hitbox 70%); the fox's `Graphics` stand-in is deleted; smoke is clean.
+
+## Common mistakes
+
+- "Sprite sheet, walk cycle, 8 frames" as the whole prompt: you get a picture of a sheet.
+- Sliding an action character without its promised state feedback, or idle bob added only to
+  satisfy a motion counter.
+- Trusting "transparent" without measuring: a whole family has shipped at alpha 255.
+
+Where this comes from: style-file anchoring, rubric-first, one clause per round, the stop rule and
+the sheet recipes adapted from scenario-labs/skills (MIT; THIRD_PARTY_NOTICES.md); the tools,
+keying, measures, wiring and character library are ours.
+