@funpixel/tools 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,103 @@
+# The bench: from generated mesh to shipped model
+
+A 3D model can import cleanly, pass the build and still ship broken: invisible, a flat
+silhouette, frozen in bind pose, skating, or 100K triangles where a phone draws 6K. None of these
+throws an error, and an idle-pose screenshot hides most of them. The checklist below is the order
+that avoids rework, run before code depends on a model; take the steps the model needs. Each is
+cheap next to a regeneration (a bench step costs about 1 credit; a rigged textured model 145 or more).
+
+## Tools
+
+- `inspect_model` (free): findings first, then facts (meshes, vertices, bones, clips, megabytes,
+  longest axis, height over footprint).
+- `rig_model`: keys idle, walk, attack and death onto a bare biped rig, or fits a donor biped's
+  rig and clips onto an unrigged mesh. Its free rig check refuses, uncharged and with the reason,
+  a model that is not a biped, already animates, or has nothing to borrow.
+- `audit_clips` (free): plays every clip; length, root motion, a sliding planted foot, a clip
+  frozen in one pose, and your code's clip names matched against the file's.
+- `optimize_model`: pivot at the base, +Y up, metres, decimated to a shape class's
+  triangle budget for a phone or a desktop, keeping UV seams and skin weights.
+- `finalize_model`: repairs materials that draw nothing or black, drops clips not in
+  its keep list, and renders a front view and a contact sheet as the proof.
+- `render_model`: views round any model, a front view and a contact sheet.
+- `lod_model`: 1–4 levels of detail (`model.lod1.glb` onwards) for things drawn small and often.
+- `texture_stats` (free): each texture's size and GPU memory against the device's limit.
+- `inspect_scene` and `screenshot`: the model in the game, at the camera you ship.
+- `fracture_model` pre-cuts a prop into capped pieces; `get_job` collects a paid job again.
+- `build_level`: [level-spec](level-spec.md); `author_skin`, `retexture_model`:
+  [skin](skin.md).
+- `generate_3d_model` when the mesh itself is wrong (wrong subject, fused limbs); a joint or a
+  material is a bench repair at a fraction of the price.
+- Local: `npx @funpixel/tools gen inspect|rig|optimize-model|lod|render|finalize --asset <id>`,
+  `npx @funpixel/tools model --local inspect|render|finalize <file>` on your own Blender (free),
+  and `npx @funpixel/tools scene`. With none, check by eye in a glTF viewer and say so.
+
+## The checklist
+
+1. **Inspect.** `inspect_model` on each model before wiring it: a model that loads without an
+   error can still draw nothing. Act on findings
+   before facts; the answer to each finding is in [reading.md](reading.md).
+   `-1` means not measured: it is neither a zero nor a pass.
+
+2. **Rig check before you pay for motion.** A humanoid that must move needs bones and clips that
+   drive them; "rigged" on a download page means only that bones exist. No armature on a biped:
+   `rig_model` (with a donor if you have one). Not a biped (an animal, a slime, a car): animate
+   in code; the rig check refuses it for free, and that refusal is the answer about the model.
+
+3. **Audit the clips.** `audit_clips` with `expected` set to every clip name your code plays.
+   It passes when each expected name is found, nothing is frozen in one pose, and root motion is
+   known before the game moves the object itself. A sliding foot means the clip's speed and the move speed
+   disagree. Nearest-bone weights from `rig_model` are crude: watch it move.
+
+4. **Measure, then look.** Numbers cannot show a model upside down, inside out or facing
+   backwards; a picture cannot show unweighted vertices. Each covers the other's blind spot:
+   the findings, then `render_model`'s contact sheet.
+
+5. **Optimize to the device, after rigging.** `optimize_model` with the shape class and the ship
+   device. Rig first, then decimate (one pipeline that decimated first left the rigger 6% of the
+   vertices), and decimate before welding (welding first tears UV seams). Budgets, crowds and textures:
+   [budgets.md](budgets.md).
+
+6. **Finalize, and read the proof.** `finalize_model` with `keep_clips` naming exactly the clips
+   the code plays. Its front view and contact sheet show whether the model is visible from every
+   side, the right way up, in its colours. A success message is not a fix; the proof picture is.
+
+7. **LOD where it pays.** `lod_model` pays for anything many and small (crowds, debris, trees);
+   a hero the camera frames close rarely needs it.
+
+8. **Textures and the scene.** `texture_stats` with the ship device measures each model against
+   the phone's limits (2048 px a side; JPEG normal maps band; unused maps cost memory). Then, wired in, `inspect_scene` at the
+   busiest state for draw calls and texture memory, and a `screenshot` at the game's camera.
+
+9. **Repair beats regeneration** on price and on keeping what was approved. Regenerating pays
+   when the mesh is wrong, from a better concept image ([models](models.md)).
+
+10. **Report what you could not fix.** A limb that still drags, a clip replaced with code motion,
+    a model checked by eye only, a scene over budget: each goes in the hand-back by name.
+
+## Worked example
+
+A generated `golem.glb` is the boss of a phone game:
+1. `inspect_model`: `golem.glb — 2 finding(s): material 'Stone' has alpha 0 …; mesh 'Body' has
+   11% of its vertices unweighted.` Facts: 38,210 vertices, 24 bones, 3 clips, 2.10 MB.
+2. The 11% is the left arm, fused to the torso at generation; the concept had the arms against
+   the body. A new concept with the arms held away; the golem is regenerated (145 credits, said
+   and confirmed).
+3. `audit_clips` with `expected: ["idle","walk","slam"]`: `slam` missing, the file has `attack`.
+   The code plays `attack` now.
+4. `optimize_model` with `budget: "character"`, `device: "phone"`: 98K to 6K triangles.
+5. `finalize_model` with `keep_clips: ["idle","walk","attack"]`: the alpha finding repaired, 2 unused
+   clips dropped, 2.1 MB to 0.6 MB; the contact sheet shows it lit from every side.
+6. `texture_stats`: one 4096 px map, over the phone's 2048; resized. `inspect_scene` in the arena:
+   41 draw calls.
+7. Hand-back: "The first golem had a fused arm and was regenerated once; its slam uses the file's
+   attack clip."
+
+## Common mistakes
+
+- Trusting "rigged": bones can exist with no clip that moves them.
+- Reading `-1` as zero: an unmeasured weight fraction looks like a perfectly bound mesh.
+- Claiming a fix from a success message without the proof render.
+- Wiring the model in before the bench: all rework when the model is wrong.
+- A clip name typed from memory (`hurt` against `hit`): it loads and never plays.
+- Judging a car as broken because it is wider than tall: facts are reported, not verdicts.

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

