@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-3d/references/light-and-places.md

@@ -0,0 +1,141 @@
+# Light, dressing and places: directing the world
+
+A world reads as shapes when it is evenly lit, sparsely dressed and the same everywhere. One heist
+game's plan was dark and moonlit, with spot-lit art and deep shadow, and its first build came back
+bright and evenly lit. Silt & Signal, by contrast, puts 42k instanced flowers along a clear road and
+gives each of its seven places its own light. The 3D starter (`funtools init --framework three-world`)
+directs all three from data, so you change values instead of writing a renderer:
+
+| Part | File | What you change |
+|---|---|---|
+| The light and the grade | `src/look.json` `"light"` | a mood preset and a few keys |
+| The places | `src/places.json` | one row per place: light, palette, ground, kit, landmark, road, density |
+| The machinery | `light-math.ts`, `light.ts`, `post.ts`, `sky.ts`, `surfaces.ts`, `dressing*.ts`, `stage.ts` | rarely |
+
+## The light block
+
+A preset is a whole light. A block names a preset and changes only a few keys:
+
+```json
+"light": { "preset": "moonlit-spot", "exposure": 0.9, "spots": 3 }
+```
+
+| Preset | Reads as | Key light | Fill floor | Spots | Grade |
+|---|---|---|---|---|---|
+| `dusk` | warm, low sun, long shadows | #ffc58f, 16° up | 1.0 | 0 | +sat, warm tint, vignette 0.3 |
+| `moonlit-spot` | dark room, lit art, deep shadow | cool, 0.8 | 0.7 | 3 warm pools | contrast 1.15, cool tint, vignette 0.55 |
+| `overcast` | soft and even, grey-green | 0.9, high | 1.8 | 0 | −sat, low contrast |
+| `studio` | clean showroom | white, 2.2 | 0.9 | 0 | neutral |
+| `noon` | hard sun, short shadows | 3.0, 72° up | 1.4 | 0 | +sat |
+| `dawn` | pink and cool, long light | 1.8, 10° up | 1.1 | 0 | rose tint |
+
+The keys are: `exposure`; `key`, `keyIntensity`, `keyElevation`, `keyAzimuth`; `fill`, `fillIntensity`;
+`rim`, `rimIntensity`; `sky`, `bounce`, `ambient`; `fogNear`, `fogFar`; `shadow` (`soft`, `hard` or
+`off`); `spots`, `spot`, `spotIntensity`; `saturation`, `contrast`, `tint`, `tintAmount`, `vignette`;
+`bloom`, `bloomThreshold`.
+
+Set one key with `npx @funpixel/tools look set light.exposure=0.85`, which validates the value. The
+validator refuses `ambient` under 0.15: a black floor is unreadable, not moody.
+
+Rules that come from our games:
+
+- **The fog is always the horizon colour.** It is also the scene's clear colour and the bottom of the
+  sky, so the edge of the world melts into the sky.
+- **One shadow map, on the key light only.** Its box follows the hero. Pools of light come from spots
+  without shadows. A light that is added or removed recompiles every lit material, so the rig makes
+  its spots once and dims the unused ones to 0.
+- **Spot the play first.** Pools go on the platforms nearest the play, then the landmark, then the
+  lanterns. That is the moonlit-spot look: the eye goes where the light is.
+- **The grade is CSS.** Saturation and contrast are a filter on the stage; the tint and vignette are
+  one overlay below the HUD. The compositor applies it, so a phone pays no draw call and no render
+  target, the HUD keeps its own contrast, and every capture shows it. The Pixi starter reads the same
+  keys (`gradeFromLook`).
+- **Bloom only where it is affordable.** It runs at half resolution on desktop and high, before the
+  tone mapping. A phone that runs long drops bloom first, then the shadows, then the pixel ratio
+  (`budget.ts` `shedders`).
+
+## Tiers: the phone stays at 60 fps
+
+`budget.tier()` decides by the same rule and storage key as `pickLevel` in `@funpixel/sdk/device`:
+the player's setting first (`funpixel.quality`), then the GPU (phone-class by GPU, never by pointer),
+memory and save-data.
+
+| Tier | Shadow map | Soft | Spots | Bloom | Dressing share | Instance cap |
+|---|---|---|---|---|---|---|
+| phone | 1024 | no | 1 | no | 0.5 | 6,000 |
+| desktop | 2048 | yes | 3 | yes | 1 | 16,000 |
+| high | 2048 | yes | 4 | yes | 1 | 24,000 |
+
+The frame budget stays 120 draw calls and 300k triangles. The starter's three dressed places measure
+70–90 calls and 40–170k triangles.
+
+## Dressing: a kit per place, by rule
+
+A place's `kit` is a list of slots:
+
+```json
+{ "role": "ground", "kind": "tuft", "density": 120, "scale": [0.7, 1.4], "clump": 0.7, "patch": 4, "roadside": 0.4 }
+```
+
+- **`role`** is one of four:
+  - `ground`: cover, which also dresses the play;
+  - `mid`: props, trees and rocks beyond the edge;
+  - `landmark`: one per place, at the road's end;
+  - `life`: lanterns and the like, which also dress the play.
+- **`density`** is instances per 100 m²; `count` is a fixed number.
+- **`clump`** (0 to 1) puts that share of the slot in patches `patch` metres across. Real ground cover
+  grows in patches; even noise reads as a carpet.
+- **`roadside`** (0 to 1) keeps a thing nearer the road's edges.
+- **The scatter is seeded, so a place looks the same every run.**
+  - It keeps the road (`road.width`) and every solid clear. The test is `onRoad` 0.
+  - Each thing stands at the lowest ground under its footprint (`footing`). The ground mesh and every
+    prop read the same `heightAt`, so nothing floats over the facets.
+  - A phone dresses half the small things.
+- **One InstancedMesh per kind.** 10k tufts are one draw call. Ground cover and life sway in the
+  vertex shader with the foot planted.
+- **Your own model replaces a stand-in.** A `public/assets/models/<kind>.glb` takes the kind's place
+  (its largest mesh, instanced) with no code. The built-in shapes are `tuft`, `reeds`, `flower`,
+  `rock`, `bush`, `tree`, `lantern` and `column`, in the place's palette.
+
+Density targets to start from (things per 100 m² over the dressed disc):
+
+| Place | Target |
+|---|---|
+| a meadow or square | 120–160 |
+| a grove | 100–120 |
+| a stone court or interior | 30–60 |
+
+Silt's first chapter is the ceiling to aim at: about 42k flowers and 782 landmark details, at 260–600
+draw calls on a desktop.
+
+## Places as data
+
+Write one row of `src/places.json` per `## Places` row of the GDD. Make the fields the plan's words:
+the room's name; its light as a preset plus the two or three keys the target frame asks for; its
+palette (`sky-top`, `sky-horizon`, `ground`, `ground-2`, `stone`, `accent`, `glow`); its `surface`
+(`grass`, `sand`, `cobble`, `flagstone`, `snow` or `moss`); its kit; its landmark; its road; its
+`density` target; and its `target` picture when the plan has one.
+
+One heist game's spec is the model for a row: each room has a size and shape, a material, an era, a
+light and a colour, and differs from the others in all five. For example:
+
+- "Long Gallery, oxblood velvet, cool moonlight from the lunette against warm gold picture lights"
+  becomes `moonlit-spot`, `spot` #ffd9a0, `key` #9db4d6, palette oxblood.
+- "Cabinet rooms, candle-warm and dark green" becomes `dusk`, `exposure` 0.75, `spots` 3, palette
+  slate-green.
+
+Winning a round travels to the next place. The views `place-<id>` enter each place directly, so the
+checks can set every place side by side.
+
+## Checking it (free, local)
+
+- **`funtools places`** enters every place and compares each pair in colour (ΔE), layout and light.
+  Alike in colour and light means one place repainted. The bar is at least 3 distinct places in the
+  first fifteen minutes.
+- **`funtools boxes` and `walk`** add a dressing check: things per 100 m² round the player, against
+  the place's target. It warns when the place reads bare (under 60% of its target), when dressing
+  stands on the road, and, with `--viewport phone`, when the frame is over the phone's budget.
+- **`funtools score --target <picture> --view place-<id>`** prints light moves in these keys. Example:
+  "the frame is 25 L* brighter than the target: change light.exposure ×0.4". Apply the top two or
+  three moves, then score again. Stop when `palette_light` holds or after five differences fixed.
+- **`funtools profile --views place-<id>`** and `--viewport phone` give the frame time and calls.

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

