@genex-ai/cli-demo 1.31.2 → 1.32.0-dev.650

package/templates/skills/genex-blender-scene/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: genex-blender-scene
+description: Compose a level, arena, interior, building or map — a SPACE of rooms, lanes, walls and sites that must relate — in a live Blender with `npx genex blender`, then export one GLB the game walks through. Use for places to move through, floor plans, or explicit Blender authoring including standalone assets. Probe the lane first; code is the fallback only when Blender was not explicitly required.
+---
+
+# Genex Blender · Scene
+
+Build the game's SPACE in a real Blender that answers over HTTP: write a Python
+script, run it, read the numbers, look at the four-view sheet, repeat — then
+export one GLB and load it like any model. The scene persists between steps, so a
+level grows the way a level is actually built: shell, then zones, then dressing.
+
+## When this lane owns the work
+
+- An explicit request to author or edit **in Blender**, even one standalone
+  asset. This overrides the default single-object route below. Keep Python
+  source under `blender/`, export the requested GLB and show it in a simple
+  browser preview; add gameplay only when requested. In hosted creation use
+  the CLI through Bash and open contact sheets with Read: the Blender MCP
+  server is not registered in the hosted harness.
+  If Blender is unavailable, report that limitation and keep the authored
+  scripts; the code fallback below is for requests that did not require Blender.
+
+- A **space**: a level, arena, interior, building, map, dungeon, station — several
+  rooms, lanes, walls or sites that must relate to each other, and a player who
+  moves through them.
+- A **floor plan or reference** to trace (a sketch, an ASCII plan, a photo of a room).
+- A **blockout**: the playable shape first, dressing later.
+
+Default routes when the player did not explicitly request Blender:
+
+- One recognisable object (a barrel, a cart, a statue) → `$genex-ai-model`.
+- One parameterized object placed many times with variation, or a stylized shader
+  material → `$genex-threejs-procedural-assets`.
+- The player's body, creatures, animation → `$genex-ai-character`,
+  `$genex-threejs-creatures`. Terrain from a heightmap → code.
+
+Mixing all three in one scene is normal: the Blender level is the architecture, a
+generated GLB is the hero piece, code is the repeated dressing.
+
+## Is the lane on? Probe by doing
+
+```bash
+npx genex blender scene
+```
+
+Read the answer literally — there are three:
+
+1. **A scene JSON prints** → the lane is on. Continue.
+2. `Warming up a Blender seat…` and then `The Blender seat is still warming up. Run
+   the same command again in a minute.` → **not done yet**, even though the command
+   exited cleanly. A GPU is booting for you (about 20 s on a warm pod, ~2 minutes
+   on a cold one, up to ~20 minutes on a host that has never pulled the image).
+   Between re-runs keep building everything that does not need Blender — the game
+   code, the markers plan, the scripts themselves — and run the command again every
+   couple of minutes; the wait never counts against you. Never read this line as
+   success, and never read it as failure.
+3. `The Blender lane is off on this stand`, `No Blender seat: fleet_full` or
+   `No Blender seat: pod_unavailable` → build
+   the same space **in code** with `$genex-threejs-procedural-assets`, say so in one
+   plain line to the player, and keep going. Do not wait, do not ask.
+
+The seat, once granted, is remembered in `.genex/blender-seat.json` — later
+commands are silent about it.
+
+## The loop
+
+Scripts are the level's source. Keep them in the project, one per zone:
+
+```
+blender/01-shell.py      walls, floor, towers
+blender/02-gatehouse.py
+blender/03-courtyard.py
+…
+```
+
+Run one:
+
+```bash
+npx genex blender exec --in blender/01-shell.py
+```
+
+Every run prints two things and writes one file:
+
+- **The numbers** — `objects N  meshes N  tris N  materials N  radius N`. This is
+  the gate. Before you run, know what the script should produce (twelve objects,
+  about 4k tris, radius ≈ 40); after, compare. A render judge is unreliable for
+  pass/fail; the numbers are not.
+- **The sheet** — `assets/blender/contact-sheet.webp`, four fixed views (front,
+  side, TOP, hero) from cameras derived from the scene bounds, so two steps compare
+  pixel for pixel. **Open it with your file-reading tool after every step.** The
+  TOP view is the floor-plan check; the hero view is the mood check. Nothing shows
+  it to you unless you look.
+- Script `print()` output comes back as stdout; a raised exception comes back with
+  its traceback AND the sheet of the half-built scene, which is usually where the
+  bug is visible.
+
+The Python namespace **persists between runs** (`bpy`, `bmesh`, `mathutils`,
+`math`, `random` are preloaded): define `mat()` and `box()` helpers once in the
+first script and use them in every later one. If a run says the service restarted
+and the scene was restored from a checkpoint, re-read the numbers — your last step
+may be missing; re-run that one script.
+
+Other verbs:
+
+```bash
+npx genex blender snap --mode wireframe   # topology; also normals | solid | lit
+npx genex blender scene                   # the full graph as JSON, when a number surprises you
+npx genex blender reset                   # empty scene (the namespace resets too)
+```
+
+Keep each step under about 90 seconds of Blender time: a script that loops
+hundreds of boolean cuts is killed at the deadline and the scene comes back from
+the last checkpoint. Split heavy work across scripts. A level is 8–15 steps, not 50.
+
+## Craft rules that decide whether the export works
+
+- **Metres.** Floor at `z = 0`, the map's centre at the origin. Blender is Z-up;
+  the export converts to Y-up, so the floor is the XZ plane in Three.js and a
+  Blender `(x, y, z)` lands at `(x, z, -y)`.
+- **Name everything** `<zone>_<thing>` (`gate_portcullis`, `hall_table_1`). Names
+  survive the export and are how the game finds parts.
+- **Materials: few and flat.** Six to eight for a whole level, one per surface
+  family (stone, dark stone, wood, roof, iron, glow). Set the Principled BSDF base
+  colour **and** `material.diffuse_color` — the sheet's fallback renderer reads the
+  second, and a scene that sets only the first exports with correct colours and
+  renders entirely grey. No image textures: they do not fit the export ceiling, and
+  an asset URL does not export.
+- **Repetition by loop, never by an unapplied modifier.** Crenellations, columns,
+  pews: a Python `for`. An Array modifier that is not applied is not in the GLB.
+- **Tri budget.** Keep the whole level under ~150k triangles and use 12–16 segments
+  on cylinders — phones load this file too. The export refuses above 6 MB; treat
+  that as "no longer a game asset", not as a limit to work around.
+- **Markers.** Empties export as named nodes: `bpy.data.objects.new("spawn", None)`
+  placed and linked into the scene collection, likewise `key_1`, `door_crypt`,
+  `patrol_1`. The level tells the game where things go; the game reads them with
+  `scene.getObjectByName("spawn")`.
+- **Lights stay in the game.** Blender lights do not export usefully; light the
+  level in Three.js (a hemisphere + a sun, point lights at torches and hearths).
+- **Collision is the game's.** Static level geometry gets Rapier trimesh colliders
+  per mesh — `$genex-threejs-physics-rapier`. If a mesh is too dense to collide
+  against, add a simplified `col_<zone>` box in Blender and keep the visual one out
+  of physics.
+
+A minimal first script, the shape every later one follows:
+
+```python
+import bpy
+bpy.ops.wm.read_factory_settings(use_empty=True)
+
+def mat(name, rgb, rough=0.85):
+    m = bpy.data.materials.new(name)
+    m.use_nodes = True
+    b = m.node_tree.nodes["Principled BSDF"]
+    b.inputs["Base Color"].default_value = (*rgb, 1.0)
+    b.inputs["Roughness"].default_value = rough
+    m.diffuse_color = (*rgb, 1.0)   # BOTH, or the sheet renders grey
+    return m
+
+def box(name, loc, half, m):
+    bpy.ops.mesh.primitive_cube_add(size=2.0, location=loc)
+    o = bpy.context.active_object
+    o.name, o.scale = name, half
+    o.data.materials.append(m)
+    return o
+
+STONE = mat("Stone", (0.46, 0.44, 0.41))
+box("yard_floor", (0, 0, -0.25), (35, 35, 0.25), mat("Ground", (0.30, 0.28, 0.24)))
+for sx, sy in ((1, 1), (1, -1), (-1, 1), (-1, -1)):
+    bpy.ops.mesh.primitive_cylinder_add(radius=3, depth=14, vertices=16,
+                                        location=(sx * 35, sy * 35, 7))
+    t = bpy.context.active_object
+    t.name = f"tower_{sx}_{sy}"
+    t.data.materials.append(STONE)
+print("shell:", len(bpy.context.scene.objects), "objects")
+```
+
+## Hero pieces from `genex model`
+
+```bash
+npx genex model "weathered stone knight effigy on a tomb, medieval"   # prints a URL
+npx genex blender import https://assets.genex.technology/generations/<id>/model-glb
+```
+
+`import` prints the object names it added and renders a fresh sheet; place and
+scale them in the next `exec` (`bpy.data.objects["…"].location = (…)`). Import
+when the piece must be composed WITH the architecture (a gate in a wall, a statue
+in a niche). When it is dressing, skip the import: drop a marker in Blender and
+load the GLB in Three.js at that marker — it keeps the level file small.
+
+## Export and load
+
+```bash
+npx genex blender export --out public/assets/level.glb
+```
+
+Load it like any GLB. The quality kit's rung ladder applies only to generated
+`/generations/` URLs, so this file loads as-is — the tri and material budgets
+above are what keep it phone-safe.
+
+```ts
+import { createGltfLoader } from "./controllers/quality/gltf-loader.ts";
+
+const gltfLoader = createGltfLoader(renderer);
+const level = await gltfLoader.loader.loadAsync("/assets/level.glb");
+level.scene.traverse((o) => {
+  if ((o as THREE.Mesh).isMesh) { o.castShadow = true; o.receiveShadow = true; }
+});
+scene.add(level.scene);
+const spawn = level.scene.getObjectByName("spawn");
+```
+
+Then colliders (`$genex-threejs-physics-rapier`), the player
+(`$genex-threejs-character-controller`), lights, and a real screenshot check
+(`$genex-threejs-visual-validation`). Record the level in `DESIGN.md`'s Assets as
+`local Blender build — scripts under blender/`, never a provider generation id.
+
+## Money
+
+A **hosted session's** seat bills a few credits per minute while it is held, idle
+or not, and ends with the session — there is no close command for it. So build
+the level in one sitting: shell → zones → hero pieces → export, then move on to
+the game. Batch changes into fewer, larger scripts; every step renders one sheet.
+
+At a **terminal with no Blender installed**, `npx genex blender seat` rents the
+same pooled GPU on your own credits (the price and the idle timeout print on
+open); it ends itself after 15 idle minutes, or run `npx genex blender release`
+when you are done. Prefer `npx genex blender serve` against your own Blender
+when one is available — the measurements favour it, and it costs nothing.
+
+## Troubleshooting
+
+- `payload_too_large` on export → fewer cylinder segments, delete faces the player
+  never sees, or export two GLBs (`--out public/assets/level-a.glb`).
+- The sheet is grey → `material.diffuse_color` was not set (see above).
+- `refused the seat token (401)` → the rejected cached grant has been removed.
+  In hosted creation, run `npx genex blender scene` to acquire a new seat and
+  inspect the restored scene before deciding whether to rerun the failed script.
+  At a terminal, run `npx genex blender seat` first. Recovery never automatically
+  replays scene changes; a replaced pod restores the latest saved checkpoint.
+- `seat_not_ready` → the pod is still booting; run again shortly.
+- The numbers are right but the top view is wrong → coordinates: `y` in Blender is
+  depth, and `scale` on a 2-unit cube is the half-size.