@@ -0,0 +1,48 @@
+# Device budgets
+
+Detail for steps 5 to 8 of [bench](bench.md). Phone numbers are what our 3D games drew on an
+iPhone 11 class phone; desktop is four times that, an estimate nobody has profiled yet.
+
+## Triangles per model
+
+`optimize_model` decimates to these by the class you name (`budget`) and the `device`.
+
+| Class (`budget`) | What | Shipped on phones | Phone | Desktop |
+|---|---|---|---|---|
+| `food` | pickups, food, small loot | 800–1,500 | 1,500 | 6,000 |
+| `prop` | crates, barrels, small furniture | 1,500–2,500; small textures shattered below | 2,500 | 10,000 |
+| `thin_walled` | cups, bowls, rims, frames | 4,000–7,000; tore at 1,500–2,500 | 7,000 | 28,000 |
+| `set_piece` | stalls, buildings, backdrops | 6,000–9,000 | 9,000 | 36,000 |
+| `character` | anything rigged | 4,500–6,000 | 6,000 | 24,000 |
+
+A whole phone scene shipped at about 255K triangles; generation returns about 100K per model.
+
+The same table drives quality levels: `npx @funpixel/tools optimize optimize-mesh <glb> --levels
+phone,desktop,high --class <class>` (or `optimize_asset` with `levels` in the Studio) cuts all
+three from one source at ×1, ×4 and ×16 these phone numbers, so a desktop is not handed the phone
+cut. Detail and measured results: the [models](models.md) skill, its `references/levels.md`.
+
+## Crowds and distance
+
+- Many copies of one model: one instanced mesh per kind, one draw call. A skinned mesh cannot be
+  instanced in three.js; a crowd of rigged units either bakes its clips to a vertex-animation
+  texture or keeps a handful of animated leaders.
+- `lod_model` for anything drawn small and often. One of our crowd games drew its fodder as a
+  vertex-coloured level of about 400 triangles once a unit was under about 36 px on screen, which
+  cut its peak from 3.48M to 2.45M triangles a frame. Under about 30 px a clip cannot be seen, so
+  the far level can stay static.
+- Switch levels by on-screen size, not distance: one distance is 20 px on a phone, 60 on a desktop.
+
+## Textures
+
+- `texture_stats` with the ship device: phone at most 2048 px a side, desktop 4096; power of two;
+  no JPEG normal maps; nothing unused.
+- Size a texture to the pixels the model covers. Our football game's generated heads came back
+  at 4096 px and shipped at 512 px WebP, 71–260 KB each, twelve heads in 1.35 MB.
+
+## The scene
+
+`inspect_scene` (or `npx @funpixel/tools scene`) at the busiest named state. Draw calls should
+grow with the kinds of thing on screen, not the count of them; a count that grows with the crowd
+means a material or a mesh per copy (share them, or instance). Over budget: report it with the fix; cutting the look is the person's call, since pooling,
+instancing and atlases usually buy the frames back first.

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

