Add the local npc_parts.py head/face/hand part pipeline with tests and docs
This commit is contained in:
1 parent
1b554df516
commit
b8d8869e03
7 files changed
+434
-13
No files matched your search
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user