package/templates/skills/genex-game-director/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: genex-game-director
-description: The lightweight Genex request router. Read the latest game, tool, component, or focused-change request; ask only genuinely unresolved build forks; keep DESIGN.md current; and load only the Genex skills that the requested work actually needs. Use first for new work, resumed work, or whenever ownership is unclear.
+description: The Genex request router. Read the latest game, tool, component, or focused-change request; ask only genuinely unresolved build forks; keep DESIGN.md current; and load each owning lane BEFORE the first file of the subsystem it owns — only the lanes the work touches, never the whole pack, and never fewer than the work needs. Use first for new work, resumed work, or whenever ownership is unclear.
 ---
 
 # Genex Game Director
 
 The player chooses what to build and in what order. You route that request;
-the owning Genex skills control how their lanes run. Load only skills that
-change the requested result—never the whole pack by default, and never
-commission unrelated work because an old workflow listed it.
+the owning Genex skills control how their lanes run.
+
+Routing binds in BOTH directions: load only the lanes the requested work
+touches — never the whole pack by default, and never unrelated work because an
+old workflow listed it — and load a lane BEFORE the first file of the subsystem
+it owns. A matching row in the routing map is not a suggestion: each lane
+exists because writing that subsystem without it ships a known defect.
+Loading one lane never commissions another.
 
 **After any context compaction or session resume**, re-read the project's
 `AGENTS.md`, `DESIGN.md` when present, and the skill for the work you are
