@funpixel/tools 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,109 @@
+# Build a 3D level from a spec
+
+Use the Blender bench's declarative level spec when its geometry fits the task. Code-built,
+imported and manually authored levels are also valid; they still need usable routes, colliders
+and in-engine inspection. The bench returns a GLB with named parts plus proof pictures. Check
+those before relying on its markers, then test real traversal in the game.
+
+## Tools
+
+- `build_level` takes the spec and returns `level.glb`, `plan.png` (from above, north up) and
+  `view.png` (a raised corner), plus the marker list and the collider audit's findings. About 1
+  credit. Locally, free, on your own Blender:
+  `npx @funpixel/tools model --local level design/level.json`; hosted:
+  `npx @funpixel/tools model level design/level.json`.
+- `capture_view` and `inspect_scene` show the level inside the running game; locally
+  `npx @funpixel/tools capture` and `npx @funpixel/tools scene`.
+- `generate_3d_model` for a hero prop the kit does not have, then `optimize_model` to a budget.
+
+## The checklist
+
+1. **The place as a table before the spec.** Areas with sizes, which doors join which areas,
+   the routes a player needs to walk, and every named point the code will ask for: spawns, the
+   exit, pickups, enemy posts, checkpoints, lights. A point the code reads but the table never
+   declared is a point nothing checks.
+
+2. **Write the spec in `design/level.json`** (the JSON Schema is in the `build_level` tool entry).
+   Metres, +Y up, the ground plane X/Z; north is -Z. Plan numbers sit on the 0.25 m grid. Rooms
+   get walls and `openings` by side; yards, paths and water are open ground; `walls` are free runs
+   along X or Z (fences, partitions); `ramps` rise at most 40°, stairs (`steps` 2–64) at most 50°.
+   Names are identifiers (`a-z`, `0-9`, `_`), unique across the level; the validator refuses prose.
+   A marker's `rot` (degrees) turns it counter-clockwise seen from above. In the engine it faces
+   its local +Z (Three: `marker.getWorldDirection(v)`): 0 faces south (+Z), 90 east (+X), 180
+   north (−Z), −90 west. Give a door, portal or spawn the `rot` a player walks out of it along,
+   and read that direction from the marker instead of re-deriving it from the walls.
+
+3. **Blockout first: areas, walls, ramps, platforms and markers, no props.** Props placed before
+   the routes are walked get moved twice. A refusal names the field (`spec.areas[2].openings[0]: runs 5–7 m
+   along a wall 6 m long`): fix that number and build again. Look at `plan.png`: a green pin is a
+   spawn, red an exit, gold a pickup, magenta an enemy; a red ring means nothing stands under it.
+
+4. **Play it in the game before dressing it.** `npx @funpixel/tools reach` first names markers
+   or rooms nothing reaches. Load `level.glb`, place the player at the spawn, walk every route.
+   The `colliders` node is the collision shape, hidden: the art mesh as a collision shape snags
+   and tunnels. `capture_view` the spawn and each room.
+   A mesh level has no floor outside it, so a kill plane a few metres under its lowest floor that
+   respawns the player keeps a fall recoverable.
+
+5. **Dress it with the kit.** 18 prop kinds (crate, barrel, table, chair, bench, bed, shelf,
+   counter, pillar, lamp, tree, bush, rock, planter, fence, sign, chest, pot), placed by
+   `at`, `rot` and `scale`. Place props for the intended routes and encounters; preserve the required clearances.
+   `collide: false` for what a player walks through (bushes, lamps). Aim for zero findings: a
+   prop blocking a door or a marker inside a prop is a level the player cannot finish.
+
+6. **One material style.** The palette's ten roles (floor, wall, trim, ground, path, water, prop,
+   foliage, accent, ink) are every material the level has; take them from the design note's AD
+   rules or the game's style lock. `shading: "toon"` with `outline: true` is one supported look,
+   not a requirement. Its `funpixel_shading` marker enables a runtime material swap; the ink is
+   an inverted hull. Choose the supported material settings for the brief and keep changes
+   reproducible in the spec or documented runtime treatment.
+
+7. **Read markers by name, and fail loudly.** Each marker is an empty `marker_<kind>_<name>`
+   under `markers`. A lookup that misses throws with the names the level has, so a typo cannot
+   put the boss at the origin:
+
+   ```ts
+   const level = gltf.scene.getObjectByName('level_keep')!;
+   level.getObjectByName('colliders')!.visible = false;
+   const at = (kind: string, name: string) => {
+     const m = level.getObjectByName(`marker_${kind}_${name}`);
+     if (!m) throw new Error(`no ${kind} ${name}: ${level.getObjectByName('markers')!.children.map((c) => c.name).join(', ')}`);
+     return m.getWorldPosition(new THREE.Vector3());
+   };
+   ```
+
+8. **Prove it.** The plan and the view, then `capture_view` from the spawn at phone size. The
+   hand-back names the level file, its markers and anything the audit still reports.
+
+## Worked example
+
+A heist in a two-room cottage with a garden:
+1. Table: `hall` 6×5 m (door south, window east), `garden` 14×8 m, a fence with a gate, stairs up
+   to a `deck`; points: `spawn p1` in the garden, `exit door_out` on the deck, `pickup key` on the
+   hall bed.
+2. `design/level.json`: two areas, one wall run, one flight of six steps, one platform, three
+   markers; palette from the note (plaster walls, oak trim, moss ground).
+3. Blockout built: `plan.png` shows the three pins, none ringed.
+4. In the game: the player spawns in the garden, walks through the gate and up the stairs; the
+   kill plane catches a jump off the deck.
+5. Dressed: bed, table, shelf, two trees, a crate. The audit answers
+   `prop 'crate_1' blocks a door of 'hall'`; the crate moves 1 m east; built again, no findings.
+6. Hand-back: "`public/assets/models/cottage.glb`, markers p1, door_out, key; no findings."
+
+## Common mistakes
+
+- Colliding against the art: a character snags on every table leg and falls through foliage.
+- Colliders for the hero but not the camera: one game's shoulder camera entered walls six
+  times in one blind phone run and lost her; cast it against the walls and planes at the kit's faces.
+- Dressing before walking the blockout: every prop moved twice.
+- A marker the code asks for that the spec never declared.
+- Deleting the prop the audit named instead of moving it: the room loses what it was for.
+- Two areas at the same height overlapping: their floors flicker. Offset one, or make it a path.
+- Positions typed into game code instead of read from markers: the next build moves them.
+
+A scene that must match a painted target (camera, haze, layered ground, backdrop, light rig) and a generated 2D hero animated in 3D without coming apart:
+[painted target](painted-target.md). Light, dressing and places as data:
+[light and places](light-and-places.md); skies: [skyboxes](skyboxes.md).
+
+For Blender-to-engine boundaries and a requested Unity assessment, read
+[engine targets](engine-targets.md). Unity is not a shipped target.

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

