@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-3d/references/hero-route.md

@@ -0,0 +1,104 @@
+# The hero route and the 3D look
+
+The default path for every hero of a 3D game: the player, the rivals, the bosses, and the key
+prop the player stares at. A choice the person locked (a code-built toy style, a budget of zero
+credits, a library character) overrides it. Environment and background may stay procedural.
+
+Why it exists: a phone racer was offered `generate_3d_model` in three creator rounds
+and never called it. Its boats and world were boxes, cones and extrusions; stills of tidy
+primitives read as a style, and the blind panel scored the look above 7 while the owner saw "a
+shapes game". Another game, rooms of code geometry, reached 7.28 against Monument Valley 2's 8.60.
+
+## Declared, proven, or named
+
+`npx @funpixel/tools look --3d` reads what the heroes are made of: primitive constructors by
+kind, hand-built buffers, a loaded model, the models shipped under `public/`, and with a build,
+each hero node live (meshes, triangles, screen share). Its line reaches the critic seats as a
+numbered fact. Three honest states for a code-built hero:
+
+- **Declared and proven.** funpixel.json:
+  `"art3d": { "heroes": "procedural", "why": "paper-fold toy boats: the facets are the look", "proof": "design/target.png" }`.
+  The proof frame shows the style at its best; the target frame (skill `funpixel-art`)
+  usually serves. A declaration without a proof on disk proves nothing.
+- **Named stand-ins.** `"art3d": { "stand_ins": ["skiff hulls: code until skiff.glb passes judge identity"] }`,
+  and the same words in the hand-back.
+- Neither: `look --3d` fails and the hand-back check asks for the names.
+
+## The route, per hero
+
+1. **Pick the heroes by what the camera sees most.** A chase camera shows a boat's stern and
+   flank for most of a race; a puzzle camera shows the whole diorama from one high angle. Write
+   one line per hero: its view, its size on a phone screen, the lane (this skill's lane table).
+2. **A multi-angle concept, approved.** One `generate_image` per hero from the most-seen angle
+   first, then front and side on the same sheet or as siblings, all in the frozen style words;
+   plain background, flat light ([concept-image.md](concept-image.md)). Approval is the person's
+   yes, or the concept set against the target frame. Rivals of one family share a concept and
+   differ by trim and colour, which is one model and a material swap, not four generations.
+3. **Generate from the image.** `generate_3d_model` with `image_url` and `style: "standard"`;
+   price first, `confirm_cost` on a yes. Start every hero at once; write the scene meanwhile.
+   `style: "hero"` is for a static hero the camera frames close, cut to quality levels after
+   ([levels.md](levels.md)): 300K triangles on Meshy 7.1 (the default engine, 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; the hard-surface take:
+   one game kept Rodin's crate, door, lockers and bell). A rigged hero stays `standard`, and
+   never Rodin (it has no rig).
+
+   Rodin 2.5 (`engine: "rodin"`) runs only when named and never falls back: static only (with
+   `animations` it is a 400), the front and every view in one job, `standard` 50K triangles and
+   2048 px PBR maps (~80 credits), `hero` 500K with 4096 px maps (~240), `lowpoly` 8K triangles,
+   untextured (~20). Pick it for machines, doors, crates and set pieces; Meshy 7.1 stays the
+   character engine (the most faithful from every side in the 4 Oct bake-off). For a first-person viewmodel or a close-up character, add
+   `raw: true`: the engine's file untouched (the optimized copy clamps maps to 1024 px), then
+   cut it to the device yourself. `npx @funpixel/tools gen model3d --image-asset front.png
+   --back-asset back.png --style hero --engine hunyuan --raw` does all of it from the CLI.
+   **Fidelity against the views** (one game's hero, 10 Oct 2026, `npx @funpixel/tools fidelity`):
+   from one view the model is a slab whose end views score ~46%; four views (front, back, both
+   ends) fix the depth. Projecting the views onto the mesh was the largest single gain (a profile
+   84 → 91%), and generation plus projection plateaued near 73% (Hunyuan from four views 72.8%,
+   Meshy hero 73.3%: Meshy keeps profiles sharper, Hunyuan the ends). Check the views agree
+   first: `fidelity` names views no one object can match (the hero's drawings drew the drum two
+   sizes, which capped even a hand-built mesh at ~74%). For 95% (reached, 95.0% mean), the studio
+   order: block the shape in Blender from primitives measured off the views (6.4K faces); render
+   the plain mesh in four orthographic views; `gen edit` each render into a paintover in the house
+   style ("keep the silhouette and every part exactly", from the cast master, ~5 credits each);
+   project the paintovers back and bake; score against the paintover sheet, which becomes the
+   master only on the person's yes. Score at the references' own size (512 px against 1024 px
+   references cost ~2 points), project every visible face (facing dot 0.08, not 0.35: +0.9), add
+   `--outline` for inked views (+0.4), `--own-axes` for a mesh built square to its axes, `--roll`
+   for a deep model squared onto its side.
+4. **Bench it** ([bench](bench.md)): `inspect_model`, `rig_model` when a biped must move,
+   `optimize_model` to the budget below, `finalize_model`, then `render_model` for a turntable.
+5. **Judge identity against the concept:** `npx @funpixel/tools judge identity hero.glb --concept
+   concept.png`. A major drift (lost fin, wrong colour, wrong proportions) is a regeneration from
+   a clearer image or a bench repair, not a pass.
+6. **Load it right** ([three-loading.md](three-loading.md)): `GLTFLoader` with the decoders the
+   file needs (meshopt, Draco, KTX2), the root named, grounded by its posed bounds, one clone per
+   copy (`cloneSkinned` when rigged), rivals tinted by cloned materials.
+7. **Prove it:** `look --3d` passes, captures at the most-seen view, `npx @funpixel/tools profile`
+   at the busiest moment.
+
+The environment may be procedural when it shares one style source with the heroes: a palette
+module and one material factory that both the code-built world and the loaded models' retuned
+materials come from.
+
+## The 3D look checklist
+
+Starting numbers, not rules; each one is checkable in a capture or a profile.
+
+| Lever | Starting point | Check |
+|---|---|---|
+| Environment map | `scene.environment` from `PMREMGenerator` on `RoomEnvironment`, or a CC0 sky from `get_material`; `envMapIntensity` 0.3–1 | PBR metal is not black; highlights exist |
+| Tone mapping | `ACESFilmicToneMapping` or `AgXToneMapping` for PBR; Neutral when the palette must stay true; none for flat toon; exposure 0.9–1.1; `outputColorSpace` sRGB | whites are not milky, darks not crushed |
+| Racer camera | chase, 5–7 m behind and 1.5–2.5 m up for a 4 m vehicle (about 0.4–0.6 of its length), looking a few metres ahead; FOV 60–70, up to +10 with speed; damped follow | the vehicle fills 15–25% of a phone frame; the road ahead reads |
+| Puzzle diorama | orthographic, or FOV 20–35 from 30–45° above | every piece of the room in one frame |
+| Third person / platformer | 6–10 m behind, 2–4 m up, FOV 50–60 | the next jump is visible |
+| Top-down arena | 55–70° pitch, FOV 40–50 | the player and the nearest threat on screen |
+| Fog | `THREE.Fog` in the palette's horizon colour; near about a third of the view distance, far just inside `camera.far` | distance fades into the sky, never to a clip line |
+| Sky and ground | a gradient dome, a generated skybox or a CC0 sky; ground with texture or vertex-colour variation; three depth layers (near props, middle, far silhouettes) | no flat void or single-colour plane |
+| One material rule | every material from one palette module and one shading model; loaded models' colours and roughness retuned to it | a loaded hero and a code prop look lit by one world |
+| Hero budget | about 15K triangles in at most 8 material batches for a hero vehicle (the figure OpenAI's Astra write-up gives, a guide); 6K for a rigged phone character ([bench](bench.md), its budgets reference) | `look --3d` live counts, `funtools scene` draw calls |
+| Scene budget | a phone scene near 250K triangles shipped; draw calls that grow with kinds of thing, not their count | `npx @funpixel/tools profile` p95 frame time at the busiest view |
+| Shadows | one directional shadow map (1024–2048) or a blob under each actor | every actor touches the ground |
+
+Measure before and after each lever at the same view and seed: a change that only moved the
+numbers the panel cannot see is not worth its frame time.

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