diff --git a/TODO.md b/TODO.md index a1cdf2b..d59f67a 100644 --- a/TODO.md +++ b/TODO.md @@ -14,7 +14,8 @@ The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gi ## 3D model re-evaluation Goal: re-judge every shipped 3D asset against the newly available Blender skill guidance, rank -the real gaps, and fix only what the rankings justify. This is an unversioned development track: +the real gaps, and fix only what the rankings justify. Evidence comes from three separate sources: +licensed real-location photos, generated concept boards, and build captures. This is an unversioned development track: it must not change the `npc_base` contract, the renderer or the 0.10.0 release candidate. Scope: 8 library characters (`npc_casual`, `npc_jacket`, `npc_coat`, `npc_vest`, `npc_dress`, @@ -78,6 +79,12 @@ except the rebuilt assets themselves. `hair-groom` guidance; decide explicitly whether cloth simulation stays out of scope. - [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. +- [ ] Build a licensed real-photo reference board for crowd variety (ages, builds, hair, outer + layers) and record what was adopted; reference only, never traced or repainted. +- [ ] Generate a face/hand concept board for the highest-ranked P1 and compare it with the 0.9.4 + baseline before rebuilding anything; keep it development-only and record model and prompt. +- [ ] After each accepted fix, capture front/three-quarter/profile comparisons, add them to the + review sheet, and refresh the README character row. - [ ] `qa-review` sign-off: a ship/no-ship verdict per variant with accepted limits recorded. ### C. Gear and prop re-evaluation @@ -96,6 +103,13 @@ except the rebuilt assets themselves. sedan at day and late; confirm the flashlight stays a tight spot with no beam geometry. - [ ] Collision: verify every prop collider and navigation obstacle matches its silhouette and add the missing `collision-proxy` shapes where walking is blocked. +- [ ] Build a real-photo comparison for street furniture (bollard, bench, bin, hydrant, planter, + lamp) and rank the silhouette and proportion mismatches. +- [ ] Rebuild only the mismatched pieces through the assisted Blender pipeline + (`blender_assets.py inspect` → scripted retopo/UV assist → atlas → `audit`/`fit`); document + the exact commands in `docs/asset-tooling.md`. +- [ ] Refresh `sheet_props.jpg`/`sheet_npc_gear.jpg`, the README asset rows and + `docs/blender_previews/README.md` after the rebuilds. - [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset. ### D. Venue and camera re-evaluation @@ -111,10 +125,43 @@ except the rebuilt assets themselves. navigation obstacles and readable storytelling clusters. - [ ] Camera height: decide 1.7 m gameplay framing vs the ~1.55 m concept frames using `camera-cinematography`, and record the decision instead of leaving the mismatch open. +- [ ] Build the venue three-up boards (real photo | generated concept | current capture) and + attach them to `docs/hollywood-boulevard-map.md` and `docs/joke-shop-map.md`. +- [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev` + pass, and record the deviations that stay accepted. +- [ ] After the pass, regenerate the venue captures and update README plus both venue documents. - [ ] Hooded/winter portrait: close the deferred close-up by staging a types 5–7 capture (`--portrait-type`) or adding a scenario spawn that provides one. -### E. Gates and documentation +### E. Reference images, concept boards and screenshots + +*Skill route: `lookdev`, `lighting`, `environment-artist`, `qa-review`; tooling: +`tools/scene_concepts.py`, `tools/screen_designs.py`, `tools/asset_pipeline.py`.* + +Licensed photos are evidence of what a place looks like, generated boards are art-direction +proposals, and captures are proof that the build matches. Keep the three labelled and separate, +and never ship a generated or downloaded image without provenance. + +- [ ] Create `docs/screens/refs/` with a README and a sidecar template: source URL, author, + licence/attribution, capture or generation date, what it is evidence for, and whether it is + shipped or development-only. +- [ ] Collect licence-cleared real-location photos for each venue (Wikimedia Commons, own captures, + and Mapillary only where its licence allows) into per-venue boards there. No Street View, + no scraped social media; link each board from its venue map doc. +- [ ] Generate one concept board per venue with `tools/scene_concepts.py generate` (palette, facade + rhythm, lighting), keep raw output gitignored, commit only the selected board, and record the + model, prompt and spend in the sidecar. +- [ ] Build a three-up sheet per venue (real photo | generated concept | current build capture) and + use it as the reference for the character, prop and venue verdicts. +- [ ] Apply the screenshot rule to every workstream: each accepted fix updates the relevant row in + `README.md` plus the matching docs page (`docs/blender_previews/README.md`, + `docs/screenshots/README.md`, `docs/3d-model-review.md` or the venue map doc). +- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py` after gallery changes + and record both results in the handoff. +- [ ] Keep AI-generated images out of `assets/` until they are picked, cropped, credited and (for + textures) audited; `CREDITS.md` and ADR-0015 still govern provenance. + +### F. Gates and documentation - [x] Add the measurable checks the review needs (texel density, weight/pose sanity, collider coverage, LOD/impostor check) as stdlib or GDScript gates where possible; CI stays offline. @@ -209,6 +256,8 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve hood/cup; prototype sheet committed.) - [ ] Re-derive the four approved specs against the re-evaluated character baseline (face, hands, proportions, gear offsets) so the new variants do not reintroduce the gaps the review found. +- [ ] Generate the four variants through the assisted pipeline (procedural generator → `inspect` → + `audit`/`fit`) and capture the result before committing any of them. - [ ] Add the four approved specs to `CHARACTERS`, build and commit their GLBs/AO maps, and update the manifest with roles and tint data. Build only the new assets, never a no-op full rebuild, and remember that `export_filter="all_resources"` packs committed GLBs into the @@ -217,6 +266,11 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve tests for repeatability and duplicate avoidance (`godot-export` contract check included). - [ ] Rebuild and verify gear fit for every new variant (`blender_assets.py fit` plus the runtime gear checks) and re-run `inspect` on the four new GLBs. +- [ ] Build the crowd-variety reference board (licensed street-crowd photos plus AI proposals) and + compare it with the approved Blender prototypes before building; keep proposals + development-only and record them in `docs/npc-model-sourcing.md`. +- [ ] Capture the four new variants in the neutral baseline and a portrait set, add the rows to + `docs/npc-visual-review.md` and the README character row when they land. ### QA and release @@ -266,10 +320,12 @@ facades and AI-assisted composition. This is an unversioned development track, n - [ ] Write a reference shot list per block: facade materials, windows, signage, rooflines, street furniture, curb cuts and lighting. - [ ] Download and catalogue reference images from Wikimedia Commons, local/own photography or - other clearly licensed sources; record author, licence and attribution. Do not use - unlicensed Street View or scraped commercial imagery. + other clearly licensed sources; record author, licence and attribution with the §E sidecar + template. Do not use unlicensed Street View or scraped commercial imagery. - [ ] Separate development-only references from shipped textures; commit only images with clear redistribution rights and keep the rest under `tmp/` or the ignored reference folders. +- [ ] Build the per-block real-photo board under `docs/screens/refs//` using the sidecar + template from the 3D review §E, and link it from the venue map documents. - [ ] Define the photoreal target and a material-derivation workflow (albedo/normal/roughness, AO, weathering) that matches the existing Compatibility renderer (`texture-workflow`, `materials`, `lookdev`). @@ -284,12 +340,28 @@ facades and AI-assisted composition. This is an unversioned development track, n - [ ] Build a reusable photoreal facade kit (window bays, cornices, storefronts, awnings, signage) with `environment-artist`/`hard-surface`/`geometry-nodes` so buildings share materials and stay inside the venue triangle/material budgets. -- [ ] Add an AI-assisted composition step for palette, facade rhythm and reference boards; record - the model, prompt and output, and keep human review as the acceptance gate. AI output must - not be treated as licensed map data or shipped without provenance. +- [ ] Run the assisted Blender pipeline end to end on the first block (OSM import → `inspect` → + retopo/UV assist → atlas → `audit`), and document the exact commands in + `docs/asset-tooling.md`. - [ ] Integrate the result behind `WorldBuilder.VENUE_SPECS` with colliders, navigation obstacles, occlusion and the existing day/night materials. +### Generated location imagery + +*Skill route: `lookdev`, `lighting`, `environment-artist`, `texture-workflow`; tooling: +`tools/scene_concepts.py`, `tools/asset_pipeline.py`, `tools/screen_designs.py`.* + +- [ ] Generate facade, street and signage concept frames for the target block + (`scene_concepts.py generate`), commit only the selected frames, and record model, prompt and + spend in the block sidecar. +- [ ] Derive palette, lighting and material targets from the real-photo board and the generated + concepts, and record the deltas the facade kit has to close. +- [ ] Generate signage, awning and poster texture candidates with `asset_pipeline.py`; run the + role audit and the `CREDITS.md` provenance check before anything is used in the kit. +- [ ] Compare generated concepts against the licensed photos: where they disagree, the photos win + for shape and the generated board only informs colour, mood and detail density. Human review + stays the acceptance gate, and AI output is never treated as licensed map data. + ### Gaussian splatting evaluation: photo intake and provenance Gaussian splatting is evaluated as a photo-driven pipeline: licensed or permissioned photos @@ -384,6 +456,10 @@ reference-image licence and privacy gates above rather than replacing them. the stylized fallback available. - [ ] Run the venue triangle/mesh budget, navigation and collider checks, plus day/night capture comparisons. +- [ ] Capture day/night gallery frames of the new block and add before/after rows to `README.md` + and the venue map documents. +- [ ] Re-run `tools/check_screenshots.sh` after the map swap so the 21-shot gallery reflects the + new geometry, and refresh the `docs/screens/refs/` three-up sheets. - [ ] Update `docs/architecture.md`, the venue map documents, `docs/asset-tooling.md`, `docs/development-status.md` and `CHANGELOG.md` when the pipeline ships or a source is rejected. @@ -408,6 +484,15 @@ task, not on a schedule. corrected on 2026-11-03); add a documentation check or grep note only if the same class of drift returns. +### Reference and generated imagery upkeep + +- [ ] Keep `docs/screens/refs/` sidecars, concept-board records and `CREDITS.md` in sync whenever an + image is added, replaced or dropped, including the model/prompt for generated boards. +- [ ] Run `python3 tools/check_docs.py` after any gallery or reference-board edit so every tracked + image stays linked from its folder README. +- [ ] Delete or ignore development-only photos and raw generations once a board is committed; the + repository carries the picks and their provenance, not the working set. + ### Blender skills upkeep - [ ] Re-check the installed Blender pack (`version.json`) when updating it and record the version @@ -594,8 +679,11 @@ order. Only a release-blocking defect from those tracks may enter this milestone - [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`, `docs/getting-started.md`, `docs/smoke-checklist.md`, `CHANGELOG.md` and this roadmap. -- [ ] Regenerate the full screenshot gallery and realism baselines after content lock; run - `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts. +- [ ] Regenerate the full screenshot gallery and realism baselines from the release-candidate + build (not the dev tree) after content lock; run `check_screenshots.sh` and the pinned vision + judge, recording model/spend/verdicts, and refresh the README and venue-doc images. +- [ ] Include the reference/concept boards and the updated asset sheets in the release docs, and + verify every README and docs-page image resolves from the tagged build. - [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence. - [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings. - [x] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.