@@ -0,0 +1,111 @@
+# Generate and load 3D models
+
+A generated GLB is paid, slow and can load without an error while it renders flat grey, stands
+frozen or sinks into the floor; beside code-built props with their own materials it reads as a
+second game. This skill picks the lane per object, the cost, one shared look, and the loading
+contract. For the heroes (player, rivals, bosses: what the camera frames most) the default is the
+hero route and 3D look checklist in [hero-route.md](hero-route.md); the
+person's locked choices override it.
+
+## Tools
+
+- `generate_3d_model`: a prompt or image URL to a GLB. `style`: `standard` (textured, ~30K
+  triangles, ~160 credits), `hero` (static, 300K–500K, cut to levels) or `lowpoly` (grey
+  clay, ~45). `animations` rigs a humanoid biped; `engine` (`rodin`: hard
+  surface) and `raw` keep a close-up's detail ([hero-route.md](hero-route.md)). Long
+  runs return a job id.
+- `generate_image` makes the concept image.
+- `list_characters`, `get_character` (free), `restyle_character`: rigged characters that
+  already move; [characters.md](characters.md).
+- `get_material` (after `find_material`): free CC0 HDRIs, PBR sets, models.
+  `generate_skybox`: a 360° sky.
+- `get_job` collects a job by id. A timed-out job still runs, paid for: collect it, never
+  resubmit (that pays twice).
+- `inspect_model`, `optimize_model` and `finalize_model` check and ship the result (skill
+  [bench](bench.md), which owns the order and the device budgets).
+- No local 3D generation: `npx @funpixel/tools gen model3d` needs a paid key. Without one, build
+  it from grouped palette primitives, named as a stand-in in the hand-back.
+- `npx @funpixel/tools fidelity hero.glb front=ref.png end=end.png` scores a model against its
+  views, free. One view makes a slab, four fix the depth, projection plateaus near 73%; past it,
+  paint over a hand-blocked mesh ([hero-route.md](hero-route.md)).
+- `npx @funpixel/tools look --3d` reads what the heroes are made of (primitives or a loaded
+  model). Code-built heroes are a style only when funpixel.json `art3d` declares it with a reason
+  and a proof frame; otherwise they are stand-ins (the panel is told).
+- Models re-made only when their words change: `model3d` items in `npx @funpixel/tools assets gen`
+  (the `funpixel-art` pipeline reference).
+
+## Steps
+
+1. **A lane per object.** Generation is good at identity; code is exact about rules, numbers and
+   colours. A line per object in the design note ("head: generated; ball: code"), with its cost,
+   shows the spend first.
+
+   | Object | Lane |
+   |---|---|
+   | A humanoid a library character fits | `get_character`; `restyle_character` to match |
+   | Player, rival, boss, anything a camera frames close | `standard`, from a concept image |
+   | Humanoid biped that must move | add `animations` (idle plus one locomotion clip) |
+   | A body whose size is a stat, a kit in exact team colours | primitives in code; a generated head or face on top |
+   | Animal, blob, vehicle | static generated mesh; animate in code (bob, hop, spin, squash) |
+   | Crates, walls, balls, chains, simple hard-surface props | primitives in the palette, no generation |
+   | Crowds, fodder, debris | one model instanced many times, with a far LOD |
+
+2. **A concept image first** keeps the model on the game's art: text-to-3D invents its own
+   design. What the image-to-3D step reads best (one subject, whole, straight on, plain light
+   background, flat light, no base or text), what a rig needs (A-pose, empty hands, fitted
+   clothing) and back views: [concept-image.md](concept-image.md).
+
+3. **Price, then start early.** About 160 credits, rigged with walk, run and one more clip
+   included; two or more extra clips add 40 plus 24 each (up to 8 clips).
+   Say the price and pass `confirm_cost` only when the person allowed it. Models take minutes:
+   start them together, write the scene meanwhile. A hero: a [bake-off](bake-off.md).
+
+4. **Refusals can arrive with the result**, and the same prompt can pass minutes later. Retry
+   failed humanoids one at a time: parallel resubmits have all failed where serial ones passed.
+
+5. **Rig before decimating:** generate, rig, animate, then decimate and finalize on the bench
+   ([bench](bench.md); a rigger handed a decimated mesh got 6% of the vertices).
+   One cut for every device reads melted on a desktop: cut `phone`, `desktop` and `high` levels
+   from the kept source, free ([levels.md](levels.md)).
+
+6. **One material direction.** Generated and code-built objects belong together when they share
+   a direction; metal, glass and cloth need not share one shader. A toon ramp with an ink
+   outline is one proven recipe. Compare loaded models under the
+   game's light at phone size. Code: [three-loading.md](three-loading.md). Surfaces:
+   [textures.md](textures.md).
+
+7. **The loading contract** is in the same reference: each item is a way a model loads with no
+   error and still shows nothing, freezes or sinks (decoders, `mixer.update(dt)`, `cloneSkinned`,
+   posed bounds, grounding, clip speed, a capsule collider).
+
+8. **The bench before wiring** ([bench](bench.md)) catches what loads silently wrong: a clip
+   requested as `hurt` when the file says `hit` shipped and never played in one of our games.
+   A `__FPX_SELFTEST__` entry that checks each played clip name keeps it caught.
+
+9. **Paid work survives a failure.** A failed download is collected again with `get_job`; a
+   failed generation becomes a stand-in (the right silhouette in the palette), named in the
+   hand-back. A GLB that will not load is almost always a missing decoder.
+
+## Worked example
+
+A runner with a knight hero:
+1. Lanes in the note: knight generated and rigged; coins, crates and the track in code.
+2. `generate_image`: "Painted low-saturation fantasy style. One armoured knight, whole, front
+   view, A-pose, hands empty, plain light grey background, flat light, no text."
+3. "About 248 credits (textured, rigged, idle, run and jump). Go ahead?" Yes; `generate_3d_model`
+   with `image_url`, `animations: ["idle", "run", "jump"]`, `confirm_cost: true`.
+4. The call times out; `get_job` returns `knight.glb` and its clips, 98K triangles.
+5. Bench: all three clip names found, decimated to 6K, finalized; one toon material for all.
+6. Hand-back: "Knight rigged with three clips; the rest is code, one material."
+
+## Common mistakes
+
+- Text-to-3D for the hero: the model drifts from the 2D art. Build it from the concept image.
+- Generating a body whose size is a game rule: the hitbox and the mesh disagree.
+- Generated models and code props in two material directions: match them to the chosen one.
+- A figure holding a sword or wearing a long coat sent to the rigger: fused limbs, failed rig.
+- A shield or bag in a rigged character's hands bends in the walk; a skirt or cape tears.
+- `animations` on a dog or a slime: the rig step is skipped and the money buys nothing.
+- `root.clone()` for a second enemy: every copy shares one skeleton and stands frozen.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

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