@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-3d/references/reading.md

@@ -0,0 +1,41 @@
+# Reading the bench
+
+Detail for steps 1 and 3 of [bench](bench.md): what each finding means for the player, the
+answer to it, and how to read a measurement that is missing. `inspect_model` answers
+`<path>: nothing obviously broken.` or `<path> — N finding(s):`, one bullet each, then the facts.
+
+## Finding to answer
+
+| Finding | What the player sees | Answer |
+|---|---|---|
+| a material at alpha 0 | nothing; the model loads and draws no pixel | `finalize_model`, or set `opacity = 1` and `transparent = false` on load and name it |
+| near-black with no texture | a flat black silhouette under any light | `finalize_model`, or a palette base colour on load; confirm the textures decoded |
+| no armature | a still mesh (fine for a prop) | a character that must move: `rig_model` (a donor, or regenerate with `animations`), or code motion |
+| a rig with no clips that drive it | "rigged" means bones exist; nobody posed them | `rig_model` with no donor on a biped, or code motion; never re-buy the mesh |
+| a mesh over 5% unweighted | that part stays in bind pose while the rest moves | if the limb was fused at generation, regenerate from a better concept; otherwise live with it and name it |
+| clips that animate nothing | nothing visible; megabytes of download | `finalize_model` with `keep_clips` naming the ones the code plays |
+
+## `audit_clips`, clip by clip
+
+| Reading | What it breaks | Answer |
+|---|---|---|
+| root motion | the clip walks the body and the game moves it again: double speed, a drift | zero the root in code, or stop moving the object while that clip plays |
+| a planted foot slides | skating on the ground | tie the clip's `timeScale` to move speed ([models](models.md)), or pick another clip |
+| holds one pose | a frozen character in that state | drop it from `keep_clips` and animate the state in code |
+| an expected name missing | the state never plays, with no error | rename in code to the file's clip, or author it with `rig_model` |
+| one name inside another (`run` in `run_fast`, `walk` in `walkback`) | a loose lookup (`includes`, a prefix, a regex) plays the wrong clip, with no error | give each a word of its own and look clips up by exact name; `funtools model clips <file>` lists collisions, free and local |
+
+Facts are reported, not judged: a standing humanoid's height over footprint reads well above 1,
+and a car is legitimately wider than tall.
+
+## Three-state, never two
+
+`-1` in any field means not measured: no armature to weigh against, alpha driven by a node, a
+file the bench could not read. It is no information: never a zero, never a pass and never a
+finding. "Could not be measured" is an answer about the file (not a model, a broken export), not
+an outage; the same bytes give the same answer.
+
+## Repairs
+
+Repairs write GLB and refuse to overwrite a `.gltf` or `.fbx`, so convert those to a `.glb` path
+first: GLB bytes behind a text content type would break a model that used to load.

package/plugins/cursor/skills/funpixel-3d/references/skin.md

