@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-3d/references/painted-target.md

@@ -0,0 +1,184 @@
+# From a painted target to a 3D scene that holds up
+
+Why this exists: one game was built twice from one plan (1 Oct). In both builds the title and
+menus reached their painted targets, and the 3D walk stayed a flat, empty plane under a plain
+sky: a tech demo. In one build the cut-out hero's legs and arms drifted off the body as she
+walked. The walk is the first minutes of play, the stretch that decides whether people stay (the
+hook). Another game shows the way that worked: every look pass ended in fidelity strips at fixed
+framings, today beside the target, and the next pass worked on the largest gap. A racer (boats of
+boxes and cones handed back as finished) and a puzzle game (57 code primitives) show what happens
+when nobody puts the game beside the picture.
+
+## Read the target first (five minutes, written down)
+
+Before any code, measure the target frame and write the answers beside it in the GDD's place row:
+
+| Read | Example (one game, f3_walk) |
+|---|---|
+| Horizon height, share of frame from the top | 0.42 |
+| Hero height, share of frame | 0.22, standing left of centre |
+| Layers, near to far | crust and ruts · dunes · ridge silhouettes · relay on the horizon · planet · sky |
+| Light: direction, colour, the one warm accent | low from the right, cold violet; the cradle's amber window |
+| Haze colour at the horizon (pick it from the picture) | `#6d6a9c` |
+| What moves | dust in the wind, a crab crossing, the cradle's glow breathing |
+
+## Camera before scenery
+
+A wide lens flattens a painted scene and empties it. Start with a vertical FOV of 35 to 50
+degrees, then put the camera where the hero is the target's size:
+
+```ts
+// hero height h (m) fills share s of the frame's height at vertical fov f (degrees)
+const dist = h / (2 * Math.tan(THREE.MathUtils.degToRad(f) / 2) * s);
+```
+
+Pitch the camera until the horizon sits on the target's line, then check both framings: phone
+landscape 852×393 and desktop 1280×720. Three keeps the vertical FOV, so a wider screen shows
+more at the sides: give that extra width something to show (scatter, a second landmark), not
+bare ground.
+
+## Haze that is the sky
+
+The fog colour is the sky's colour at the horizon, exactly, or every far object sits in a grey
+box. Use the same value in three places: `scene.fog`, the bottom of the sky dome or gradient,
+and the clear colour.
+
+```ts
+const HAZE = new THREE.Color('#6d6a9c');
+scene.fog = new THREE.Fog(HAZE, 30, 220);   // far layers fade into the sky, not to grey
+renderer.setClearColor(HAZE);
+```
+
+Far things are lighter and lower in contrast than near ones (aerial perspective). If the far
+ridge reads as dark as the near rocks, the depth is gone.
+
+## Ground with height, in layers
+
+A flat plane under a painted sky is the tech-demo look. Build three bands:
+- **Near (0–20 m):** terrain with noise height (0.3 to 2 m), ruts or a path the hero follows,
+  instanced scatter thickest beside the path (rocks, tufts, debris; one `InstancedMesh` per kind).
+- **Middle (20–120 m):** dunes or ridges a few metres high that cross the view, so the eye
+  climbs over them; one or two landmarks that break the horizon (the relay, a wreck, a tower).
+- **Far (beyond the fog's far):** a backdrop: the target's far band (cut the top of a generated
+  environment plate) on a cylinder around the camera, unlit and fogless
+  (`MeshBasicMaterial`, `fog: false`), its horizon lined up with the camera's. Big sky objects
+  (a planet, a moon) are sprites on it or just inside it, moved with the camera so they never
+  get closer.
+
+Each band is lighter and lower in contrast than the one in front of it.
+
+## A light rig, not one lamp
+
+- `HemisphereLight` with the target's sky colour above and its ground bounce below.
+- A key `DirectionalLight` from the target's light direction; shadows on the hero and the near
+  band only (a tight shadow camera), never the whole world.
+- A rim light behind the hero, so a flat cut-out separates from the ground.
+- The one warm accent as a small `PointLight` with a slow breath (±15% over 2 to 4 s).
+- `ACESFilmicToneMapping`, sRGB output; tune exposure with the target beside the capture, never
+  alone.
+
+## Ambient motion from the first frame
+
+At least three things move on their own before the player touches anything: dust or motes
+drifting, grass or cloth swaying (a vertex shader or a few sine offsets), clouds or the backdrop
+sliding slowly, a creature on a path, a light that breathes, the hero's idle. `funtools life`
+counts what moves; `funtools hook` reads the first minutes and warns when they are still or empty.
+
+## Compare at fixed framings, every pass
+
+`npx @funpixel/tools compare --target design/first-look/f3_walk.png --view play` writes a strip,
+today beside the target, at both framings. Judge mood, light, value steps, the hero's size and
+how full the frame is. Keep the strips (before and after) in `design/look/`; a pass that cannot
+point at a closed gap in its strip did not close it.
+
+# A walk that reads as a person, in one piece
+
+The owner, after that game: "better walking animations, not like a robot; smooth movement like
+us humans." A robot walk is limbs swinging at a constant speed about fixed points while the body
+glides. A person's walk is the body falling forward and catching itself.
+
+## The human walk first
+
+- **Weight shifts side to side:** the hips move over the planted foot, a few centimetres each
+  step; the body is never centred between the feet for long.
+- **A gentle vertical bob:** lowest as the feet pass wide apart (the contact), highest as one leg
+  passes under the body; two bobs per stride, about 2 to 4% of the height.
+- **Hips and shoulders counter-rotate:** the hips turn toward the leg that swings forward, the
+  shoulders the other way; the head stays level.
+- **Heel to toe, and a planted foot never slides:** the heel lands, the foot rolls flat, the toe
+  pushes off. While planted it stays still on the ground; the body moves over it. Drive the
+  stride by distance walked, not time.
+- **Arms swing opposite the legs,** lagging a little; under a load (a pack frame, a cradle) the
+  hands brace the straps instead and the swing moves to the elbows and shoulders.
+- **Eased starts and stops:** two or three steps to reach speed and to settle, never a full
+  stride on the first frame.
+- **A lean that builds and settles:** into a slope, a turn or a weight, over a few tenths of a
+  second, then back; overshoot a little on the way back (follow-through on the head and the load).
+- **No linear angles:** every joint eases in and out (sine or a curve), never a triangle wave.
+
+These numbers are a preset in every starter's `src/motion.ts` (walk, run, sneak, carry, limp, old,
+child, a quadruped, a flyer's beat), with bounded dials, a stride driven by distance and a
+strike's timed phases in `src/strike.ts`: skill `funpixel-game-feel`, references/motion.md.
+
+## Two routes; pick what reads as a person on a phone
+
+**A cut-out rig done properly.** Cut the sheet into parts (`npx @funpixel/tools parts sheet.png`):
+hips, torso, head, upper and lower arms and legs, plus what the hero carries. One hierarchy
+(hips → torso → head and arms; hips → thighs → shins → feet), so a parent's turn carries its
+children.
+- **Pivots at the joints, never at a part's centre** (`geometry.translate(0, -len / 2, 0)` for a
+  limb hanging from its top).
+- **Overlap at every joint:** cut each limb 10 to 15% longer into its parent and draw it behind (a
+  0.001 depth step or `renderOrder`), so a bend never opens a gap.
+- **Face the camera as one.** Only the root turns toward the camera; parts stay in the root's
+  plane. Billboarding parts one by one is how limbs drift off the body.
+- **Secondary motion:** the head, hair, scarf and load follow the torso 60 to 100 ms late; a
+  stumble is one keyed curve of about 0.4 s (dip, catch, recover).
+- When the poses must change shape (turning, a big reach), whole-body pose flipbooks from the
+  locked reference sheet (6 to 8 walk frames, `parts --grid`), swapped by distance walked at 8 to
+  12 a second, keep identity best and cannot come apart.
+
+**A rigged 3D character with real walk clips.** `generate_3d_model` with animation (the Meshy rig
+and its clips, [models](models.md)) gives walk, run and idle made by motion data: weight,
+bob and counter-rotation come with it. Blend clips (`AnimationMixer` cross-fades of 0.2 to
+0.3 s), scale the clip's speed to the ground speed so feet do not skate, lean the root into
+turns. Cost is a paid model and a phone budget ([bench](bench.md)).
+
+Choose by a capture at phone size: the one that reads as a person walking at the hero's real
+size on screen wins, whichever took less work.
+
+## Many painted cut-outs, one draw call
+
+A painted world of props, creatures and folk drawn as one `THREE.Sprite` each costs a draw call
+each: one build reached 164 against its budget of 150 with about 200 cut-outs. The 3D
+world starter's `src/cutouts.ts` draws every cut-out that shares an atlas as one instanced mesh, so
+300 cut-outs are one draw call. Cut the figures with `npx @funpixel/tools cut sheet.jpg` (clean
+alpha, no paper or floor patches), build the atlas in the page with `atlasFrom([...pngs])` (or use
+a grid sheet as it is), then `cutouts(scene, atlas.texture, { cols, rows })`; each `add()` takes a
+place, a height, a tint, a frame, a mirror and a sway. The shader turns each one round the
+vertical axis to the camera and bends it from a planted foot (`sway`, `squash`): a breathing
+person, grass or a flag that bends, not a card that bobs. `walk(i, cycle, distance, moving)` steps
+a frame cycle by distance walked (`src/cutout-math.ts`), so a crab's scuttle or a walker's steps
+keep pace with the ground and stop when it stops. A cut-out that only slides or bobs reads as a
+picture on a stick: give it frames or a bend.
+
+## The cheap check
+
+```ts
+// test/rig.test.ts: sample the walk, the lean and the stumble; every part stays attached, a planted
+// foot stays put, the body bobs, and joints ease rather than swing at a constant speed.
+for (const clip of ['walk', 'lean', 'stumble']) for (let t = 0; t < 1; t += 0.02) {
+  rig.pose(clip, t); rig.root.updateMatrixWorld(true);
+  for (const p of rig.parts) if (p.parent) {
+    const gap = p.joint.getWorldPosition(a).distanceTo(p.parent.socketFor(p).getWorldPosition(b));
+    assert.ok(gap < 0.01, `${clip} ${t.toFixed(2)}: ${p.name} is ${gap.toFixed(3)} m off ${p.parent.name}`);
+  }
+}
+const walk = sampleWalk(rig, 50);                 // per step: hips y, foot world x/z while planted, knee angle
+assert.ok(walk.bob > 0.02 * rig.height, 'no vertical bob: the body glides');
+assert.ok(walk.plantedSlide < 0.01, `a planted foot slides ${walk.plantedSlide} m`);
+assert.ok(walk.kneeEase > 0.2, 'knee angle moves at a constant speed: a robot swing');
+```
+
+`kneeEase` is how far the angle's speed varies over the cycle (0 for a triangle wave). Then look:
+`npx @funpixel/tools capture --view play --burst 12` at phone size while walking.

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