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.
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# Verification Matrix
|
||
|
||
Run from the repository root. Stop and fix the first failure before continuing.
|
||
|
||
## Environment
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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.
|