@@ -0,0 +1,85 @@
+# Skin that reads, the same way across a cast
+
+A cast that feels like one world is part of what makes Hades memorable: its characters were
+sculpted from two base bodies and hand-painted to match one set of portraits, so the family reads
+before a word is said. A generated character often arrives with skin that is not quite skin: the face greyer than the
+hands, a blotch where the texture seam falls, one character warm and the next one waxy. Players
+read faces first, so it shows in every close shot. The bench fixes it as a pass, not by hand: it
+photographs the character from fixed views, a vision pass marks the bare skin, and the bench paints
+exactly those surfaces one tone, keeping their light and dark. Eyes, lips, brows and clothing keep
+their own colours because they are not skin-coloured.
+
+## Tools
+
+- `author_skin` takes a character you made and a `tone` (`#rrggbb`) and returns `model.glb` and
+  `proof.png` (front, face and both hands after the change). About 3 credits, held at 9.
+  `npx @funpixel/tools model skin <file|asset-id> --tone #8d5524`.
+- `retexture_model` gives the same mesh a new look: its four sides repainted by the image model
+  (your game's style lock when you name the game), projected back onto its own materials.
+  `npx @funpixel/tools model retexture <file> "a snowy winter coat" --game-id <id>`.
+- `inspect_model` and `render_model` before and after; `capture_view` in the game, or
+  `npx @funpixel/tools capture`.
+- `get_job` collects a finished job again by id.
+
+## The checklist
+
+1. **A cast table in the design note.** One row per character: its tone as a hex, and its
+   variants. One tone per character, reused for every variant, with characters differing on
+   purpose, keeps the cast one cast; a tone decided per job drifts, and the cast stops looking
+   like one game. Skin may be any colour the world allows: a green orc is still skin.
+
+2. **Inspect before painting** ([bench](bench.md)). The model faces +Z (the glTF front),
+   stands upright, and is not invisible or black. Views are taken from fixed sides: a character
+   lying down or facing backwards gets its back called "front", and the proof shows it.
+
+3. **Retexture before skin.** `retexture_model` repaints every surface, skin included, so a
+   skin pass made before it is lost. Make the variant first (its prompt names the clothes and
+   materials, the shape stays), then run `author_skin` on the variant with the character's tone.
+   Naming the game with `game_id` makes the repaint follow the style lock and anchors.
+
+4. **Run `author_skin` with the table's tone.** Omit `tone` only to even out the model's own
+   skin colour. A model with no bare skin (a robot, a knight in full plate) fails, not charged
+   for the result; that is an answer about the model, not a bug.
+
+5. **Read the result before the picture.**
+   - `marks` lists the cells the vision pass called skin, per view; empty `face` or `hand_*` on a
+     human is a miss worth looking at.
+   - `detail_texels_kept` above zero is expected: eyes, lips and brows inside a marked cell.
+   - A finding such as `31% of the textured surface no view saw` means the underside of the arms
+     or the soles kept their old colour.
+
+6. **Look at `proof.png`.** It is right when the face, both hands and the front read as one skin; the
+   eyes are still eyes; no sleeve or collar turned skin-coloured. A clothing edge painted by
+   mistake is a reason to run it again: a hand-painted texture drifts from the next run's.
+
+7. **Prove it in the game.** `capture_view` the character at the camera you ship, under the
+   game's own light and material. Skin that reads on the bench's flat light can go grey under
+   a dark scene: fix the scene light, not the tone per shot.
+
+8. **Hand back the cast table** with each character's tone, the variants made, and anything the
+   proof still shows (a missed ear, an unseen sole).
+
+## Worked example
+
+A four-person heist crew, all generated:
+1. Note: Ada `#8d5524`, Bo `#e0ac69`, Cy `#c68642`, Dee `#5c3a21`; Bo also gets a winter variant.
+2. `inspect_model` on each: all upright, facing +Z, textures present.
+3. `retexture_model` on Bo: "a quilted winter parka, wool scarf" with the game's `game_id`;
+   `proof.png` shows the parka on all four sides.
+4. `author_skin` on Ada, Bo, Bo-winter, Cy and Dee with their tones.
+5. Ada's result: marks on face, both hands and the front's forearms; `detail_texels_kept` 412
+   (eyes and lips). Dee's: `hand_r` empty — the proof shows a glove, which is right.
+6. In the game, the vault is dark: the four faces go grey. The key light is raised; the tones stay.
+7. Hand-back: the table with five tones, one variant, and "Bo-winter's soles kept the old colour
+   (no view sees them)."
+
+## Common mistakes
+
+- A new tone per job for the same character: its face changes between cutscenes.
+- Running `author_skin` before `retexture_model`: the repaint paints over the skin.
+- Hand-editing a texture after a pass: the next pass paints over the edit.
+- Judging the result from its numbers alone: `skin_share` cannot show a sleeve painted as skin.
+- Treating "no exposed skin" as a failure to retry: a fully clothed model has none.
+
+Where this comes from: cast consistency (one tone, one reference across characters) is adapted from
+scenario-labs/skills (MIT; THIRD_PARTY_NOTICES.md); the bench pass, its views and its checks are ours.

package/plugins/cursor/skills/funpixel-3d/references/skyboxes.md

@@ -0,0 +1,65 @@
+# Skies: the free one first, a painted one when it pays
+
+**The default is free.** The 3D starter's `sky.ts` draws the sky procedurally in one draw call:
+
+- a dome shaded from the horizon colour up to the top colour;
+- a sun or moon disc with a glow, placed where the key light comes from, so the light and the shadows
+  agree with the sky;
+- a soft band of cloud that drifts;
+- stars when the place is dark (`moonlit-spot`, or a fill under 0.6).
+
+Its colours come from the place's palette (`sky-top`, `sky-horizon`). The fog and the clear colour
+are the horizon colour too, so the world's edge melts into the sky. Change a place's sky by changing
+its palette and its light's `keyElevation` and `keyAzimuth`; there is no picture to make.
+
+## When a painted sky is worth paying for
+
+Pay for a sky only when it carries something the procedural dome cannot, and the player sees it most
+of the play:
+
+- a skyline with a story: a distant city, a mountain range you will climb, a lighthouse;
+- a painted style the rest of the world is drawn in;
+- a title or menu backdrop the cover also uses.
+
+When the camera mostly looks down at the ground, the procedural sky is the right one.
+
+## The paid route (the creator's choice, priced first)
+
+`generate_skybox` (MCP) or `npx @funpixel/tools gen skybox` makes an equirectangular panorama. Price
+it first and pass `confirm_cost` only when the creator allows. The steps:
+
+1. **Write the brief from the game's own files, not new words.**
+   - The palette: the place's `sky-top` and `sky-horizon` as named colours.
+   - The time of day: the light preset.
+   - Where the sun or moon sits: `keyAzimuth` and `keyElevation`.
+   - The style: the style lock in `assets/assets.json` or the GDD's look.
+   - The reference image, when the plan has one.
+   - One line for what the horizon holds.
+2. **Keep the horizon low and plain.** The fog meets the sky at the horizon, so the lowest band of
+   the panorama should be close to the `sky-horizon` colour. Detail belongs above it.
+3. **Size for the device.**
+   - Desktop: 4096 × 2048.
+   - Phone: 2048 × 1024, loaded by tier (`budget.tier()`).
+   - Anything bigger costs memory and buys nothing at play distance.
+4. **Check the seam before wiring it.** Put the left and right edges side by side (`look --sheet` on
+   the two crops): a visible step means regenerate or blend the seam. Check that the sun in the
+   picture is where the key light is; a sky lit from the left over shadows cast to the left reads
+   wrong at once.
+5. **Wire it as a background and a light source.**
+   - Load it with `TextureLoader` and set `mapping = EquirectangularReflectionMapping` and
+     `colorSpace = SRGBColorSpace`.
+   - Set it as `scene.background`, and through `PMREMGenerator` as `scene.environment`, so the
+     models pick up its colour.
+   - Hide the procedural dome (`stage.sky.mesh.visible = false`).
+   - Keep the fog colour equal to the panorama's horizon.
+6. **Keep the free sky as the fallback.** When the picture fails to load, the procedural dome stays
+   on and the game says so once in the console.
+7. **Measure it.** Run `funtools score --target` on the place with the plan's frame and
+   `funtools profile` on a phone. The sky should move `palette_light` without moving the frame time.
+
+## Free alternatives before paying
+
+- Poly Haven HDRIs (`find_material` / `get_material`, CC0) as `scene.environment` only, with the
+  procedural dome kept as the background. Real reflections, the game's own sky colours.
+- A painted backdrop cylinder (unlit, fogless) for a skyline. This is one texture of the place's
+  landmark range, the painted-target recipe's far band ([painted target](painted-target.md)).

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