diff --git a/MEMORY.md b/MEMORY.md index 95c9a90..ab7f56d 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -178,10 +178,10 @@ canonical implemented-features list in `docs/development-status.md`. The playable build covers the three venues, tutorial/campaign/checkpoints, the 0.9.3–0.9.6 polish/texture/integration passes and the Blender + realism asset pipeline (see `DONE.md` and `CHANGELOG.md`). The 12-character library (realistic face + four crowd variants) and the -Comedy Store map rebuild are complete. **Priority (2026-11-04, owner):** 1) release the finished procedural character development as -the **0.9.7 patch**, 2) finish the MakeHuman character + the 3D model and map improvements, -3) re-evaluate the 3D models, 4) ship it all together in the **0.10.0 minor** — `TODO.md` is the -priority source. Test counts as of 2026-11-04: Godot 277/277, -Python 161/161, `check_docs` OK. +Comedy Store map rebuild are complete. **Priority (2026-11-04, owner):** 1) the **Blender NPC +model overhaul** (head/face/hands, local part pipeline), 2) finish the MakeHuman character + the +3D model and map improvements, 3) ship it all together in the **0.10.0 minor**. The 0.9.7/0.9.8 +character patches are published; `TODO.md` is the priority source. Test counts as of 2026-11-04: +Godot 277/277, Python 160/160, `check_docs` OK. diff --git a/TODO.md b/TODO.md index ebfe632..3beb68e 100644 --- a/TODO.md +++ b/TODO.md @@ -3,15 +3,116 @@ Work is grouped by theme. Each item should be small enough to complete and verify on its own; see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans. -**Priority order (2026-11-04, owner):** 1) release the finished procedural character development -as the **0.9.7 patch**, 2) finish the MakeHuman character + the 3D model and map improvements, -3) re-evaluate the 3D models, 4) ship all of it together in the **0.10.0 minor**. See `AGENTS.md` -§Priority and Versioning and §Local Blender skills. +**Priority order (2026-11-04, owner):** 1) **Blender NPC model overhaul** — head, face and hands +with a local part pipeline; 2) finish the MakeHuman character + the 3D model and map improvements; +3) ship it together in the **0.10.0 minor**. The 0.9.7/0.9.8 character patches are published. See +`AGENTS.md` §Priority and Versioning and §Local Blender skills. The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gitignored). Every 3D workstream below names the skills to load; they are guidance only, and the project contract, `blender_assets.py audit`/`fit`/`inspect` and the capture gates stay authoritative. +## Blender NPC model overhaul (top priority) + +Goal: replace the sphere-and-primitive face and hand construction with a local, part-based +development pipeline that can build, inspect and compare the **head/face** and **hands** separately +before assembling them into the shipped character. Prioritise face readability at portrait +distance, then hand silhouette and gear contact. Preserve the `npc_base` contract, the 13-bone rig, +five tint slots, 8,000/8,000 character cap and Compatibility/Web path. + +*Skill route: `character-artist`, `retopology`, `sculpting`, `rigging`, `uv-workflow`, +`texture-workflow`, `materials`, `lookdev`, `asset-optimization`, `qa-review`.* + +**Current state:** `assets/models/npc/` contains the tracked frozen `npc_base.blend` and its +gitignored `.blend1`; the 12 production characters are assembled procedurally by +`tools/blender_assets.py` from `_shape_head_mesh`, `_face`, `_hair` and `_hands_and_shoes`. +There is no per-part source asset library yet. The MakeHuman body prototype and its temporary +head/hand swap live under `tmp/npc-research/` and are not the shipped path. This overhaul supplies +the reusable head/face and hand parts that both the procedural characters and the MakeHuman body +can consume. + +This workstream supersedes the face/head and hands items in §C until the prototypes are approved; +the rest of §C remains the broad review checklist. + +### 1. Baseline and acceptance + +- [ ] Inventory the real starting point: the frozen `assets/models/npc/npc_base.blend`, the 12 + generated character GLBs/AO maps, the current `_face`/`_hands_and_shoes` builders and the + temporary MakeHuman head/hand swap. Record tris/verts, head subdivision, material slots, + UV layout and the exact locations of eye/mouth/finger geometry. +- [ ] Define measurable acceptance: face front/three-quarter/profile at 1.5 m and 1.85 m; hands + open and gripping at 0.8 m; silhouette, eye/mouth readability, ear/nose/jaw planes, finger + separation and gear contact. Keep the 8,000/8,000 cap; no contract or renderer change. +- [ ] Confirm the identity boundary: `npc_base.blend` is the frozen fallback and must not absorb + prototype detail unless a separate contract decision approves it. +- [ ] Choose a local working-set layout: `tmp/npc-parts//` (gitignored) for part `.blend` + and preview GLBs; only the assembled character GLBs, AO/maps, manifest and review sheets are + committed. Do not add a new committed `.blend` source tree without a docs/ADR decision. + +### 2. Local part pipeline + +- [ ] Add `tools/npc_parts.py` with a small, documented CLI: + `extract` (pull the current head/hands for comparison), `build --part head|face|hand_l|hand_r`, + `assemble --variant `, `inspect`, `compare` and `sheet`. It should reuse the existing + builder helpers where possible and emit deterministic local files; do not fork a second + face/hand implementation. +- [ ] Keep the part pipeline local-only and headless: flatpak Blender for authoring, stdlib/Pillow + for inspection and sheets. No Blender MCP, no new runtime dependency, no CI Blender step. +- [ ] Add tests for deterministic part assembly, contract output (mesh root, bones, slots, budgets) + and the non-Blender failure path. Verify one assembled prototype with `audit`/`fit`/`inspect` + before touching production variants. +- [ ] Document the commands, working-set paths and “part source is not a shipped asset” rule in + `docs/asset-tooling.md`, `docs/blender-assets.md` and + `.agents/skills/gig-line-blender-asset-contract/references/verification.md`. + +### 3. Head and face prototype + +- [ ] Build one `npc_casual` head/face prototype as a connected head shell plus intentional feature + geometry — not a sphere with floating facial balls. Use loop-based eye sockets/lids, a + readable nose bridge/tip/ala, a mouth with upper/lower lip volumes, ears with concha depth, + and brow/cheek/jaw planes that survive the 256² AO bake. +- [ ] Compare two or three subdivision/loop variants at 1.85 m front/three-quarter/profile and a + 1.5 m portrait. Pick the variant that reads best before changing all 12 characters; keep the + rejected variants local. +- [ ] Verify head weights stay on the Head bone, headgear clearance still passes `fit`, and the + face does not bake recessed creases into dark AO patches. +- [ ] Get owner sign-off on the one-variant prototype, then roll the approved head/face into the + other 11 variants one asset family at a time, with a before/after sheet per batch. + +### 4. Hands and grip prototype + +- [ ] Build separate left/right hand parts with a connected palm, four multi-segment fingers, a + thumb, knuckles and rounded tips. Support an open palm and a relaxed grip; preserve the + current `HAND_ITEM_FORWARD` behaviour for phone/cup/clipboard/camera/flashlight/wand/radio. +- [ ] Decide finger articulation explicitly: the 13-bone contract has no finger bones, so keep the + open/relaxed-palm approach unless an ADR approves extra bones and the budget/weight path. +- [ ] Verify all hand gear at 0.8 m (contact, clipping, direction) and capture open/grip hand + close-ups for the review sheet. +- [ ] Roll the approved hands into all 12 variants only after the one-variant hand sheet passes. + +### 5. Assembly and rollout + +- [ ] Integrate the approved parts into `build_character` with deterministic joins, weights, UVs and + AO. The final output remains one `npc_base` skinned mesh under the existing 13-bone armature; + no second rig, no material-slot rename. +- [ ] Keep the MakeHuman body prototype consumable with the same approved head/hands; do not let it + grow a second face/hand implementation while the part pipeline is being proven. +- [ ] Rebuild only the changed character GLBs, AO maps and manifest entries; never run a no-op full + library rebuild. Commit one asset family per change. +- [ ] Re-run `blender_assets.py audit`/`fit`/`inspect`, `npc_proportions.py`, the 24-NPC budget, + Godot and Python tests, the 48-frame baseline and the 96-frame final-context review. + +### 6. QA, docs and exit + +- [ ] Capture front/three-quarter/profile head comparisons and open/grip hand comparisons; add + durable sheets to `docs/blender_previews/` and link them from the review docs. +- [ ] Update `docs/3d-model-review.md`, `docs/npc-visual-review.md`, + `docs/known-limitations.md`, `MEMORY.md` and the project skills with the accepted limits and + the new part workflow. +- [ ] Exit: head/face and hands are approved on one prototype, rolled out across all 12 variants, + all contract/budget/capture gates pass, the local part pipeline is documented, and no + runtime dependency or skeleton contract changed. + ## Fix the Rig pose harness Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the root cause is