zwitschi
2ba40f3578
Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
4.9 KiB
Verification Matrix
Run from the repository root. Stop and fix the first failure before continuing.
Environment
godot --version
flatpak run org.blender.Blender --version | head -3
git status --short
Expected: Godot 4.7.2; Blender 5.2 LTS flatpak; clean or intentionally scoped
working tree. Blender's flatpak cwd is /app/blender; all paths passed to
Blender must be absolute.
Asset checks
| Check | Command | Expected |
|---|---|---|
| Contract audit | python3 tools/blender_assets.py audit |
exit 0, no BAD assets |
| Gear fit | python3 tools/blender_assets.py fit |
exit 0; review head band/clothing/back clearances |
| Texture/texel density | python3 tools/blender_assets.py texels |
authored 40–400 px/m; fabric ≥250 px/m |
| NPC base | python3 tools/npc_pipeline.py audit |
exit 0, contract bones/slots/maps |
| Proportions | python3 tools/npc_proportions.py report |
all eight inside the stylized guide |
| Single incoming GLB | flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- inspect --file "$PWD/path.glb" --category <cat> --json |
contract result and measurements |
| Part GLB (local) | flatpak run org.blender.Blender --background --python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/<variant>/<part>.glb" |
measurements; a part GLB is not a shipped asset |
| Prop audit | python3 tools/model_pipeline.py audit |
exit 0 when generated props changed |
| Texture audit | python3 tools/asset_pipeline.py audit assets/textures/ai/game_ready |
exit 0 when textures changed |
Build/bake
# one library asset
flatpak run org.blender.Blender --background \
--python "$PWD/tools/blender_assets.py" -- build --only npc_guard
# bake AO for the same asset
flatpak run org.blender.Blender --background \
--python "$PWD/tools/bake_ao.py" -- --only npc_guard
# NPC base material maps/base
python3 tools/npc_pipeline.py prepare
flatpak run org.blender.Blender --background \
--python "$PWD/tools/npc_pipeline.py" -- build
python3 tools/npc_pipeline.py audit
Only run prepare when AI fabric inputs changed. Do not run a full library
rebuild just to hide a small diff; build the affected asset and its AO map.
Import and tests
godot --headless --path . --import
godot --headless --path . --script res://src/test/test_runner.gd
python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py'
python3 tools/check_docs.py
Expected: Godot suite passes; Python tooling suite passes; docs check OK. The project uses its own headless runner, not GUT.
Capture gates
# neutral studio baseline: 48 frames (8 characters x 6 views)
godot --path . --script res://src/test/capture_npc_baseline.gd \
-- --out=res://tmp/npc-baseline-after
# final-context: 96 frames (8 models x 3 distances x 2 venues x day/night)
godot --path . --script res://src/test/capture_npc_review.gd \
-- --out=res://tmp/npc-review-after
# optional hand close-up: 8 frames
godot --path . --script res://src/test/capture_npc_baseline.gd \
-- --out=res://tmp/npc-hands --view=hand
Raw frames stay under tmp/ and are never committed. Compare with:
python3 tools/npc_baseline.py compare \
--before tmp/npc-baseline --after tmp/npc-baseline-after \
--out docs/blender_previews/sheet_npc_baseline_compare-<topic>.jpg
Do not replace the committed baseline sheet until the change is accepted.
Budget/performance
godot --headless --path . --script res://src/test/smoke_npc_budget.gd
Expected report: 24 avatars / 168 meshes / 131,616 triangles (current baseline) inside the 50 ms budget. Record the actual frame time; do not copy an old number without measuring.
Visual review criteria
The part pipeline (tools/npc_parts.py) builds/extracts head/face/hand parts under
tmp/npc-parts/<variant>/; these are local working files and are not shipped. Only the
assembled character GLBs, AO/maps, the manifest and the review sheets are committed. An
assembled GLB still goes through blender_assets.py inspect/audit/fit before any part is
accepted. The npc_base.blend fallback is frozen: never save prototype detail into it.
For each changed variant, inspect at least:
- 2 m portrait: eyes, mouth, ears, neck/shoulder, hair/headgear clearance.
- 4.2 m conversation: hands, gear contact, clothing silhouette.
- 8 m crowd: readable silhouette and LOD/impostor swap.
- Day and night/LATE final-context frames.
- Front, three-quarter and profile for a shape change.
Accepted stylized limits are in docs/assets/3d-model-review.md and
docs/design/known-limitations.md. Do not turn an accepted limit into an unreviewed
contract change.
Final diff review
git diff --check
git status --short
git diff --stat
Check that only intended .glb, AO/maps, manifest, tests and docs changed. If a
.blend, raw capture, generated AI input or temporary sheet is staged, stop and
remove it. Commit one coherent asset family per commit.