@@ -36,6 +41,13 @@ paths. Building, previewing, promoting and publishing use `genex preview` /
 
 Use the request in front of you, not the oldest description of the project.
 
+- **Explicit Blender authoring**, including a standalone prop, owns the
+  `$genex-blender-scene` lane. Keep the requested scope: Python scripts, an
+  exported GLB and a browser preview for an asset request. Do not invent
+  gameplay, a character controller or a game concept to justify the hosted
+  workspace. Blender in this sentence names the authoring tool; a kitchen
+  blender requested as a prop follows the ordinary asset rows.
+
 - **Clear focused request**—“work on the UI,” “fix movement,” “add one enemy,”
   “make this prop,” “publish this”—read the touched implementation and
   `DESIGN.md`, load only the owning skills, update `Now:`, and start. Do not
@@ -54,6 +66,10 @@ Use the request in front of you, not the oldest description of the project.
   invent or propose game concepts for them.
 - **Existing project** respects its renderer, physics, file conventions, and
   working systems unless the player asks to change them.
+- **A tagged reference** (source under `.genex/refs/<slug>/`) owns the
+  subsystem it was tagged for: read its `_map.md` and implementing files
+  before choosing a lane — it outranks the default lane, including the
+  vendored controllers, for that subsystem.
 
 Ask one decision at a time. Never ask the player to choose an SDK, engine,
 renderer, file layout, provider, or other implementation detail. Product