@@ -0,0 +1,67 @@
+# The character library (3D)
+
+Rigged characters that already move, on one humanoid rig with one set of clip names. When one
+fits, it replaces a paid, slow generation and a rig run; when none does, generate your own (the
+steps in SKILL.md) — the library is an option on the shelf, not a rule.
+
+## What is on the shelf
+
+`list_characters` with `medium: "3d"` (free): `adventurer-3d`, `robot-3d`, `goblin-3d`, each a
+biped with these clips, measured on the bench when it was made:
+
+- from the rig run: `idle`, `walk`, `run`, `jump`, `attack`, `hit`, `death`, `wave`
+- authored on the same rig from a checked spec: `nod`, `hop`, `flinch`, `celebrate`
+
+`walk` and `run` are in place and carry `ground_speed_mps`: move the body at that speed (or set
+the action's `timeScale` to speed / ground speed) and the feet do not skate.
+
+## Using one
+
+- `get_character` (free; `npx @funpixel/tools character get robot-3d`) copies `model.glb`,
+  `clips.json`, `turntable.png` and the concept picture into `public/assets/characters/<id>/`.
+  The GLB is meshopt-compressed with plain textures: `GLTFLoader` with the meshopt decoder reads
+  it, no KTX2 transcoder needed.
+- The scaffold's `src/character.ts` (Three) loads it with an `AnimationMixer`: `play(name)`
+  cross-fades, one-shots play once and hold, `rate()` follows speed, `update(dt)` every frame.
+  `src/characters.ts` picks idle, walk or run from speed inside tuned ranges.
+- One-shots end where they start, on the idle stance, so any clip blends back to idle.
+
+## Your look, the same rig
+
+`restyle_character` (`npx @funpixel/tools character restyle robot-3d "a rusty scrap robot"
+--game-id <id>`) is `retexture_model` on the master: four sides repainted, projected onto its
+textures; the rig and every clip are kept, and the job is refused if a clip went missing. `palette`
+pins up to 8 colours. It changes the paint, not the shape: a knight is not a restyled robot.
+
+## Where it is weak
+
+- Humanoid bipeds only. A quadruped or a bird is a static mesh animated in code (SKILL.md step 1).
+- Three bodies, one proportion each: a very tall or very squat hero needs its own model.
+- The rig run's clips are generic. `author_motion` adds a wave, nod, hop, strike, flinch or
+  celebrate to any humanoid rig from a few dials; `retarget_clips` carries a library
+  character's clips onto your own rig (feet not locked: `audit_clips` it). A signature move (a
+  spell, a dance) is still made per game.
+
+## When the game poses its own skeleton
+
+A three.js horror game (29 Sep 2026) posed a code skeleton from its sim every frame, and
+its enemies lose limbs, so neither the library nor an auto-rig fit: their bones carry their own
+names, rolls and rest rotations, and none splits a body for severing. What it did instead, run in
+local Blender:
+
+- Bones built at joint positions read off an orthographic render, every rest rotation the
+  identity, so `bone.rotation.x = a` means what the old code joints meant.
+- Weights by capsule distance to each bone with a short blend into the neighbours; the bench's
+  own `fit_rig` notes that bone heat gives up on generated meshes.
+- A skin rather than rigid parts per bone: rigid parts open gaps at the hip and shoulder the moment
+  a joint bends.
+- Severing without losing the skin: the mesh cut on planes at shoulders, elbows, hips and knees,
+  each piece its own `SkinnedMesh` on the one skeleton, each opening capped with its own material.
+  Weights are a function of position only, so both sides of a cut match and the body bends as one
+  until `detach()` hides a piece and bakes its current pose into a static mesh for the debris.
+- A decoration generated once (a coral crust) and instanced on six bones, reshaped to hug each
+  limb, with its own material so the game can light it on its own.
+
+A trap it met: the `death` clip started standing, so a crawling enemy cross-faded upright and out
+of the shot when stomped. A death that starts from the crawl's pose fixed it: a clip has to start
+where the state that plays it leaves the body.

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

