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
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

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/npc-visual-review.md and docs/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.

4.3 KiB Raw Blame History Unescape Escape