@@ -99,40 +115,69 @@ Never invent a provider generation ID for local code. Sections for gameplay,
 content, UI, world, assets, multiplayer, character/animation, tools, or
 modules are conditional on the request and existing project.
 
-## 4. Route to the owning lane
-
-Use the [routing map](references/routing-map.md) for exact ownership. The main
-Genex asset and runtime lanes are:
-
-- `npx genex model "<prompt>"`—a generated GLB (also `--image` from a
-  reference picture, `model segment` into named parts, `model rig` +
-  `model animate` for non-biped bodies) → `$genex-ai-model`
-- `npx genex texture "<prompt>"`—a generated surface → `$genex-ai-texture`
-- sky, horizon, time of day, weather mood—built in code, never generated; no
-  command and no skill owns it, so pick what this game needs
-- `npx genex sfx "<prompt>"` / `music` / `voice` →
-  `$genex-ai-sfx`, `$genex-ai-music`, `$genex-ai-voice`
-- `npx genex image "<prompt>"` / `video`—2D and motion art →
-  `$genex-ai-image`, `$genex-ai-video`
-- UI, HUD, and menu requests → `$genex-threejs-game-ui`,
-  `$genex-ai-hud`, `$genex-ai-menu`
-- `npx genex character`, `creature`, and their motion commands →
-  `$genex-ai-character`, `$genex-threejs-creatures`
-- movement and vehicles → `$genex-threejs-character-controller`,
-  `$genex-threejs-vehicle-controllers`
-- phone input and phone-survivable rendering →
-  `$genex-threejs-touch-controls`, `$genex-threejs-adaptive-quality`
-- structures, buildings, modular kits, repeated or varied environment pieces,
-  and parameterized objects — code is often the more efficient engine for
-  these → `$genex-threejs-procedural-assets`
+## 4. Routing map — load the owning lane before the first file
+
+For every subsystem the current milestone touches, find its row below, load
+that skill, and write the lane beside the work in `DESIGN.md` — a `Lane` cell
+on the module's row in the Modules table, or a `Lane:` line under `Now:` in
+focused or step-by-step work. `Lane: none — <why>` is the only way to write a
+subsystem with no lane. Then write the code. Never reconstruct a lane's API or
+vendored code from memory of another engine.
+
+| Work needed | Load |
+| --- | --- |
+| **your first `npx genex model` or `npx genex character` this session** — the command, what comes back, how to scale and ground it, and what to do when a lane is dead. One page, thirty seconds. The full lanes below are long; measured across 105 generation-lane invocations, 94% ran without the owning skill open, and placement is where that showed | `$genex-lane-card` |
+| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action, mouse-look, the screen-direction contract for hand-rolled steering/pan/look input signs, floating origins | `$genex-threejs-camera-direction` |
+| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, the player's body loader, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
+| **attacking, casting, aiming or reloading WHILE moving** — any action the legs must keep running under; a weapon carry stance over stock locomotion; a wind-up the character holds while walking | `$genex-threejs-character-controller` (`references/animations.md`, upper-body layering) |
+| dash, dodge, roll, blink, backstep, a lunging attack — any burst that moves the character itself | `$genex-threejs-character-controller` (`references/tuning-and-presets.md`, dash recipe) |
+| the game's own generated character—the player's body wherever a human body appears—or Meshy animation coverage beyond the stock pack: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` (first time this session: `$genex-lane-card`) |
+| a character/enemy needs motion the catalog lacks—a signature move, boss telegraph, death, full 8-way set, or the player's footage; free plan before spend | `$genex-ai-character` motion section + `references/motion-generation.md` |
+| remote player bodies in multiplayer—never hand-built primitives: the game's generated character when it has one, otherwise the player's `p.avatarUrl` VRM | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
+| enemies, NPCs, or creatures: rigged bipeds via `npx genex creature`; non-biped body plans (quadruped, flier, serpent, aquatic, multi-leg) via `npx genex model rig` + `model animate`; static plus procedural motion only for shapes with no body plan; collider, facing, hit reaction, death | `$genex-threejs-creatures` |
+| cars, drones, vehicle physics, gearbox, character↔vehicle enter/exit | `$genex-threejs-vehicle-controllers` |
+| playable on phones: joystick, virtual buttons, drag zones, genre touch recipes, rotate-device overlay | `$genex-threejs-touch-controls` |
+| phone-survivable rendering: device tiers, DPR/shadow/post budgets, runtime governor, generated-asset rungs, Quality picker, dispose-on-swap | `$genex-threejs-adaptive-quality` |
+| anything falls, collides, gets pushed, or needs colliders/events | `$genex-threejs-physics-rapier` |
+| launch/docking timelines, authored transform phases, springs, convergence, deterministic prop/debris motion | `$genex-threejs-procedural-animation` |
+| a level, arena, interior or map to walk through — the SPACE ITSELF: its ground plan, rooms, lanes, walls, paths and sites, from a description or a floor plan; a blockout. This row claims the space, never the things standing in it — the buildings, props, creatures and characters a player walks up to are separate rows below, and routing the space does not route them | `$genex-blender-scene` — probe the lane first (`npx genex blender scene`); when it is off, the same space is built as code via `$genex-threejs-procedural-assets` |
+| rebuild a reference prop, hard-surface object, modular decoration, or structural environment piece (kits, fences, walls, paving) as editable parameterized Three.js code — held to the asset bar at the end of this section | `$genex-threejs-procedural-assets` |
+| stylized/abstract shader-authored materials, the procedural/PBR material boundary | `$genex-threejs-procedural-assets` |
+| particles, trails, plasma, shockwaves, pooled bursts, and event effects | `$genex-threejs-procedural-vfx` |
+| stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
+| eye adaptation, tone mapping, output color, LUT grading, and proven static grain | `$genex-threejs-exposure-color-grading` |
+| fixed-view screenshots, input direction, facing, temporal and budget evidence | `$genex-threejs-visual-validation` |
+| **a model the player already has** — a `.glb` they exported, bought or made elsewhere: it is IMPORTED, never rebuilt. `npx genex model import <file.glb>` (free) for props and non-biped bodies (then `model rig`/`model animate`), `npx genex character import <file.glb>` for a humanoid that should walk (Uthana auto-rig, then `character animate --locomotion`) | `$genex-ai-model` · `$genex-ai-character` |
+| the default for a concrete object the player looks at up close: a generated GLB for a prop, vehicle, building, or object — from text or a reference image (`--image`); split into named parts (`model segment`); rig + animate any mesh (`model rig` / `model animate`). A space routed to code above does NOT settle these: a village's ground plan can be code while the forge you walk up to is generated | `$genex-ai-model` (first time this session: `$genex-lane-card`) |
+| generated surface or terrain texture with real-world UV scale | `$genex-ai-texture` |
+| sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code in the scene—there is no sky command and no owning skill, so pick the technique this game needs |
+| poster, sign, sprite, decal, reference sheet, or other 2D art | `$genex-ai-image` |
+| in-world motion art or another requested video | `$genex-ai-video` |
+| sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
+| requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
+| selling anything for platform coin: a shop, an item catalog, boosts, cosmetics, "make it earn"; also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
+| cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
+| drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
+| the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |
+| realtime multiplayer: movement sync, shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
+| players talking to each other by TEXT — chat, room chat, "let them type to each other" (`room.chat` + `npx genex controller chat`) | `$genex-threejs-multiplayer` |
+| players TALKING — voice chat, mic, "hear each other", proximity/positional voice (`room.voice` + `npx genex controller voice`; party-sized, max 6 per room — say that number out loud before building the feature) | `$genex-threejs-multiplayer` |
+| player identity, sign-in, guests, saves/progress, per-player state, shared persistent world, leaderboards—mandatory for every game | `$genex-threejs-embed-auth` |
+| the player EXPLICITLY asks to make an asset or publish something from their game as an asset for the free library | `$genex-asset-author` (`genex asset new`) — never offer this unprompted; no game duty routes here |
+
+Request-shape rules, working modes and the protected-lane handoffs stay in the
+[routing map](references/routing-map.md); read it when the request shape, not
+the subsystem, is what is unclear.
 
 For “make this image 3D,” ask **one** route question only when both results
 honestly fit: a generated GLB built from the picture itself
 (`npx genex model --image <path>`), or editable parameterized Three.js code.
 If the request says procedural, parametric, code-built, reusable variations,
 or names a GLB, start the corresponding route directly. An image alone never
-auto-triggers the procedural lane. Player bodies, rigged characters/creatures,
-and animation stay with their protected owners.
+auto-triggers the procedural lane. A floor plan, a room photo or a map sketch
+is a SPACE, not an object: it goes to `$genex-blender-scene` with no route
+question. Player bodies, rigged characters/creatures, and animation stay with
+their protected owners.
 
 If a procedural request has a private reference, use it locally and do not
 upload, publish, or commit it without explicit permission. If no reference was
@@ -141,16 +186,36 @@ supplied and creating one is part of the requested work, use the existing
 Assets row.
 
 The request sets the floor for the asset plan, never the ceiling: a world
-should feel dressed and alive, so plan the detail its genre implies — and pick
-the more efficient engine per object. Paid generation buys hero pieces (the
-player's character, key props, music); procedural code is the
-unlimited detail engine for structures, buildings, modular kits, and repeated
-or varied dressing (`$genex-threejs-procedural-assets` owns that lane) — and
-for the sky, which is never generated at all. Mixing
+should feel dressed and alive, so plan the detail its genre implies — and
+choose the engine per object, never per category. The bar is the same for both
+engines: whatever the player looks at must read as the thing it is, in this
+game's own style — a building as that building, a person as a person, a prop as
+that prop. A coloured box, a capsule or a flat grey block is not a finished
+version of any of them. Generation is the default route to that bar wherever
+code will not honestly reach it: the player's character, anything the request
+names, anything the player walks up to, enters, or interacts with, and the
+music and sound under it. Procedural code (`$genex-threejs-procedural-assets`)
+is a first-class engine for what is structural, repeated, distant, or
+parametric — terrain, sky (never generated), fences, paving, modular kits,
+filler — and for anything else only when the result meets the same bar and you
+have checked it in a capture before its row says `landed`. Write the route on
+each Assets row: the paid flow for generated pieces, the procedural flow with
+its local path for code-built ones — the table is where the per-object decision
+lives, and a table with no generated row records
+`Generation: none — <why code alone reaches the bar here>` beside it. Mixing
 both in one scene is the normal way to build, never a fallback. In focused
-work, stay inside the touched scope. Run independent planned generations with
-`--no-wait`, scaffold while they land, and preserve their IDs, URLs, and
-wiring state.
+work, stay inside the touched scope. Generate in batches you can finish. The first
+batch is the smallest set that makes the scene read — the player's body,
+whatever the request names, and the first thing they walk up to — enqueued
+together with `--no-wait` while you scaffold. Before a second batch starts,
+every id in the first is collected with `npx genex wait --all`, loaded from a
+file in `src/`, and seen in a capture. A batch begun while the previous one is
+still uncollected is how a game ends up with an asset library and an empty
+world. This is enforced, not merely advised: unshipped generations are counted
+and the generate commands refuse past a ceiling, which `npx genex preview`
+resets to zero. There is no total — preview between batches and generate as
+much as the game needs. Preserve every id, URL and wiring state across a
+compaction.
 
 ## 5. Execute by working mode
 
@@ -308,13 +373,14 @@ your pick. The announced pick carries the lane:
 
 `npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`
 
-Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+Meshy 7 Image-to-3D first produces an unremeshed high-detail model. Show its
 front, back, left, and right views and report its measured face count.
-Preserve that model in R2. The 10,000-face triangle remesh—not the high-detail
-source—is rigged and animated. In the default lane, the pick authorizes that
-remesh:
+Preserve that model in R2. A triangle remesh at the face budget you approve
+(10000-100000; 10000 for crowds, 20000-30000 for a third-person player
+body)—not the high-detail source—is rigged and animated. In the default lane,
+the pick authorizes that remesh:
 
-`npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 [--animation <action-id>…]`
+`npx genex character finalize <preview-id> --user-approved --approve-remesh <faces> [--animation <action-id>…]`
 
 When the player explicitly requested a custom character, keep the existing
 two stops: wait for their explicit candidate selection before Image-to-3D,

package/templates/skills/genex-game-director/references/design-contract.md

@@ -37,11 +37,15 @@ so it survives a long pause, context compaction, handoff, and remix.
   status flow `proposed → planned → generating (id) → landed (URL) → wired`.
   A landed asset is unfinished until wired or visibly cancelled. Preserve
   generation IDs, permanent URLs, local outputs, and wiring state across
-  compaction.
+  compaction. Every row shows its route: generated rows carry the paid flow;
+  code-built rows carry the procedural flow and a local path. A table with no
+  generated row at all carries `Generation: none — <why code alone reaches the
+  bar here>` beside it (build contract, law 22).
 - **Code-built procedural assets use their own truthful status flow:**
   `proposed → planned → building (blockout | detail | material | runtime) →
   landed (<local TypeScript path>) → wired`. They never invent a provider
-  generation ID. A generated reference image is a separate normal Assets row.
+  generation ID. `landed` on a code-built row means a capture at gameplay
+  distance showed it reads as the thing it is. A generated reference image is a separate normal Assets row.
 - Sections are request-driven. Gameplay, content, UI, assets, world,
   multiplayer, character/animation, tools, modules, and procedural assets
   appear only when the request or existing project uses them.
@@ -73,6 +77,7 @@ or explicitly re-scope it.>
 Working mode: <whole coordinated build | step by step | focused change>
 Now: ▶ <number/name of the current milestone or focused task>
 Done when: <one plain, observable condition for the current work>
+Lane: <$genex-… owning the current subsystem | none — why no row matches>
 1. <milestone> — ✅ → previewed
 2. <milestone> — ▶ in progress (<main agent | sub-agent>)
 3. <milestone> — ⏸ paused (<reason>)
@@ -121,7 +126,10 @@ Menu video: <generation id/URL, or the still standing in while it renders>
 | <asset> | <model/image/texture/…> | planned | — |
 | <asset> | <kind> | generating (<id>) | — |
 | <asset> | <kind> | landed → <URL> | yes/no |
+| <asset> | procedural-code | building (blockout) | — |
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
+Code-built rows: proposed → planned → building (…) → landed (<local path>) → wired.
+Generation: none — <why code alone reaches the bar in this game> (only when no row is generated)
 
 **HUD pipeline state (only while the sprites lane is running) — keep this
 current; it is how that pipeline survives a context compaction.**
@@ -152,9 +160,9 @@ Play-button rule: nothing connects before the click when a Play screen exists.
 Verification still open: <two-identity/netcode evidence>
 
 ## Modules (whole coordinated mode or another useful split only)
-| Module | Owns files | Built by | Done when |
-|---|---|---|---|
-| <request-derived stream> | <disjoint paths> | <parallel/serial + reason> | <observable result> |
+| Module | Lane | Owns files | Built by | Done when |
+|---|---|---|---|---|
+| <request-derived stream> | <$genex-… or none — why> | <disjoint paths> | <parallel/serial + reason> | <observable result> |
 
 ## Verification evidence
 - <preview URL/date and what it proves>

package/templates/skills/genex-game-director/references/routing-map.md

@@ -28,52 +28,23 @@ copy demo architecture.
   3D,” ask one plain question: normal generated GLB, or editable parameterized
   Three.js code? Explicit `GLB`, `procedural`, `parametric`, `code-built`, or
   `variations` language chooses directly.
+- **Tagged reference:** source under `.genex/refs/<slug>/` owns the subsystem
+  it was tagged for — read its `_map.md` and implementing files before choosing
+  a lane; it outranks the default lane, vendored controllers included.
 
 ## Route by system
 
-| Work needed | Load |
-| --- | --- |
-| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action, mouse-look, the screen-direction contract for hand-rolled steering/pan/look input signs, floating origins | `$genex-threejs-camera-direction` |
-| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, the player's body loader, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
-| **attacking, casting, aiming or reloading WHILE moving** — any action the legs must keep running under; a weapon carry stance over stock locomotion; a wind-up the character holds while walking | `$genex-threejs-character-controller` (`references/animations.md`, upper-body layering) |
-| dash, dodge, roll, blink, backstep, a lunging attack — any burst that moves the character itself | `$genex-threejs-character-controller` (`references/tuning-and-presets.md`, dash recipe) |
-| the game's own generated character—the player's body wherever a human body appears—or Meshy animation coverage beyond the stock pack: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
-| a character/enemy needs motion the catalog lacks—a signature move, boss telegraph, death, full 8-way set, or the player's footage; free plan before spend | `$genex-ai-character` motion section + `references/motion-generation.md` |
-| remote player bodies in multiplayer—never hand-built primitives: the game's generated character when it has one, otherwise the player's `p.avatarUrl` VRM | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
-| enemies, NPCs, or creatures: rigged bipeds via `npx genex creature`; non-biped body plans (quadruped, flier, serpent, aquatic, multi-leg) via `npx genex model rig` + `model animate`; static plus procedural motion only for shapes with no body plan; collider, facing, hit reaction, death | `$genex-threejs-creatures` |
-| cars, drones, vehicle physics, gearbox, character↔vehicle enter/exit | `$genex-threejs-vehicle-controllers` |
-| playable on phones: joystick, virtual buttons, drag zones, genre touch recipes, rotate-device overlay | `$genex-threejs-touch-controls` |
-| phone-survivable rendering: device tiers, DPR/shadow/post budgets, runtime governor, generated-asset rungs, Quality picker, dispose-on-swap | `$genex-threejs-adaptive-quality` |
-| anything falls, collides, gets pushed, or needs colliders/events | `$genex-threejs-physics-rapier` |
-| launch/docking timelines, authored transform phases, springs, convergence, deterministic prop/debris motion | `$genex-threejs-procedural-animation` |
-| rebuild a reference prop, hard-surface object, modular decoration, or simple environment piece as editable parameterized Three.js code | `$genex-threejs-procedural-assets` |
-| stylized/abstract shader-authored materials, the procedural/PBR material boundary | `$genex-threejs-procedural-assets` |
-| particles, trails, plasma, shockwaves, pooled bursts, and event effects | `$genex-threejs-procedural-vfx` |
-| stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
-| eye adaptation, tone mapping, output color, LUT grading, and proven static grain | `$genex-threejs-exposure-color-grading` |
-| fixed-view screenshots, input direction, facing, temporal and budget evidence | `$genex-threejs-visual-validation` |
-| a generated GLB for a concrete prop, vehicle, building, or object — from text or a reference image (`--image`); split into named parts (`model segment`); rig + animate any mesh (`model rig` / `model animate`) | `$genex-ai-model` |
-| generated surface or terrain texture with real-world UV scale | `$genex-ai-texture` |
-| sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code in the scene—there is no sky command and no owning skill, so pick the technique this game needs |
-| poster, sign, sprite, decal, reference sheet, or other 2D art | `$genex-ai-image` |
-| in-world motion art or another requested video | `$genex-ai-video` |
-| sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
-| requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
-| selling anything for platform coin: a shop, an item catalog, boosts, cosmetics, "make it earn"; also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
-| cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
-| drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
-| the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |
-| realtime multiplayer: movement sync, shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
-| players talking to each other by TEXT — chat, room chat, "let them type to each other" (`room.chat` + `npx genex controller chat`) | `$genex-threejs-multiplayer` |
-| players TALKING — voice chat, mic, "hear each other", proximity/positional voice (`room.voice` + `npx genex controller voice`; party-sized, max 6 per room — say that number out loud before building the feature) | `$genex-threejs-multiplayer` |
-| player identity, sign-in, guests, saves/progress, per-player state, shared persistent world, leaderboards—mandatory for every game | `$genex-threejs-embed-auth` |
-| the player EXPLICITLY asks to make an asset or publish something from their game as an asset for the free library | `$genex-asset-author` (`genex asset new`) — never offer this unprompted; no game duty routes here |
+The ownership table lives in **SKILL.md §4** so it is in front of you the
+moment the director loads, rather than behind a link you have to decide to
+open. This file keeps the request-shape and working-mode rules; read it when
+the shape of the request, not the owning subsystem, is what is unclear.
 
 ## Request-sized execution
 
 ### Focused work
 
-Load only the owning row or rows, preserve the current architecture, implement
+Load the owning row or rows — before the first file of each subsystem, and
+none beyond the work — preserve the current architecture, implement
 the requested result, and run its relevant check. UI work routes directly to
 UI; movement routes directly to movement; publishing routes directly to the
 existing publish flow. Do not add a concept, unrelated asset batch, full-game
@@ -129,14 +100,28 @@ flow and state what remains.
 
 ## Procedural assets (code-built)
 
-Use `$genex-threejs-procedural-assets` whenever code is the more efficient
-engine for an object — structures, buildings, modular kits, repeated or varied
-props, parameterized objects — or when the player asks for procedural,
-parametric, or code-built work. It is a first-class lane, not a fallback, and
-mixing it with generated GLBs in one scene is the normal way to build a
-detailed world. An image alone still doesn't decide the route (ask the one
+Use `$genex-threejs-procedural-assets` whenever code will honestly make the
+object read as the thing it is — structural pieces, modular kits, repeated or
+varied props, parameterized objects — or when the player asks for procedural,
+parametric, or code-built work. It is a first-class lane, not a fallback, held
+to the same bar as a generated GLB, and mixing it with generated GLBs in one
+scene is the normal way to build a detailed world. An image alone still doesn't decide the route (ask the one
 route question when both honestly fit), and never use it for player bodies,
-rigged characters/creatures, or animation.
+rigged characters/creatures, or animation. An OBJECT is this lane's unit; a
+SPACE the player moves through — a level, an interior, a whole building — is
+`$genex-blender-scene`'s, which falls back to this lane when the Blender lane
+is off on the stand.
+
+**That fallback claims the SPACE, never the things standing in it.** MEASURED
+2026-09-03: a village brief matched the space row, the Blender lane was off, and
+the whole world — every house, the forge, the well, and five villagers — was
+built as code with no Assets table written and not one generation run. Routing
+the ground plan to this lane is not a decision about the forge the player walks
+up to, the smith they talk to, or the props they pick up: those are their own
+rows (`$genex-ai-model`, `$genex-ai-character`, `$genex-threejs-creatures`) and
+they are still decided per object against the asset bar. A village's layout in
+code with generated buildings and characters standing on it is the normal shape,
+not a contradiction.
 
 - Prefer a supplied reference. A private attachment stays local unless the
   player explicitly permits upload, publication, or commit.