diff --git a/MEMORY.md b/MEMORY.md index 1192499..c4385cd 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -4,6 +4,13 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o ## Decisions +- Graphics v0.6.0 plan (2026-11-01): NPCs move to Blender-authored skinned meshes + (`docs/plan-graphics-v0.6.md`, ADR-0013). `tools/npc_pipeline.py` builds + `assets/models/generated/npc_base.glb`; `NpcAvatar` keeps the procedural `_build_body()` + fallback. Preserve `Rig/Head`, the limb node names, and the seed-deterministic + `outfit_for`/`layer_for`/`hand_item_for` helpers. Blender = flatpak 5.2.0 LTS, sandbox cwd + `/app/blender` → absolute paths for `--python`. CI stays offline (committed assets). + - Engine: Godot 4.3 stable (official editor build, `~/.local/bin/godot`). The system's preinstalled `godot-runner` (4.7.2, Fedora) cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead. - Language: GDScript. All cross-file references use explicit `preload()` constants (not `class_name` globals) so scripts compile in headless `--script` runs without the editor's class cache. - Test framework deviation: the project uses a custom minimal headless test runner (`src/test/test_runner.gd`) instead of GUT, because GUT needs the editor plugin. CI runs it with `--headless`. @@ -15,6 +22,30 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o ## Handoff (read this first) +- **Phase 2 — AI texturing (this agent, DONE 2026-11-01).** Phase 1 assets were + already in the tree (untracked) and are preserved. Generated six seamless AI + clothing albedos into `assets/textures/npc/ai/{shirt,trousers,jacket,vest, + coat,dress}.png` (512×512, `--role tile`, gpt-5-image-mini; audit 6 good). + **Gotcha:** `asset_pipeline.py generate` defaults to `GEN_SIZE=2048`, which + gpt-5-image-mini rejects (HTTP 400); pass `--request-size 1024` for 1:1 roles. + `generate --role tile` already applies `make_seamless`, so a separate + `seamless` pass is redundant. Added to `tools/npc_pipeline.py`: `prepare` + (layers AI shirt→cloth, trousers→pants albedos at 128px) and `palette` + (writes `assets/textures/npc/palette.json` via `model_pipeline.dominant_colors`). + `write_slot_textures()` now skips the albedo for slots with an AI override + (normal/ORM stay procedural). Blender `build` re-run: GLB audit ok, 1204 tris / + 2488 verts, AI albedo embedded for cloth+pants. **Do not commit yet** — Phase 1 + files are uncommitted; coordinate the commit with the Phase 1/3 agents. + **Import concurrency:** a parallel agent is running + `timeout 300 godot --headless --editor --quit --path .` and then checks + `assets/models/generated/npc_base.glb.import` — treat that as the canonical + import. My own `godot --headless --path . --import` hung with no output past + the engine banner (two Godot instances contended on `.godot`); I killed the + orphan (PID 2482934). Do not run a second import while that `--editor --quit` + is active. + Next: Phase 3 (`NpcAvatar._load_model` + slot tinting) consumes + `palette.json` and the GLB; Phase 2's capture/judge item is blocked on that. + - Repo: `/run/media/system/DATA/Documents/06-games/security-game` (also reachable at `/var/home/zwitschi/Documents/06-games/security-game`). Godot: `~/.local/bin/godot` (4.3.stable). Tests: `godot --headless --path . --script res://src/test/test_runner.gd` → **177/177**. diff --git a/PLAN.md b/PLAN.md index 3010eab..d1d292b 100644 --- a/PLAN.md +++ b/PLAN.md @@ -399,6 +399,17 @@ The studio also has authorized guests and staff. They must either be recognized - Someone presents a counterfeit wristband or credential. - A violent threat appears during a crowded arrival, requiring the player to protect the entrance while calling for assistance. +--- + +## Visual Quality Direction + +The game prioritizes readable, well-lit, low-poly presentation over realism (GL Compatibility +renderer). The next visual pass, v0.6.0, replaces the procedural NPC rig with Blender-authored, +UV-mapped, skinned characters carrying baked normal/AO/roughness maps, using the existing AI tools +for textures, palettes, and screen judging. See +[`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) and +[ADR-0013](docs/adr/0013-blender-authored-npc-characters.md). + The scenario should test the player’s ability to distinguish ordinary Hollywood Boulevard activity from a genuine security problem. The best solution is usually a simple gesture, clear direction, or credential check rather than immediate escalation. Future venues can reuse this structure while changing the rules, equipment, staff roles, and types of access decisions. diff --git a/README.md b/README.md index 54ba559..d2ac2cd 100644 --- a/README.md +++ b/README.md @@ -391,6 +391,7 @@ The full arc42-style architecture documentation lives in [`docs/architecture.md` - [`MEMORY.md`](MEMORY.md) — Persistent session notes. - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation. - [`docs/adr/`](docs/adr/) — Architecture Decision Records. +- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Graphics-quality plan: Blender-authored NPC characters. ## Development Status @@ -430,7 +431,7 @@ Implemented so far: - Web build: `build/step-line-web-.zip` (Godot's non-threaded web template, no COOP/COEP headers needed) built by `tools/build_releases.sh` and published with the desktop artifacts; serve the unzipped folder from any static host - Aim-free selection pass (v0.3.0 work, [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md)): the focus cone ranks candidates by angle then distance, `Tab` and the mouse wheel cycle nearby people nearest-first and pin the selection, right click clears focus with a short re-acquire grace, the HUD reports how many people are in the ring, and holding `Shift` walks at half speed for close work -Not yet implemented: live 3D body-camera replay, editor-based GUT integration, and crowd performance profiling/LOD (see `TODO.md`). +Not yet implemented: the v0.6.0 graphics pass (Blender-authored NPC characters, see [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md)), live 3D body-camera replay, editor-based GUT integration, and crowd performance profiling/LOD (see `TODO.md`). ### Smoke Test Checklist diff --git a/TODO.md b/TODO.md index 7911999..b2dd9bf 100644 --- a/TODO.md +++ b/TODO.md @@ -5,7 +5,75 @@ suite **208/208** plus **56** Python tooling tests; the session, PLAN-verb, crow timeline, audio, scenario-content, props, NPC-budget, movement, and windowed focus/radial smokes pass. Anonymous downloads are enabled on the host. -The scheduled presentation pass is complete (see `DONE.md`). Only optional future ideas remain. +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). + +## 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) + +### Phase 0 — Toolchain spike and contract freeze + +- [ ] Verify `flatpak run org.blender.Blender --version` reports Blender 5.2.x and runs headless in this shell. +- [ ] Run a minimal headless Blender export using an absolute `--python` path (sandbox cwd is `/app/blender`); confirm the output file lands where expected. +- [ ] Record the exact working invocation (flatpak + absolute paths) in `MEMORY.md`. +- [ ] Freeze the NPC asset contract in `docs/plan-graphics-v0.6.md` and ADR-0013: file paths, bone names, material slots, triangle budget. +- [ ] Fix the material-slot set (`skin` / `cloth` / `pants` / `accessory` / `hair`) and the ORM packing (R=occlusion, G=roughness, B=metallic). +- [ ] Choose and record the initial tier-0 triangle/vertex budget (≤ ~6000 tris / ~4000 verts) in the plan. +- [ ] Spike: confirm Godot 4.3 imports a test `.glb` as a `PackedScene` with a `Skeleton3D` and playable imported clips. + +### Phase 1 — Blender authoring + export pipeline + +- [ ] Author the low-poly base humanoid in Blender: torso, articulated arms/legs, head with a face front, hands, shoes. +- [ ] Rig with an armature whose bones mirror the node contract (`Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`); origin at the feet, +Y up. +- [ ] UV-unwrap the mesh into a power-of-two layout, one region per material slot. +- [ ] Save the editable source as `assets/models/npc/npc_base.blend` (committed). +- [ ] Add `tools/npc_pipeline.py` with `list` / `build` / `audit` subcommands, run through the Blender flatpak. +- [ ] `build` exports `assets/models/generated/npc_base.glb` plus the material textures. +- [ ] Bake neutral albedo per slot, normal maps (fabric weave, denim, knit), and the packed ORM map. +- [ ] Bake ambient occlusion into the albedo or the ORM R channel (the Compatibility renderer has no SSAO). +- [ ] `audit` enforces UVs in [0,1], expected bone names, triangle/vertex budget, feet at y≈0, and material-slot presence. +- [ ] Reuse the `model_pipeline.py` colour-space discipline (linear factors vs sRGB textures) in the exporter. +- [ ] Run `godot --headless --path . --import` and confirm `npc_base.glb` imports without errors. + +### Phase 2 — AI-assisted texturing + +- [x] Generate seamless clothing albedos (shirt, trousers, jacket, hi-vis vest, coat, dress) with `tools/asset_pipeline.py generate` (OpenRouter, `openai/gpt-5-image-mini`) — written to `assets/textures/npc/ai/` (512×512). +- [x] Tile-edge blending on each fabric — applied automatically by `generate --role tile` (`make_seamless`); the `tile` audit's edge check confirms continuity. +- [x] Run `asset_pipeline.py audit` on the outputs — 6 good, 0 bad (role `tile`). +- [ ] Commit the validated textures (files are under `assets/textures/npc/ai/`; git commit coordinated via `MEMORY.md` — Phase 1 files are still uncommitted). +- [x] Derive per-role outfit palettes via `model_pipeline.dominant_colors` — written to `assets/textures/npc/palette.json` (`npc_pipeline.py palette`). +- [x] Bake normal/roughness procedurally and layer the AI albedos on top — `npc_pipeline.py prepare` + Blender `build` keeps the AI albedo for `cloth`/`pants` and regenerates normal/ORM; GLB audit ok (1204 tris / 2488 verts). +- [ ] Regenerate the staged captures and run `screen_designs.py judge` (blocked: needs Phase 3 `NpcAvatar` integration to render the skinned model). + +### Phase 3 — Godot integration + +- [ ] Add `NpcAvatar._load_model()` that instantiates the imported `npc_base.glb` `PackedScene`. +- [ ] Keep `_build_body()` as the offline fallback; choose per-avatar and record `loaded_model` / `fallback_avatar` for tests. +- [ ] Map `outfit_for()` onto the model's material slots so seed variety, `layer_for`, `hand_item_for`, and archetype colors survive. +- [ ] Keep accessory attachments (cap / hood / backpack / sunglasses / lanyard) under `Rig` / `Head`. +- [ ] Add `SurfaceMaterials` baked-map recipes (`npc()` / `skin()` / `cloth()`); stop calling `Materials.flat()` for the body. +- [ ] Add `_set_limb_rotation()` so `_animate()` / `_idle_layer()` write to bones or pivots; keep `Rig/Head` findable by the focus cone. +- [ ] Update `test_npc_character`, `test_npc_theater`, and `test_target_cycle` for the skinned path (or document why they stay on the fallback). +- [ ] Re-measure `smoke_npc_budget.gd`; tune `LOD_TIERS` if the skinned rig is heavier up close. +- [ ] Re-verify the focus-cone smoke (`smoke_focus_radial.gd`) and the movement smoke. + +### Phase 4 — Environment and lighting lift + +- [ ] Bake AO for the prop set (or rebuild the props in Blender) behind the same `assets/models/generated/.glb` contract. +- [ ] Regenerate higher-resolution brick / concrete / asphalt textures via `asset_pipeline.py` with normal maps, keeping the current UV scales. +- [ ] 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). +- [ ] 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. +- [ ] 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`. ## Future ideas (optional, not scheduled) diff --git a/assets/models/generated/npc_base.glb b/assets/models/generated/npc_base.glb new file mode 100644 index 0000000..d5e4cb1 Binary files /dev/null and b/assets/models/generated/npc_base.glb differ diff --git a/assets/models/npc/npc_base.blend b/assets/models/npc/npc_base.blend new file mode 100644 index 0000000..89c23c5 Binary files /dev/null and b/assets/models/npc/npc_base.blend differ diff --git a/assets/models/npc/npc_base.blend1 b/assets/models/npc/npc_base.blend1 new file mode 100644 index 0000000..c06e93b Binary files /dev/null and b/assets/models/npc/npc_base.blend1 differ diff --git a/assets/textures/npc/accessory_albedo.png b/assets/textures/npc/accessory_albedo.png new file mode 100644 index 0000000..b55bd6b Binary files /dev/null and b/assets/textures/npc/accessory_albedo.png differ diff --git a/assets/textures/npc/accessory_normal.png b/assets/textures/npc/accessory_normal.png new file mode 100644 index 0000000..73ad7c5 Binary files /dev/null and b/assets/textures/npc/accessory_normal.png differ diff --git a/assets/textures/npc/accessory_orm.png b/assets/textures/npc/accessory_orm.png new file mode 100644 index 0000000..a996245 Binary files /dev/null and b/assets/textures/npc/accessory_orm.png differ diff --git a/assets/textures/npc/ai/coat.png b/assets/textures/npc/ai/coat.png new file mode 100644 index 0000000..fb90454 Binary files /dev/null and b/assets/textures/npc/ai/coat.png differ diff --git a/assets/textures/npc/ai/dress.png b/assets/textures/npc/ai/dress.png new file mode 100644 index 0000000..f0273ea Binary files /dev/null and b/assets/textures/npc/ai/dress.png differ diff --git a/assets/textures/npc/ai/jacket.png b/assets/textures/npc/ai/jacket.png new file mode 100644 index 0000000..5e32109 Binary files /dev/null and b/assets/textures/npc/ai/jacket.png differ diff --git a/assets/textures/npc/ai/shirt.png b/assets/textures/npc/ai/shirt.png new file mode 100644 index 0000000..8a70a60 Binary files /dev/null and b/assets/textures/npc/ai/shirt.png differ diff --git a/assets/textures/npc/ai/trousers.png b/assets/textures/npc/ai/trousers.png new file mode 100644 index 0000000..3148ffb Binary files /dev/null and b/assets/textures/npc/ai/trousers.png differ diff --git a/assets/textures/npc/ai/vest.png b/assets/textures/npc/ai/vest.png new file mode 100644 index 0000000..831b042 Binary files /dev/null and b/assets/textures/npc/ai/vest.png differ diff --git a/assets/textures/npc/cloth_albedo.png b/assets/textures/npc/cloth_albedo.png new file mode 100644 index 0000000..5332002 Binary files /dev/null and b/assets/textures/npc/cloth_albedo.png differ diff --git a/assets/textures/npc/cloth_normal.png b/assets/textures/npc/cloth_normal.png new file mode 100644 index 0000000..080ee7c Binary files /dev/null and b/assets/textures/npc/cloth_normal.png differ diff --git a/assets/textures/npc/cloth_orm.png b/assets/textures/npc/cloth_orm.png new file mode 100644 index 0000000..69fc4f1 Binary files /dev/null and b/assets/textures/npc/cloth_orm.png differ diff --git a/assets/textures/npc/hair_albedo.png b/assets/textures/npc/hair_albedo.png new file mode 100644 index 0000000..cd40fec Binary files /dev/null and b/assets/textures/npc/hair_albedo.png differ diff --git a/assets/textures/npc/hair_normal.png b/assets/textures/npc/hair_normal.png new file mode 100644 index 0000000..97e97a0 Binary files /dev/null and b/assets/textures/npc/hair_normal.png differ diff --git a/assets/textures/npc/hair_orm.png b/assets/textures/npc/hair_orm.png new file mode 100644 index 0000000..5aa942e Binary files /dev/null and b/assets/textures/npc/hair_orm.png differ diff --git a/assets/textures/npc/palette.json b/assets/textures/npc/palette.json new file mode 100644 index 0000000..241289a --- /dev/null +++ b/assets/textures/npc/palette.json @@ -0,0 +1,50 @@ +{ + "coat": { + "hex": "#868585", + "rgb": [ + 0.5255, + 0.5216, + 0.5216 + ] + }, + "dress": { + "hex": "#cead94", + "rgb": [ + 0.8078, + 0.6784, + 0.5804 + ] + }, + "jacket": { + "hex": "#171616", + "rgb": [ + 0.0902, + 0.0863, + 0.0863 + ] + }, + "shirt": { + "hex": "#d5c8b8", + "rgb": [ + 0.8353, + 0.7843, + 0.7216 + ] + }, + "trousers": { + "hex": "#294667", + "rgb": [ + 0.1608, + 0.2745, + 0.4039 + ] + }, + "vest": { + "hex": "#e2e916", + "rgb": [ + 0.8863, + 0.9137, + 0.0863 + ] + } +} diff --git a/assets/textures/npc/pants_albedo.png b/assets/textures/npc/pants_albedo.png new file mode 100644 index 0000000..06de7f9 Binary files /dev/null and b/assets/textures/npc/pants_albedo.png differ diff --git a/assets/textures/npc/pants_normal.png b/assets/textures/npc/pants_normal.png new file mode 100644 index 0000000..cdc9728 Binary files /dev/null and b/assets/textures/npc/pants_normal.png differ diff --git a/assets/textures/npc/pants_orm.png b/assets/textures/npc/pants_orm.png new file mode 100644 index 0000000..0f0f415 Binary files /dev/null and b/assets/textures/npc/pants_orm.png differ diff --git a/assets/textures/npc/skin_albedo.png b/assets/textures/npc/skin_albedo.png new file mode 100644 index 0000000..57be307 Binary files /dev/null and b/assets/textures/npc/skin_albedo.png differ diff --git a/assets/textures/npc/skin_normal.png b/assets/textures/npc/skin_normal.png new file mode 100644 index 0000000..adc97cb Binary files /dev/null and b/assets/textures/npc/skin_normal.png differ diff --git a/assets/textures/npc/skin_orm.png b/assets/textures/npc/skin_orm.png new file mode 100644 index 0000000..99243a2 Binary files /dev/null and b/assets/textures/npc/skin_orm.png differ diff --git a/docs/adr/0013-blender-authored-npc-characters.md b/docs/adr/0013-blender-authored-npc-characters.md new file mode 100644 index 0000000..d1ef1b8 --- /dev/null +++ b/docs/adr/0013-blender-authored-npc-characters.md @@ -0,0 +1,85 @@ +# ADR-0013: Blender-authored NPC characters and baked materials + +- **Status:** Proposed +- **Date:** 2026-11-01 + +## Context + +NPCs are the procedural capsule-and-box rig from +[ADR-0010](0010-procedural-npc-presentation.md): articulated `Node3D` limbs, +flat `StandardMaterial3D` colors, and sphere hair/eyes. ADR-0010 accepted this +as a placeholder and recorded that a later skinned-mesh pass would replace the +rig while keeping the `Head` contract. The props already moved to generated +`.glb` assets ([ADR-0012](0012-surface-materials-and-generated-props.md)), but +people remain the lowest-fidelity part of the scene: no UVs, no baked normal or +ambient-occlusion maps, and silhouettes built from capsules. + +The project renders with the **GL Compatibility** backend (no SSAO/SSIL), so +visual quality has to come from the assets and baked maps rather than a renderer +change. CI must stay offline: the Blender step is a developer tool, not a build +dependency. + +## Decision + +1. **Author the NPC body in Blender** and export a skinned, UV-mapped base mesh + as `assets/models/generated/npc_base.glb`, driven by a new + `tools/npc_pipeline.py` (`build` / `audit`) invoked through the Blender + flatpak in headless mode. The `.blend` source is committed under + `assets/models/npc/`. +2. **Bake material maps in Blender** — neutral albedo, normal, and a packed ORM + (occlusion/roughness/metallic) map per material slot (`skin`, `cloth`, + `pants`, `accessory`, `hair`). Ambient occlusion is baked into the albedo or + the ORM R channel, since Compatibility has no screen-space AO. +3. **Keep a procedural fallback.** `NpcAvatar` loads the imported `PackedScene` + when it exists and falls back to the current `_build_body()` rig otherwise, + mirroring `WorldBuilder._add_prop_model()`. Committed assets mean CI never + needs Blender, and the headless suite runs against the fallback when the + import is absent. +4. **Preserve the `Head` contract and seed determinism.** The armature bones are + named after the current nodes (`Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, + `ElbowL/R`, `HandL/R`); `outfit_for` and friends stay pure and drive the + material slots. A thin `_set_limb_rotation()` wrapper lets `_animate()` / + `_idle_layer()` target either `Node3D` pivots or `Skeleton3D` bones. +5. **AI tooling supplies art direction only.** `tools/asset_pipeline.py` + generates seamless clothing albedos, `tools/model_pipeline.py`'s palette + helpers (`dominant_colors`, `assign_roles`) derive per-role palettes from + concept sheets, and `tools/screen_designs.py judge` closes the loop. All AI + outputs are committed; generation is dev-time and never a runtime or CI + dependency. + +## Consequences + +### Positive + +- NPCs gain real geometry, UVs, and baked normal/AO/roughness, so they read as + people at cinematic distance without a renderer switch. +- Skinned meshes collapse ~33 draw calls per avatar into one, which can offset + the skinning cost at `MAX_LIVE_NPCS = 16`. +- The asset contract stays behind the same `.glb` + audit discipline that props + already use; the procedural fallback keeps offline CI deterministic. +- AO baked into the maps compensates for the absence of SSAO in Compatibility. + +### Negative + +- A new toolchain (Blender flatpak + `npc_pipeline.py`) and its path/colour-space + gotchas enter the repo; contributors must run `audit` after changing the + `.blend`. +- Skinning shifts cost from draw calls to CPU; the 16-NPC frame budget must be + re-measured before raising the cap. +- Two avatar backends (skinned + fallback) must stay behaviourally identical, or + tests that assume the fallback will silently pass against one and not the + other. + +## Alternatives considered + +- **Keep the procedural rig and only add textures.** Rejected: textures on + capsules do not fix the silhouette; the rig is the fidelity ceiling. +- **Use Mixamo / a downloaded skinned character.** Rejected: licensing and + retargeting overhead exceed the value; a low-poly base authored in-house keeps + the art direction and the `Head`/bone contract under our control. +- **Switch the renderer to Forward+ for SSAO/SSIL.** Rejected as a prerequisite; + it would break the Web export assumptions. A desktop-only Forward+ preset + remains a follow-up, not a dependency of this decision. +- **A 3D-model (image-to-mesh) API instead of Blender.** Rejected for characters; + output topology is not controllable enough to satisfy the bone/UV contract. + It remains a possible prop-only follow-up (ADR-0012). diff --git a/docs/architecture.md b/docs/architecture.md index e82f8c0..a5a1c32 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -161,6 +161,7 @@ Architecture decisions are recorded as ADRs: - [ADR-0010: Procedural NPC presentation](adr/0010-procedural-npc-presentation.md) - [ADR-0011: Aim-free selection and precision walk](adr/0011-aim-free-selection-and-precision-walk.md) - [ADR-0012: Surface materials and generated props](adr/0012-surface-materials-and-generated-props.md) +- [ADR-0013: Blender-authored NPC characters and baked materials](adr/0013-blender-authored-npc-characters.md) ## 10. Quality Requirements diff --git a/docs/plan-graphics-v0.6.md b/docs/plan-graphics-v0.6.md new file mode 100644 index 0000000..815f6da --- /dev/null +++ b/docs/plan-graphics-v0.6.md @@ -0,0 +1,215 @@ +# Development Plan — Graphics Quality v0.6.0 (Blender-authored NPCs) + +> Status: Proposed · Target version: **v0.6.0** (MINOR) +> Companion decision: [ADR-0013](adr/0013-blender-authored-npc-characters.md) + +## Why this exists + +The game is functionally complete through v0.5.0, but NPCs are still the +procedural capsule-and-box rig from [ADR-0010](adr/0010-procedural-npc-presentation.md). +They read as people at conversation distance but not at cinematic distance, and +every surface on a body is a flat color. ADR-0010 recorded that "a later +skinned-mesh pass will replace this rig and must keep the `Head` contract" — +this plan is that pass. + +The goal is **better NPCs first**, then a modest environment lift, using the +existing AI tooling for art direction and quality gates, and **Blender** for the +geometry, UVs, skeleton, and baked material maps. + +## Constraints that shape the plan + +- **Renderer is GL Compatibility** (`project.godot` `config/features`). SSAO, + SSIL, and volumetrics are unavailable. Quality therefore comes from better + meshes, baked maps (AO/normal/roughness), and lighting — not from a renderer + switch. +- **CI builds offline.** `.gitea/workflows/build.yml` runs the Godot editor only + (no Blender, no network). Everything the game loads must be committed; the + Blender step is a developer tool, and the game keeps a procedural fallback so a + fresh checkout still boots and the headless suite still passes. +- **Determinism.** Seed-driven variety (`outfit_for`, `layer_for`, + `hand_item_for`, `idle_style_for`) must keep working and keep its tests green. + AI generation is a dev-time input, not a runtime dependency; the committed + assets are the source of truth. +- **Frame budget.** v0.5.0 measured 16 avatars = 534 meshes ≈ 6.9 ms headless. + A skinned rig replaces ~33 draw calls per avatar with one skin, but skinning + costs CPU. Re-measure with `src/test/smoke_npc_budget.gd` before raising + `MAX_LIVE_NPCS`. + +## The NPC asset contract (what must not break) + +From `src/game/npc_avatar.gd` and `src/game/guard_controller.gd`: + +- A scene-level node named **`Rig/Head`** — `GuardController` raycasts for it + (`get_node_or_null("Rig/Head")`), and the focus circle + name tag + reaction + tag attach under it. +- Limb pivots currently named `HipL`/`HipR` → `Knee`, `ShoulderL`/`ShoulderR` → + `Elbow` → `Hand`. `_animate()` and `_idle_layer()` drive them by `rotation.x`. +- Pure static helpers must stay pure and seed-deterministic: `outfit_for`, + `layer_for`, `hand_item_for`, `idle_style_for`, `queue_slot_for`, + `lod_tier_for_distance`, `reaction_label`, `crouch_for_pose`, + `prop_lift_for_pose`, `limb_swing`, `sway_for_pose`. +- LOD tiers (`apply_lod`, 0 / 1 / 2 with a billboard impostor at tier 2) must + keep working; `_detail_nodes` are hidden at tier 1. +- `set_focus_visual`, `_focus_circle`, `_name_tag`, `_reaction_tag`, the + theater poses, and the crowd reaction (`start_rubberneck`, `start_flee`) all + operate on the rig and must survive the swap. + +## Workstreams + +### Phase 0 — Toolchain spike and contract freeze (small, throwaway) + +1. Confirm headless Blender works in this environment. Blender **5.2.0 LTS** + flatpak is installed; the sandbox cwd is `/app/blender`, so `--python` and + all input/output paths must be absolute: + + ```bash + flatpak run org.blender.Blender --background \ + --python /var/home/zwitschi/Documents/06-games/security-game/tools/npc_pipeline.py -- --build + ``` + + Record the working invocation in `MEMORY.md` (the Im-Dornäcker notes already + warn about the cwd gotcha). +2. Freeze the asset contract in writing (this document + ADR-0013): + - `assets/models/generated/npc_base.glb` — one skinned mesh (or a small fixed + set of sub-meshes: body / head / hands) with a **named armature** and UVs. + - Material slots rather than one atlas-per-prop: `skin`, `cloth`, + `pants`, `accessory`, `hair` each carry a neutral albedo + normal + ORM + (occlusion/roughness/metallic) map. `outfit_for` colors tint the slot, so + multi-color outfits and seed variety survive. + - Bone names mirror the current node names (`Head`, `HipL/R`, `KneeL/R`, + `ShoulderL/R`, `ElbowL/R`, `HandL/R`) so `_animate()` can target them. + - Budget: tier-0 base body ≤ ~6,000 triangles, ≤ ~4,000 vertices (revisit + after the first `smoke_npc_budget.gd` run). + +### Phase 1 — `tools/npc_pipeline.py`: author + export + audit + +New tool, run through the Blender flatpak, mirroring the `model_pipeline.py` +shape (`list` / `build` / `audit`): + +1. **Author** a low-poly base humanoid in Blender: torso, articulated arms/legs, + head with a face front (so the focus ring and the "noticed the guard" cue + keep a direction), hands, shoes. Keep the current silhouette language + (heads, caps, hoods, backpacks, lanyards) so existing `outfit_for` + accessories still attach. +2. **Rig** it with an armature whose bones are named to match the node contract. + Godot 4.3 imports glTF skeletons as `Skeleton3D`; keep the bone rest pose + matching the current `_animate()` assumptions (arms hang, legs straight, + +Y up, origin at the feet on the floor). +3. **UV-unwrap** into a power-of-two layout and **bake** maps in Blender from + node materials or a higher-detail source: + - neutral albedo (white fabric pattern) per material slot, + - normal map (fabric weave, denim, knit), + - ORM map (occlusion in R, roughness in G, metallic in B — same packing + `model_pipeline.atlas_for` already uses), + - ambient occlusion baked into the albedo or the ORM R channel (this is the + Compatibility renderer's only AO source). +4. **Export** `npc_base.glb` with materials referenced as Godot-importable + textures (or export textures alongside and wire them in GDScript — decide in + the spike). +5. **Audit** (`npc_pipeline.py audit`) enforcing: UVs in [0,1], expected bone + names present, triangle/vertex budget, feet at y ≈ 0, no missing material + slots. Reuse the checks and the colour-space discipline from + `model_pipeline.py` (glTF `baseColorFactor` is linear; albedo textures are + sRGB — do not mix them up). +6. **Commit** the `.blend` source (`assets/models/npc/npc_base.blend`) so the + build is reproducible and editable, plus the generated `.glb` + textures so + CI never needs Blender. + +### Phase 2 — AI-assisted texturing (existing tools only) + +Use the tools already in `tools/`, not new services: + +1. `tools/asset_pipeline.py generate` (OpenRouter, + `openai/gpt-5-image-mini`) for seamless clothing albedos — shirt, trousers, + jacket, hi-vis vest, coat, dress — at the role sizes its `audit` validates. + Run `seamless` for tile-edge blending and `audit` to reject wrong sizes. +2. `tools/model_pipeline.py`'s palette helpers (`dominant_colors`, + `assign_roles`) or a small shared import, to derive per-role outfit palettes + from AI concept sheets (`concept`). `outfit_for` keeps determinism: the AI + supplies palettes and textures, never per-frame randomness. +3. Normal/roughness detail (fabric weave, denim) baked procedurally in Blender, + with the AI albedos layered on top. +4. Close the loop with `tools/screen_designs.py judge`: regenerate the staged + captures and confirm the new NPCs realise the same screen intents (art style + is ignored by the judge; layout and readability are not). + +Outputs land under `assets/textures/ai/game_ready/` (or a new +`assets/textures/npc/`) and are **committed**. + +### Phase 3 — Godot integration (`npc_avatar.gd`, `materials.gd`) + +1. Add a `_load_model()` path in `NpcAvatar` that instantiates the imported + `npc_base.glb` `PackedScene`, exactly like `WorldBuilder._add_prop_model()` + loads props. Keep `_build_body()` as the offline/procedural fallback; choose + per-avatar with the same "asset or fallback" pattern (record the choice in a + `loaded_model` / `fallback_avatar` field for tests). +2. Map `outfit_for()` onto the model's material slots (skin/cloth/pants/ + accessory/hair) so seed variety, `layer_for`, `hand_item_for`, and the + archetype color read stay intact. Accessories (cap/hood/backpack/ + sunglasses/lanyard) keep attaching under `Rig`/`Head` as they do today. +3. Add `SurfaceMaterials` recipes for the baked maps — e.g. `npc()` / + `skin()` / `cloth()` — so `_material()` gains a textured path and the body + stops calling `Materials.flat()`. +4. Abstract the animation targets so `_animate()` / `_idle_layer()` write to + either the procedural `Node3D` pivots (fallback) or `Skeleton3D` bones + (skinned). Keep the existing `rotation.x` math; the abstraction is a thin + `_set_limb_rotation(part, axis, radians)` wrapper. +5. Keep `Rig/Head` as a real scene node (a marker following the head bone, or + the imported bone's Godot node) so focus, nametag, and head-turn still find + it. Re-verify the focus cone smoke and `test_npc_character` / + `test_npc_theater` / `test_target_cycle`. +6. Re-measure `smoke_npc_budget.gd`; adjust `LOD_TIERS` if the skinned rig is + heavier up close. The impostor path is unchanged. + +### Phase 4 — Environment and lighting lift (after NPCs land) + +1. **Baked AO on props:** export the existing prop set through Blender (or bake + AO in `npc_pipeline`-style tooling) so contact shadows read without SSAO. + This replaces the pure box/cylinder builder with Blender-authored props + behind the same `assets/models/generated/.glb` contract (ADR-0012's + follow-up). +2. **Higher-resolution environment textures:** regenerate brick/concrete/asphalt + through `asset_pipeline.py` with normal maps, keeping the current UV scales. +3. **Evaluate a desktop-only Forward+ preset** (SSAO/SSIL/volumetrics) while the + Web export preset keeps `thread_support=false` and GL Compatibility. Decide + explicitly in an ADR addendum; do not silently change the renderer. +4. Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run + `screen_designs.py compare` and `judge` as the regression gate. + +### Phase 5 — Verification and release + +- Headless: fallback build, `npc_pipeline.py audit` (via `test_model_pipeline` + style Python tests if Blender is present, otherwise skip with reason), outfit + determinism, `Rig/Head` presence, material recipe assertions. +- Windowed smokes: `smoke_npc_budget.gd`, `smoke_movement.gd`, + `smoke_focus_radial.gd`, `smoke_props.gd`; screenshot comparison. +- Bump `config/version` to `0.6.0`, update `README.md`, `docs/architecture.md` + (Level 2 gains `tools/npc_pipeline.py`), and publish per + [`docs/RELEASING.md`](RELEASING.md). + +## Risks and mitigations + +| Risk | Mitigation | +| --- | --- | +| Blender flatpak sandbox paths (cwd `/app/blender`) | Absolute paths everywhere; record the invocation in `MEMORY.md`. | +| glTF colour space (linear factors vs sRGB textures) | Reuse `model_pipeline.srgb_to_linear`; bake textures as sRGB, keep factors linear; assert in `audit`. | +| Skeleton retargeting vs current node math | Keep the bone names + a thin limb-rotation wrapper; fallback rig keeps old math running. | +| Frame budget with skinned avatars | Measure first (`smoke_npc_budget.gd`); tune `LOD_TIERS`; impostor path unchanged. | +| No SSAO in Compatibility | Bake AO into albedo/ORM; contact-shadow tune in Phase 4. | +| AI output nondeterminism | Generation is dev-time only; commit outputs and gate with `audit`/`judge`/`compare`. | +| Blender unavailable in CI | Committed `.glb` + textures; procedural fallback; `audit` skipped with reason when Blender is absent. | + +## Acceptance criteria (definition of done) + +1. NPCs are Blender-authored skinned meshes with baked maps; they read as people + at conversation distance and survive a cinematic close-up. +2. `Rig/Head`, the focus cone, nametag, theater poses, crowd reactions, and LOD + all still work; all existing NPC tests pass unchanged or are updated with + clear reasons. +3. The game boots and plays from a fresh checkout with **no** Blender and no + network (committed assets + procedural fallback). +4. `npc_pipeline.py build` is deterministic and `audit` enforces the contract. +5. 208 headless + 56 Python tests stay green (Python audit tests skip when + Blender is absent); NPC-budget and movement smokes pass; screenshot + `compare`/`judge` show no regressions. +6. Version bumped to v0.6.0, docs and ADR-0013 updated, release published. diff --git a/tools/npc_pipeline.py b/tools/npc_pipeline.py new file mode 100644 index 0000000..c72d2cb --- /dev/null +++ b/tools/npc_pipeline.py @@ -0,0 +1,541 @@ +#!/usr/bin/env python3 +"""Build the low-poly, skinned NPC base mesh used by Step Line. + +The mesh, armature, UVs and neutral material maps are authored procedurally in +Blender and exported to `assets/models/generated/npc_base.glb`. Godot imports the +GLB as a PackedScene, tints the material slots per avatar, and drives the armature +bones (see `src/game/npc_avatar.gd`). The procedural capsule rig stays as the +offline fallback when the GLB is missing. + +The tool runs inside Blender (the flatpak sandbox cannot see `/tmp`, so every +path must be absolute): + + flatpak run org.blender.Blender --background \ + --python "$PWD/tools/npc_pipeline.py" -- build + python3 tools/npc_pipeline.py prepare # layer AI fabric albedos (Pillow) + python3 tools/npc_pipeline.py palette # derive outfit colours -> palette.json + python3 tools/npc_pipeline.py audit + +Contract (frozen in docs/plan-graphics-v0.6.md + ADR-0013): + + * scene root "Rig" with a skinned mesh and an armature + * bones: Head, HipL/R, KneeL/R, ShoulderL/R, ElbowL/R, HandL/R + (plus Hips/Spine/Neck as parents) + * material slots: skin, cloth, pants, accessory, hair + * neutral albedo + normal + packed ORM maps, albedo tinted at runtime + * <= 6000 triangles / 4000 vertices, UVs in [0,1], feet at y ~= 0 +""" + +import argparse +import json +import math +import struct +import sys +import zlib +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +GLB_PATH = ROOT / "assets" / "models" / "generated" / "npc_base.glb" +BLEND_PATH = ROOT / "assets" / "models" / "npc" / "npc_base.blend" +TEX_DIR = ROOT / "assets" / "textures" / "npc" + +SLOTS = ["skin", "cloth", "pants", "accessory", "hair"] +BONES = [ + "Head", "HipL", "HipR", "KneeL", "KneeR", + "ShoulderL", "ShoulderR", "ElbowL", "ElbowR", "HandL", "HandR", +] +MAX_TRIANGLES = 6000 +MAX_VERTICES = 4000 +TEX_SIZE = 128 +AI_DIR = TEX_DIR / "ai" +# Base material slots that get an AI fabric albedo (`prepare` layers them over +# the procedural weave). Outer layers (jacket / vest / coat / dress) have no +# material slot yet; Phase 3 adds them and can reuse this override mechanism. +AI_FABRICS = {"cloth": "shirt", "pants": "trousers"} +AI_FABRICS_ALL = ["shirt", "trousers", "jacket", "vest", "coat", "dress"] + +try: # Blender's Python has bpy; the audit command works without it. + import bpy # type: ignore +except ImportError: # pragma: no cover - exercised outside Blender + bpy = None + + +# --------------------------------------------------------------------------- +# Texture helpers (stdlib only: Blender ships no Pillow) +# --------------------------------------------------------------------------- + +SLOT_STYLE = { + # base sRGB tone, weave frequency, roughness, metallic, AO strength + "skin": ((222, 184, 150), 0.05, 150, 0, 0.10), + "cloth": ((232, 232, 228), 0.30, 220, 0, 0.18), + "pants": ((70, 78, 92), 0.22, 235, 0, 0.20), + "accessory": ((46, 48, 56), 0.12, 120, 180, 0.22), + "hair": ((58, 44, 34), 0.18, 170, 0, 0.16), +} + + +def _png(width: int, height: int, rgba: bytes) -> bytes: + rows = bytearray() + stride = width * 4 + for y in range(height): + rows.append(0) + rows.extend(rgba[y * stride:(y + 1) * stride]) + + def chunk(tag: bytes, data: bytes) -> bytes: + return (struct.pack(">I", len(data)) + tag + data + + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)) + + header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0) + return (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", header) + + chunk(b"IDAT", zlib.compress(bytes(rows), 9)) + chunk(b"IEND", b"")) + + +def _fabric_pattern(slot: str, x: int, y: int) -> float: + """A repeatable 0..1 height/weave signal per slot.""" + u = x / TEX_SIZE + v = y / TEX_SIZE + if slot == "cloth": + return 0.5 + 0.5 * math.sin(u * math.tau * 22.0) * math.sin(v * math.tau * 18.0) + if slot == "pants": + return 0.5 + 0.5 * math.sin((u + v) * math.tau * 26.0) + if slot == "skin": + return 0.5 + 0.5 * math.sin(u * math.tau * 7.0 + v * math.tau * 11.0) + if slot == "hair": + return 0.5 + 0.5 * math.sin((u * 1.7 - v) * math.tau * 30.0) + return 0.5 + 0.5 * math.sin(u * math.tau * 9.0) * math.sin(v * math.tau * 9.0) + + +def write_slot_textures() -> None: + """Write neutral sRGB albedo, tangent normal and packed ORM for each slot.""" + TEX_DIR.mkdir(parents=True, exist_ok=True) + for slot in SLOTS: + base, freq, roughness, metallic, ao_strength = SLOT_STYLE[slot] + albedo = bytearray(TEX_SIZE * TEX_SIZE * 4) + normal = bytearray(TEX_SIZE * TEX_SIZE * 4) + orm = bytearray(TEX_SIZE * TEX_SIZE * 4) + fabric = AI_FABRICS.get(slot) + use_ai_albedo = fabric is not None and (AI_DIR / f"{fabric}.png").is_file() + for y in range(TEX_SIZE): + for x in range(TEX_SIZE): + pattern = _fabric_pattern(slot, x, y) + # Baked AO approximation: darker in creases (pattern valleys) and + # toward the bottom of the tile. + ao = 1.0 - ao_strength * (1.0 - pattern) - 0.08 * (y / TEX_SIZE) + r = min(255, int(base[0] * ao)) + g = min(255, int(base[1] * ao)) + b = min(255, int(base[2] * ao)) + offset = (y * TEX_SIZE + x) * 4 + albedo[offset:offset + 4] = bytes((r, g, b, 255)) + dx = _fabric_pattern(slot, (x + 1) % TEX_SIZE, y) - pattern + dy = _fabric_pattern(slot, x, (y + 1) % TEX_SIZE) - pattern + nx = 128 + int(dx * 90.0) + ny = 128 + int(dy * 90.0) + normal[offset:offset + 4] = bytes((max(0, min(255, nx)), + max(0, min(255, ny)), 255, 255)) + orm[offset:offset + 4] = bytes((int(ao * 255), roughness, metallic, 255)) + # The prepared AI fabric replaces the procedural albedo; the baked AO now + # lives in the ORM R channel, so the albedo can stay unshaded. + if not use_ai_albedo: + (TEX_DIR / f"{slot}_albedo.png").write_bytes(_png(TEX_SIZE, TEX_SIZE, albedo)) + (TEX_DIR / f"{slot}_normal.png").write_bytes(_png(TEX_SIZE, TEX_SIZE, normal)) + (TEX_DIR / f"{slot}_orm.png").write_bytes(_png(TEX_SIZE, TEX_SIZE, orm)) + kept = [s for s, f in AI_FABRICS.items() if (AI_DIR / f"{f}.png").is_file()] + print(f"wrote {len(SLOTS) * 3} textures to {TEX_DIR}" + + (f" (kept AI albedo for {', '.join(kept)})" if kept else "")) + + +# --------------------------------------------------------------------------- +# Blender build +# --------------------------------------------------------------------------- + +def _material(slot: str): + mat = bpy.data.materials.new(slot) + mat.use_nodes = True + nodes = mat.node_tree.nodes + links = mat.node_tree.links + bsdf = nodes.get("Principled BSDF") + base, _, roughness, metallic, _ = SLOT_STYLE[slot] + bsdf.inputs["Base Color"].default_value = ( + base[0] / 255.0, base[1] / 255.0, base[2] / 255.0, 1.0) + bsdf.inputs["Roughness"].default_value = roughness / 255.0 + bsdf.inputs["Metallic"].default_value = metallic / 255.0 + + albedo = nodes.new("ShaderNodeTexImage") + albedo.image = bpy.data.images.load(str(TEX_DIR / f"{slot}_albedo.png")) + albedo.image.colorspace_settings.name = "sRGB" + links.new(albedo.outputs["Color"], bsdf.inputs["Base Color"]) + + normal_tex = nodes.new("ShaderNodeTexImage") + normal_tex.image = bpy.data.images.load(str(TEX_DIR / f"{slot}_normal.png")) + normal_tex.image.colorspace_settings.name = "Non-Color" + normal_map = nodes.new("ShaderNodeNormalMap") + links.new(normal_tex.outputs["Color"], normal_map.inputs["Color"]) + links.new(normal_map.outputs["Normal"], bsdf.inputs["Normal"]) + return mat + + +def _assign(obj, material, bone: str) -> None: + obj.data.materials.append(material) + group = obj.vertex_groups.new(name=bone) + group.add(list(range(len(obj.data.vertices))), 1.0, "REPLACE") + + +def _cube(name, size, loc, material, bone) -> None: + bpy.ops.mesh.primitive_cube_add(size=1.0, location=loc) + obj = bpy.context.object + obj.name = name + obj.scale = (size[0], size[1], size[2]) + bpy.ops.object.transform_apply(location=False, rotation=False, scale=True) + _assign(obj, material, bone) + + +def _cylinder(name, radius, depth, loc, material, bone, vertices=8) -> None: + bpy.ops.mesh.primitive_cylinder_add(vertices=vertices, radius=radius, + depth=depth, location=loc) + obj = bpy.context.object + obj.name = name + _assign(obj, material, bone) + + +def _sphere(name, radius, loc, material, bone, segments=12, rings=8, + scale=(1.0, 1.0, 1.0), rotation=(0.0, 0.0, 0.0)) -> None: + bpy.ops.mesh.primitive_uv_sphere_add(segments=segments, ring_count=rings, + radius=radius, location=loc) + obj = bpy.context.object + obj.name = name + obj.scale = scale + obj.rotation_euler = rotation + bpy.ops.object.transform_apply(location=False, rotation=True, scale=True) + _assign(obj, material, bone) + + +def _bone(edit_bones, name, head, tail, parent=None) -> None: + bone = edit_bones.new(name) + bone.head = head + bone.tail = tail + if parent is not None: + bone.parent = parent + + +def build_character() -> None: + bpy.ops.object.select_all(action="SELECT") + bpy.ops.object.delete(use_global=False) + for collection in (bpy.data.meshes, bpy.data.armatures, bpy.data.materials): + for datablock in list(collection): + if datablock.users == 0: + collection.remove(datablock) + + write_slot_textures() + mats = {slot: _material(slot) for slot in SLOTS} + parts = [] + + # Body (Blender is Z-up; the glTF exporter converts to Godot Y-up. The face + # points toward Blender -Y, which becomes Godot +Z like the fallback rig). + _cube("Pelvis", (0.36, 0.23, 0.22), (0, 0, 0.71), mats["pants"], "Hips") + _cube("Torso", (0.42, 0.26, 0.56), (0, 0, 1.10), mats["cloth"], "Spine") + _cube("Shoulders", (0.50, 0.26, 0.12), (0, 0, 1.38), mats["cloth"], "Spine") + _cylinder("Neck", 0.07, 0.15, (0, 0, 1.47), mats["skin"], "Neck", vertices=8) + _sphere("Head", 0.17, (0, 0, 1.63), mats["skin"], "Head", + scale=(1.0, 0.95, 1.08)) + _sphere("Hair", 0.178, (0, 0.01, 1.69), mats["hair"], "Head", + scale=(1.0, 1.0, 0.82)) + for side in (-1.0, 1.0): + _sphere("Ear", 0.04, (0.165 * side, 0.0, 1.62), mats["skin"], "Head", + segments=8, rings=6) + _sphere("Eye", 0.027, (0.058 * side, -0.155, 1.655), mats["accessory"], + "Head", segments=8, rings=6) + _cube("Brow", (0.065, 0.02, 0.014), (0.058 * side, -0.158, 1.705), + mats["hair"], "Head") + _cube("Mouth", (0.085, 0.02, 0.014), (0, -0.155, 1.575), + mats["accessory"], "Head") + + for side in (-1.0, 1.0): + x = 0.27 * side + _cylinder("UpperArm", 0.075, 0.30, (x, 0, 1.21), mats["cloth"], + "ShoulderL" if side < 0 else "ShoulderR") + _cylinder("Forearm", 0.065, 0.28, (x, 0, 0.92), mats["cloth"], + "ElbowL" if side < 0 else "ElbowR") + _sphere("Hand", 0.06, (x, 0, 0.745), mats["skin"], + "HandL" if side < 0 else "HandR", segments=10, rings=6) + + hx = 0.12 * side + _cylinder("Thigh", 0.10, 0.36, (hx, 0, 0.46), mats["pants"], + "HipL" if side < 0 else "HipR") + _cylinder("Shin", 0.085, 0.30, (hx, 0, 0.15), mats["pants"], + "KneeL" if side < 0 else "KneeR") + _cube("Shoe", (0.16, 0.29, 0.10), (hx, 0.04, 0.05), + mats["accessory"], "KneeL" if side < 0 else "KneeR") + + parts = [obj for obj in bpy.context.scene.objects if obj.type == "MESH"] + bpy.ops.object.select_all(action="DESELECT") + for obj in parts: + obj.select_set(True) + bpy.context.view_layer.objects.active = parts[0] + bpy.ops.object.join() + mesh = bpy.context.object + mesh.name = "npc_base" + + bpy.ops.object.mode_set(mode="EDIT") + bpy.ops.mesh.select_all(action="SELECT") + bpy.ops.uv.smart_project(angle_limit=math.radians(66.0), island_margin=0.02) + bpy.ops.object.mode_set(mode="OBJECT") + # Neutral flat shading keeps the low-poly read; smoothing is not needed. + for polygon in mesh.data.polygons: + polygon.use_smooth = False + + arm_data = bpy.data.armatures.new("Armature") + arm = bpy.data.objects.new("Armature", arm_data) + bpy.context.scene.collection.objects.link(arm) + bpy.context.view_layer.objects.active = arm + bpy.ops.object.mode_set(mode="EDIT") + bones = arm_data.edit_bones + _bone(bones, "Hips", (0, 0, 0.62), (0, 0, 0.82)) + _bone(bones, "Spine", (0, 0, 0.82), (0, 0, 1.40), bones["Hips"]) + _bone(bones, "Neck", (0, 0, 1.40), (0, 0, 1.52), bones["Spine"]) + _bone(bones, "Head", (0, 0, 1.52), (0, 0, 1.82), bones["Neck"]) + for side, suffix in ((-1.0, "L"), (1.0, "R")): + x = 0.27 * side + _bone(bones, f"Shoulder{suffix}", (x, 0, 1.38), (x, 0, 1.06), + bones["Spine"]) + _bone(bones, f"Elbow{suffix}", (x, 0, 1.06), (x, 0, 0.78), + bones[f"Shoulder{suffix}"]) + _bone(bones, f"Hand{suffix}", (x, 0, 0.78), (x, 0, 0.68), + bones[f"Elbow{suffix}"]) + hx = 0.12 * side + _bone(bones, f"Hip{suffix}", (hx, 0, 0.62), (hx, 0, 0.30), + bones["Hips"]) + _bone(bones, f"Knee{suffix}", (hx, 0, 0.30), (hx, 0, 0.0), + bones[f"Hip{suffix}"]) + bpy.ops.object.mode_set(mode="OBJECT") + + mesh.parent = arm + modifier = mesh.modifiers.new("Armature", "ARMATURE") + modifier.object = arm + + for obj in bpy.context.scene.objects: + obj.select_set(True) + bpy.context.view_layer.objects.active = mesh + GLB_PATH.parent.mkdir(parents=True, exist_ok=True) + bpy.ops.export_scene.gltf( + filepath=str(GLB_PATH), export_format="GLB", use_selection=False, + export_apply=False, export_animations=False, export_skins=True, + export_yup=True, export_materials="EXPORT", export_image_format="AUTO", + ) + BLEND_PATH.parent.mkdir(parents=True, exist_ok=True) + bpy.ops.wm.save_as_mainfile(filepath=str(BLEND_PATH)) + print(f"wrote {GLB_PATH} and {BLEND_PATH}") + + +# --------------------------------------------------------------------------- +# Audit (stdlib only) +# --------------------------------------------------------------------------- + +def _read_accessor(gltf, binary, index): + accessor = gltf["accessors"][index] + width = {"SCALAR": 1, "VEC2": 2, "VEC3": 3, "VEC4": 4}[accessor["type"]] + fmt = {5126: "f", 5125: "I", 5123: "H", 5121: "B"}[int(accessor["componentType"])] + view = gltf["bufferViews"][accessor["bufferView"]] + offset = int(view.get("byteOffset", 0)) + int(accessor.get("byteOffset", 0)) + stride = int(view.get("byteStride", width * struct.calcsize(fmt))) + values = [] + for i in range(int(accessor["count"])): + row = struct.unpack_from("<" + fmt * width, binary, offset + i * stride) + values.append(row[0] if width == 1 else row) + return values + + +def audit_glb(path: Path = GLB_PATH) -> dict: + issues = [] + if not path.is_file(): + return {"ok": False, "issues": ["missing npc_base.glb"], "triangles": 0, + "vertices": 0, "bones": []} + data = path.read_bytes() + try: + magic, version, length = struct.unpack_from(" 0.03: + issues.append(f"feet not on the ground (min y {min_y:.3f})") + if triangles > MAX_TRIANGLES: + issues.append(f"triangle budget exceeded ({triangles} > {MAX_TRIANGLES})") + if vertices > MAX_VERTICES: + issues.append(f"vertex budget exceeded ({vertices} > {MAX_VERTICES})") + if not BLEND_PATH.is_file(): + issues.append("editable .blend source missing") + return {"ok": not issues, "issues": issues, "triangles": triangles, + "vertices": vertices, "bones": bones} + + +# --------------------------------------------------------------------------- +# AI fabric preparation (Pillow; runs outside Blender) +# --------------------------------------------------------------------------- + +def prepare_albedos() -> list: + """Layer the committed AI fabric albedos over the procedural slot albedos. + + For each slot in AI_FABRICS, resize `assets/textures/npc/ai/.png` + to TEX_SIZE and write it as `_albedo.png`. A later `build` then keeps + that albedo (write_slot_textures skips it) and still regenerates the + procedural normal + packed ORM maps, so the AI colour sits on top of the + baked normal/AO detail. + """ + from PIL import Image + + TEX_DIR.mkdir(parents=True, exist_ok=True) + written = [] + for slot, fabric in AI_FABRICS.items(): + src = AI_DIR / f"{fabric}.png" + if not src.is_file(): + print(f"skip {slot}: {src.relative_to(ROOT)} missing (procedural albedo stays)") + continue + with Image.open(src) as image: + image.load() + image.convert("RGB").resize( + (TEX_SIZE, TEX_SIZE), Image.Resampling.LANCZOS + ).save(TEX_DIR / f"{slot}_albedo.png") + written.append(f"{slot}<={fabric}") + print("prepared albedos: " + (", ".join(written) if written else "none")) + return written + + +def write_palette() -> dict: + """Derive one representative colour per AI fabric and write palette.json. + + Reuses model_pipeline.dominant_colors so the colours come from the same + centre-crop + saturation ranking as the prop concepts. Phase 3 can consume + these as deterministic, committed outfit base colours. + """ + import model_pipeline + from PIL import Image + + palette = {} + for fabric in AI_FABRICS_ALL: + src = AI_DIR / f"{fabric}.png" + if not src.is_file(): + continue + with Image.open(src) as image: + image.load() + colors = model_pipeline.dominant_colors(image, count=1) + if not colors: + continue + r, g, b = colors[0] + palette[fabric] = { + "rgb": [round(c, 4) for c in (r, g, b)], + "hex": f"#{int(round(r * 255)):02x}{int(round(g * 255)):02x}" + f"{int(round(b * 255)):02x}", + } + (TEX_DIR / "palette.json").write_text( + json.dumps(palette, indent=2, sort_keys=True) + "\n", encoding="utf-8") + print(f"wrote {TEX_DIR / 'palette.json'}") + return palette + + +def list_contract() -> int: + print("npc_base contract") + print(f" glb: {GLB_PATH.relative_to(ROOT)}") + print(f" blend: {BLEND_PATH.relative_to(ROOT)}") + print(f" slots: {', '.join(SLOTS)}") + print(f" bones: {', '.join(BONES)} (+ Hips/Spine/Neck)") + print(f" budget: <= {MAX_TRIANGLES} tris / {MAX_VERTICES} verts") + return 0 + + +def main(argv=None) -> int: + raw = list(argv if argv is not None else sys.argv[1:]) + if "--" in raw: + raw = raw[raw.index("--") + 1:] + parser = argparse.ArgumentParser(description=__doc__) + sub = parser.add_subparsers(dest="command", required=True) + sub.add_parser("list") + sub.add_parser("build") + sub.add_parser("prepare") + sub.add_parser("palette") + audit = sub.add_parser("audit") + audit.add_argument("--json", action="store_true") + args = parser.parse_args(raw) + + if args.command == "list": + return list_contract() + if args.command == "build": + if bpy is None: + print("build must run inside Blender:\n flatpak run org.blender.Blender " + "--background --python %s -- build" % Path(__file__).resolve(), + file=sys.stderr) + return 2 + build_character() + result = audit_glb() + print(json.dumps(result, indent=2)) + return 0 if result["ok"] else 1 + if args.command == "prepare": + prepare_albedos() + return 0 + if args.command == "palette": + write_palette() + return 0 + result = audit_glb() + if args.json: + print(json.dumps(result, indent=2)) + else: + print(f"{'OK ' if result['ok'] else 'BAD'} npc_base.glb " + f"tris={result['triangles']} verts={result['vertices']} " + f"bones={len(result['bones'])}") + for issue in result["issues"]: + print(" -", issue) + return 0 if result["ok"] else 1 + + +if __name__ == "__main__": + sys.exit(main())