Extend the v0.6.0 plan with the Blender asset library

Document the larger asset set produced by the running Blender generator
(tools/blender_assets.py): 8 NPC character variants, 18 gear pieces, and 22
street/venue props with a manifest, editable sources, and preview sheets.

- TODO gains Phase 3.5 with the audit/budget reconciliation (npc_casual is
  currently 7,756 tris / 5,616 verts, above the 6,000/4,000 contract), character
  selection by role, gear attach points, prop replacement/placement, emissive
  wiring, budgets, and screenshot gates
- PLAN's Visual Quality Direction describes the library, runtime selection, and
  offline fallbacks
- docs/plan-graphics-v0.6.md adds the library contract/output table and
  integration steps, and points Phase 4 at the Blender props
- MEMORY records the manifest-as-source-of-truth rule and the generator caveat

Generated library files stay untracked until the running build finishes and
passes the audit; the generator itself is committed so the plan is reproducible.
This commit is contained in:
zwitschi committed 2026-11-01 13:39:03 +01:00
1 parent a231f7588a
commit 7efb5024ec
5 files changed
+1766 -20

No files matched your search

+57 -4
View File
@@ -8,6 +8,13 @@ pass. Anonymous downloads are enabled on the host.
The scheduled presentation pass is complete (see `DONE.md`). The next scheduled pass is the
graphics-quality work in [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md).
> **Asset build in progress:** `tools/blender_assets.py` is being run separately (flatpak
> Blender) to generate a larger library: 8 NPC character variants, 18 gear pieces, and 22
> street/venue props under `assets/models/blender/`, with a manifest and preview renders.
> Do not edit the generator while that process is running. Treat
> `assets/models/blender/manifest.json` as the integration source of truth, and audit the
> finished outputs before wiring anything into the game.
## Graphics quality — Blender-authored NPC characters (v0.6.0)
Detailed plan: [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) · [ADR-0013](docs/adr/0013-blender-authored-npc-characters.md)
@@ -58,19 +65,65 @@ Detailed plan: [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) · [AD
- [x] Re-measure `smoke_npc_budget.gd`; tune `LOD_TIERS` if the skinned rig is heavier up close.
- [x] Re-verify the focus-cone smoke (`smoke_focus_radial.gd`) and the movement smoke.
### Phase 3.5 — Blender asset library integration (generator running)
Contract and outputs: [`assets/models/blender/manifest.json`](assets/models/blender/manifest.json),
generator `tools/blender_assets.py`, previews `docs/blender_previews/` (the generator's
integration notes are being written to `docs/blender-assets.md`). The library currently targets
8 `npc` variants, 18 `npc_gear` pieces, and 22 `props`; each entry records path, triangle/vertex
count, bounds, material slots, and (for gear) its attach point.
- [ ] Wait for the running build to finish, then run `python3 tools/blender_assets.py audit` and
reconcile every failure. The first `npc_casual` build is over the 6,000-triangle contract
(7,756 tris / 5,616 verts): reduce the mesh or raise/annotate the character budget in the
plan before integrating.
- [ ] Run `python3 tools/blender_assets.py sheet` and review the contact sheets; reject assets
whose silhouette, grounded origin, or face direction (+Z in Godot) is wrong.
- [ ] Commit the finished library with the generator, `.blend` sources, manifest, previews, and
`docs/blender-assets.md`; add generated/preview folders to `.gitignore` only where CI can
rebuild them offline. Keep the audit runnable without Blender.
- [ ] Add `tools/test_blender_assets.py` for the manifest contract (all catalogue entries present,
audit clean, attach points known, paths inside `assets/models/blender/`).
- [ ] Let `NpcAvatar` choose a character model from the manifest by the profile's role/layer
(`npc_casual` / `npc_jacket` / `npc_coat` / `npc_vest` / `npc_dress` / `npc_hoodie` /
`npc_firefighter` / `npc_guard`), with the existing `npc_base.glb` and procedural rig as
fallbacks; record the chosen path for tests.
- [ ] Keep `outfit_for()` tinting the `skin`/`cloth`/`pants`/`accessory`/`hair` slots on every
variant and keep `Rig/Head` as the focus/nametag anchor.
- [ ] Replace the procedural cap/hood/backpack/sunglasses/lanyard and hand items with the
matching `npc_gear` assets at the documented `head` / `back` / `chest` / `hand` attach
points; fall back to the current primitives when gear is missing.
- [ ] Load the replacement props (`bollard`, `bench`, `trash_bin`, `planter_box`,
`newspaper_box`, `fire_hydrant`, `street_lamp`, `street_tree`, `traffic_cone`) from the
Blender library behind the existing `WorldBuilder` model/fallback path.
- [ ] Place the new street/venue props (`palm_tree`, `round_planter`, `a_frame_sign`,
`wall_lantern`, `crowd_barrier`, `stanchion`, `handrail`, `security_podium`,
`double_door`, `marquee`, `sedan`) through `PROP_PLACEMENTS`/dedicated venue slots, with
collider + `NavigationObstacle3D` footprints and no overlap with the door/approach lane.
- [ ] Wire the emissive parts (`street_lamp` bulb, `wall_lantern`, `double_door` lock LED,
`marquee` bulbs/sign face, `sedan` headlights) to the day/night phase lighting instead of
leaving them always on.
- [ ] Use the library `street_tree`/`palm_tree` instead of the current cone trees, and the
Blender `marquee`/`double_door` where the procedural versions currently sit; compare
silhouettes with `screen_designs.py`.
- [ ] Re-measure `smoke_npc_budget.gd` and add a prop draw/triangle budget check; keep
`MAX_LIVE_NPCS` unchanged until the new characters are measured.
- [ ] Regenerate all staged captures and run `screen_designs.py compare` + `judge`; add a
character close-up capture (the 02 target shot) to the catalogue if needed.
### Phase 4 — Environment and lighting lift
- [ ] Bake AO for the prop set (or rebuild the props in Blender) behind the same `assets/models/generated/<prop>.glb` contract.
- [ ] Regenerate higher-resolution brick / concrete / asphalt textures via `asset_pipeline.py` with normal maps, keeping the current UV scales.
- [ ] Bake AO for the prop set through the Blender library (replacements above) or into the ORM/albedo maps behind the existing `WorldBuilder` contract; keep the procedural fallback.
- [ ] Regenerate higher-resolution brick / concrete / asphalt textures via `asset_pipeline.py` with normal maps, keeping the current UV scales; apply the same map discipline to the library's street materials.
- [ ] Evaluate a desktop-only Forward+ export preset (SSAO/SSIL/volumetrics); keep the Web preset on GL Compatibility with `thread_support=false`.
- [ ] Record the renderer decision in an ADR addendum or `MEMORY.md`.
- [ ] Regenerate `docs/screenshots/` with `capture_screenshots.gd` and run `screen_designs.py compare`.
### Phase 5 — Verification and release
- [ ] Headless suite green: fallback build, outfit determinism, `Rig/Head` presence, material recipe assertions, `npc_pipeline.py audit` (skip with reason when Blender is absent).
- [ ] Headless suite green: fallback build, outfit determinism, `Rig/Head` presence, material recipe assertions, `npc_pipeline.py audit`, and `blender_assets.py audit` + manifest tests (skip Blender builds with a reason when Blender is absent).
- [ ] Windowed smokes pass: `smoke_npc_budget.gd`, `smoke_movement.gd`, `smoke_focus_radial.gd`, `smoke_props.gd`.
- [ ] `screen_designs.py compare` and `judge` show no regressions.
- [ ] `screen_designs.py compare` and `judge` show no regressions; `blender_assets.py sheet` contact sheets reviewed for the character/gear/prop library.
- [ ] Bump `config/version` to `0.6.0`.
- [ ] Update `README.md`, `docs/architecture.md` (Level 2 gains `tools/npc_pipeline.py`), and mark ADR-0013 Accepted.
- [ ] Publish the release per `docs/RELEASING.md`.