@@ -0,0 +1,47 @@
+# The concept image a model is built from
+
+Image-to-3D follows the picture it is given; text-to-3D invents its own design and drifts from the
+game's 2D art. What the picture needs, from our runs and Scenario's 3D skills (A-pose before a rig):
+
+- One subject, whole from top to bottom with a margin.
+- A straight-on front view, or the side the camera sees: a crowd seen from behind is modelled
+  from behind.
+- A plain light background and flat, even light; no base, no scenery, no text.
+- The game's frozen style words, so the model matches the sprites and the key art.
+
+For a character headed for a rig:
+
+- A-pose: arms held 30 to 45 degrees away from the body, legs apart, hands open and empty.
+- Fitted clothing, nothing cut off at the edges of the frame.
+- Bulky or long-coated figures fuse their limbs at generation and the rig fails.
+- The auto-rig skins anything held to the body: in our cast runs a hoplite's shield crumpled and
+  a minotaur's axe warped in the walk. Weapons, shields, trays and bags are generated as separate
+  static models and attached to the hand bone.
+- Long skirts, aprons and capes are skinned to the legs and arms and tear in the walk. Keep that
+  character static, or make the cloth a separate piece.
+
+For a prop (a building, a tree, a vehicle, a rock), the generators give it a face and arms unless
+told twice: "not a character, no face" was ignored three times in three in one run (a mill, a tree
+and an arch came back with faces). This held every time after: "An inanimate object only: NO face,
+NO eyes, NO arms, NO character anywhere."
+
+Pass the image's URL to `generate_3d_model` as `image_url`. Calling fal's Hunyuan 3D v3.1 pro
+yourself: a `face_count` below 40,000 is refused (422); cut the mesh down afterwards with
+`funtools optimize optimize-mesh` instead.
+
+## When the back matters: more views
+
+One picture leaves the back to the generator, and it invents one: a character's air tank came
+back as a backpack, a scarf as hair. Draw the back (and a side when it differs) in the same style
+and pass them with the front: `view_asset_ids: { back, left, right }` (images your jobs made) next
+to `image_asset_id` or `image_url`. The model is built from every view; the price does not change.
+
+## After it is made (optional)
+
+Image-to-3D can still drift from the picture: a cape dropped, a colour shifted, a horn on the
+wrong side. Render views headlessly (`npx @funpixel/tools model --local render hero.glb` on your own
+Blender, free; or the hosted `model render`), then `npx @funpixel/tools judge identity hero.glb
+--concept concept.png`: one seat on your own agent grades each view against the concept on
+silhouette, palette, key features and proportions and names the worst view per trait. Major drift
+fails; a part the angle hides is unseen, not lost. `judge report` reads it back. In our run a
+knight's own turntable held all four traits and another character's failed three.

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

@@ -0,0 +1,31 @@
+# Blender assets and engine targets
+
+Blender produces the world and model assets; the engine runs the game. Keep the gameplay
+contract, style rules, asset provenance and test criteria shared, with engine-specific import,
+input, measurement and export adapters.
+
+The shipped GDK initializes Pixi and Three.js projects. A Three.js level can use the local
+Blender bench or the hosted level tool, then load the resulting GLB and bind colliders/markers
+to game logic. Walk the undressed blockout before adding detail. Recheck the optimized model's
+scale, axis, material, animation and collision in the engine. A Blender turntable alone does
+not prove the game's room is navigable or that its phone controls work.
+
+For a requested Unity project, state that Unity is an assessment target, not a supported
+funtools scaffold or publish path. Reuse portable GLB, PNG and audio through a verified importer;
+a GLB is not natively imported with identical materials, animation or collider data, so test it.
+Choose and record the project's importer. Test metres, orientation, animation, colliders and
+marker semantics in a small scene. The hosted bench runs
+fixed authoring and inspection verbs only, never caller-supplied Python (a security boundary).
+
+A Unity Web export includes loader/runtime code, wasm and scene/data files. It needs its own
+build adapter, serving/compression checks and a state/input bridge for the GDK verifier.
+Native exports need their own input, testing and distribution path. A Vite
+build does not stand in for those checks, and a model import does not prove full engine support. There is no
+Unity init target or Unity checker command yet.
+
+One way to assess it: build one complete playable chamber using the same asset packet in Three.js
+and the Unity spike. Keep measured startup, memory/frame timing, input, win/reset and export
+results beside the build revision. Classify each path as tested, failed or not observed; add
+the engine to supported targets only after the end-to-end evidence exists.
+
+Export structure reference: [Unity manual](https://docs.unity3d.com/6000.0/Documentation/Manual/webgl-building.html).

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