Add the local npc_parts.py head/face/hand part pipeline with tests and docs
Full build / Import + headless tests (push) Successful in 41s
Full build / Full desktop build + optional release (push) Skipped

This commit is contained in:
zwitschi committed 2026-11-04 14:17:20 +01:00
1 parent 1b554df516
commit b8d8869e03
7 files changed
+434 -13

No files matched your search

+4 -2
View File
@@ -151,8 +151,10 @@ width scale.
| `makehuman_retargeted.glb` | 7,062 / 6,444 | 14 | 5 tint | arm-down + contract rig, deltoid warp remains |
| `makehuman_final.glb` | 6,651 / 6,407 | 14 | 8 (incl. `skin.001`, `eye_white`, `rubber`) | project head/hands/shoes swapped; duplicate `skin.001` |
Each GLB carries a stray 42-vert/80-tri `Icosphere` origin helper that must be dropped before any
promotion.
The "Icosphere" the inspector lists alongside these GLBs is the glTF importer's
bone-display helper (a `pose_bone.custom_shape`), not part of the asset; `inspect_glb` already
excludes it from measurements. The real cleanup for `makehuman_final.glb` is the duplicate
`skin.001` material and the manual deltoid retopology.
## Overhaul acceptance criteria (measurable)
+7 -1
View File
@@ -430,6 +430,12 @@ scene, and connect from the sidebar. If the client cannot reach the addon:
### Recommended part-workflow
The headless part pipeline is `tools/npc_parts.py` (see
[`blender-assets.md#local-part-pipeline`](blender-assets.md#local-part-pipeline)). It builds,
extracts, assembles, inspects and sheets the reusable head/face and hand parts and reuses the
`blender_assets.py` builders, so there is no second face/hand implementation. The MCP steps below
remain optional interactive exploration; the headless commands stay the build and audit path.
1. Create a local scene, for example
`tmp/npc-parts/npc_casual/head.blend`, or open a copy of an exported part GLB.
Never save over the tracked `assets/models/npc/npc_base.blend`.
@@ -460,7 +466,7 @@ scene, and connect from the sidebar. If the client cannot reach the addon:
- MCP is **not** part of `project.godot`, the build, CI, tests, release packages
or runtime.
- Do not commit `.blend` part scenes, MCP configuration, API keys or generated
previews. The working set stays in `tmp/`.
previews. The working set stays in `tmp/`; a part GLB is not a shipped asset.
- Do not use MCP to bypass the contract, budgets, AO/UV rules or licence gate.
- The 13 core bones must remain at their rest positions; extra optional bones
are allowed only if `NpcAvatar` and the audit/tests still pass.
+38
View File
@@ -45,6 +45,44 @@ required before any prototype detail is absorbed. Working scenes live under
directly over the tracked `.blend`. The same rule already appears in
[`asset-tooling.md#recommended-part-workflow`](asset-tooling.md#recommended-part-workflow).
## Local part pipeline
The overhaul uses `tools/npc_parts.py` to build, extract, assemble, inspect and sheet the
reusable head/face and hand parts before they are rolled into the 12 characters. It reuses the
`blender_assets.py` builders (no second face/hand implementation) and stays local-only/headless.
Part sources and preview GLBs live under `tmp/npc-parts/<variant>/`; they are **not shipped
assets** — only the assembled character GLBs, AO/maps, the manifest and the review sheets are
committed.
```bash
# Build one part fresh from the current builders (head|face|hand_l|hand_r)
flatpak run org.blender.Blender --background \
--python "$PWD/tools/npc_parts.py" -- build --part face --variant npc_casual \
--out "$PWD/tmp/npc-parts/npc_casual/face.glb"
# Pull the current shipped head/hands out of the built character GLB (comparison)
flatpak run org.blender.Blender --background \
--python "$PWD/tools/npc_parts.py" -- extract --part hand_l --variant npc_casual \
--out "$PWD/tmp/npc-parts/npc_casual/hand_l.glb"
# Assemble a variant (currently rebuilds the procedural character)
flatpak run org.blender.Blender --background \
--python "$PWD/tools/npc_parts.py" -- assemble --variant npc_casual \
--out "$PWD/tmp/npc-parts/npc_casual/assembled.glb"
# Inspect a part or assembled GLB (Blender import view)
flatpak run org.blender.Blender --background \
--python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/npc_casual/face.glb"
# Contact sheet / before-after comparison (outside Blender; stdlib + Pillow)
python3 tools/npc_parts.py sheet --dir tmp/npc-parts/npc_casual \
--out docs/blender_previews/sheet_parts.jpg
python3 tools/npc_parts.py compare --before DIR --after DIR --out sheet.jpg
```
`build --part head` produces the bare head shell; `build --part face` is the shell plus
nose/eyes/mouth/ears; `build --part hand_l|hand_r` are the left/right hand geometry. `extract`
pulls the current shipped geometry out of the built character GLB by vertex group (`Head` for
`head`/`face`, `HandL`/`HandR` for the hands), so it shows what is actually shipped rather than
what the builders would emit fresh. The assembled GLB must still pass
`blender_assets.py inspect`/`audit`/`fit` before any part is accepted.
## Optional MCP
Blender MCP can be used for interactive head/face/hand part exploration, but it