@@ -0,0 +1,84 @@
+# Quality levels: one source, a cut per device
+
+One game decimated every model once for every device (the station kit 150,000 → 4,000
+triangles, characters → 13,000, props → 1,200–3,000, textures 4096² → 512–1024²). Next to its
+target frames it read flat and melted on a desktop that had headroom to spare, and the untouched
+generations survived only in a git-ignored temporary folder. Levels are the other way to do it:
+keep the source, cut `phone`, `desktop` and `high` from it, and let each device fetch only its own.
+
+## What a level is
+
+| Level | Triangles (× the class's phone budget) | Textures | Error bound |
+|---|---|---|---|
+| `phone` | ×1 | 1024 px | 2% of the mesh's size |
+| `desktop` | ×4 | 2048 px | 1% |
+| `high` | ×16 | 4096 px | 0.5% |
+
+The phone budgets are the bench's (the [bench](bench.md) skill, `references/budgets.md`):
+character 6,000, prop 2,500, set piece (kit pieces, walls) 9,000, thin-walled 7,000, food 1,500.
+A skinned model is a character unless you say otherwise; anything else is a prop, so a kit wall
+wants `--class set_piece` (or `kit`).
+
+The simplifier only ever removes triangles onto vertices that already exist: skin joints and
+weights are copied, never blended, so a rig still deforms; each mesh, node and material stays
+separate (severable pieces, emissive parts); morph targets are kept; UV seams stay seams. The
+error bound wins over the budget: a level that cannot reach its budget without melting stops and
+says why (the bound, or seams with nothing left to collapse). Treat that as information, not a
+failure: the level is the most the source allows at that quality.
+
+## Cutting them
+
+- Local and free: `npx @funpixel/tools optimize optimize-mesh <source.glb> --levels
+  phone,desktop,high [--class set_piece] [--out-dir public/assets/models] --write`. A dry run
+  (no `--write`) prints each level's triangles, texture size, bytes and time first.
+- In the Studio or a session: `optimize_asset` with `levels` (and `class`), or the asset panel's
+  "Quality levels" box. A generated model is cut from its kept source, not the shipped copy.
+- Either way you get `name.phone.glb`, `name.desktop.glb`, `name.high.glb` and
+  `name.levels.json` beside the model (or in `--out-dir`). The model file itself never changes, so
+  nothing that loads it today breaks. A rerun replaces the levels.
+
+Where the source lives is your call. A generation made with `gen model3d` keeps the provider's
+untouched GLB in `.funtools/sources/models/` (never published); the platform keeps its own copy
+beside the shipped one. Cut from that, never from a file you already decimated: a level cut from
+its shipped walker (18K triangles) reached only 16K on phone, because the detail it needed
+to trade was already gone.
+
+A `hero` generation (`style: "hero"`) is the source this is built for, cut down per device
+rather than generated low: 300K triangles on Meshy 7.1 (the default, 2048 px maps, about 160
+credits), 500K faces and 4096 px PNG maps with `engine: "hunyuan"` (about 135), or 500K
+triangles and 4096 px PBR maps with `engine: "rodin"` (about 240, static only). With
+`raw: true` the job's `model.glb` is that source itself, and no second copy comes back.
+
+## Loading one
+
+```ts
+import { loadLevel } from '@funpixel/sdk/assets';
+import { quality } from '@funpixel/sdk/device';
+
+const { asset: gltf, level } = await loadLevel('/assets/models/walker.glb', {
+  load: (url) => loader.loadAsync(url),          // the same GLTFLoader with its decoders
+});
+// A settings menu: quality.set('phone' | 'desktop' | 'high' | 'auto'), then reload the scene.
+```
+
+`loadLevel` fetches the small manifest, then exactly one GLB: the level `pickLevel()` chooses —
+the player's saved setting first; otherwise a touch-first device, 4 GB or less of memory, data
+saver or a low GPU gets `phone`; `high` needs a GPU known to be high
+(`levelSignals(renderer.getContext())` reads it) and 8 GB; everything else `desktop`. A phone never
+downloads the desktop set. No manifest (a model never cut) loads the plain file, as before.
+
+## Measured on that game's sources (29 Sep 2026)
+
+Release build of the engine on a shared M-series laptop; the time is mostly KTX2 texture encoding.
+
+| Source | Level | Triangles | Textures | Bytes | Time |
+|---|---|---|---|---|---|
+| kit wall, 500K, 61 MB | phone / desktop / high | 8,998 / 35,998 / 144,000 | 1024 / 2048 / 4096 | 1.0 / 3.6 / 11.6 MB | 5 / 14 / 160 s |
+| crate, 500K, 67 MB | phone / desktop / high | 11,876 (bound) / 15,600 (bound) / 39,998 | 1024 / 2048 / 4096 | 1.0 / 3.5 / 11.7 MB | 16 / 80 / 135 s |
+| walker source, 494K, 52 MB | phone / desktop / high | 12,082 (bound) / 24,000 / 96,000 | 1024 / 2048 / 4096 | 0.85 / 2.8 / 9.2 MB | 9 / 15 / 166 s |
+| kit wall, 150K, 18 MB | phone / desktop / high | 8,994 / 36,000 / 144,000 | 1024 / 2048 / 2048 (source) | 0.9 / 3.0 / 3.3 MB | 17 / 38 / 19 s |
+| rigged walker, 14.5K, 80 MB | phone / desktop | 9,327 (seams) / 14,512 | 1024 / 2048 | 1.6 / 5.4 MB | 13 / 37 s |
+
+"(bound)" is a level the error bound stopped above its budget: a detailed crate cannot become
+2,500 triangles inside 2% of its size, and a phone that must hold 2,500 wants a code-built crate
+instead. The rigged walker's phone level deforms like its source under the same pose.

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