diff --git a/Docs/reviews/0.1.4-review.md b/Docs/reviews/0.1.4-review.md new file mode 100644 index 0000000..2549ae4 --- /dev/null +++ b/Docs/reviews/0.1.4-review.md @@ -0,0 +1,249 @@ +# Review — `0.1.4` building façades + +A consolidated review of the work on branch **`facades-0.1.4`**, written for the project owner. It states what changed, what is actually verified, what is only claimed, the defects found on the way, and the decisions that need a human. + +Written 2026-11-09. Branch `facades-0.1.4`, 9 commits ahead of `main` (`ba68dcf`), tags `v0.1.0`–`v0.1.3` already released. + +--- + +## 1. Executive summary + +The façades went from **flat extruded boxes with flat colours** to **coursed, textured surfaces assembled from a reusable 16-piece module kit**, with a theatre that finally reads as the El Capitan Theatre (marquee, fascia, blade sign). All build and behaviour checks pass, and 67 tool tests pass. + +**One thing this document cannot do:** tell you the buildings _look_ right. Every defect that survived more than one render in this cycle was a **placement** error that rendered convincingly — a 119 m frame shift, a kit 12 km off, a mirrored marquee. So the visual verdict below is explicitly marked as pending, and there is a toolchain section (§6) for turning it into measurements. + +| Area | State | +| --- | --- | +| Build (editor + game targets, packaged) | **PASS** | +| Behaviour (`-qaselftest`: walk, reset, pause, transect, wall probe, façade probe) | **PASS** (see §7 on flakiness) | +| Tool tests | **67 pass** | +| Geometry placement (verified by coordinate probes) | **PASS** | +| Materials (graph + textures + per-slot) | **Implemented**, visual verdict pending | +| Module kit + assembly on 8 buildings | **Implemented**, visual verdict pending | +| Theatre marquee + blade sign | **Implemented**, visual verdict pending | +| Reference match | **NOT verified** — needs your eyes | +| Release | **Not tagged** — `v0.1.4` waits on review | + +--- + +## 2. Where the project stands + +| Version | Date | Content | +| --- | --- | --- | +| `v0.1.0` | 2026-11-08 | Walkable demo: hero façade, block frontage, first-person controls, ODbL HUD, all release checks | +| `v0.1.1` | 2026-11-08 | Collision patch: sidewalk edge flush, crossing ramps graded to 8 %, QA probes | +| `v0.1.2` | 2026-11-09 | Scale + façade: 3.1 m storey height (Mapbox-calibrated), colonnade 47.6 → 53.1 %, window plane, medallions, hero collision | +| `v0.1.3` | 2026-11-09 | Packaging/setup: importers clear the LFS read-only bit; docs match the pipeline | +| `0.1.4` | **in review** | Façade kit, materials, textures, theatre trim, visual loop | + +--- + +## 3. What `0.1.4` changed + +**89 files, +2 565 / −180.** Nine commits, in order: + +1. **Materials** — masonry coursing and roughness variation in the material graphs; new `M_FacadeStoneShadow`, `M_FacadeGlass` (specular 0.62 ≈ IOR 1.5), `M_FacadeBanner`; **per-slot** material assignment (it was slot-0 only, which on the hero is the banner, so stone and glass were still flat). +2. **Texture maps** — `Tools/generate_facade_textures.py`: deterministic stdlib-only PNGs for ashlar, stucco, asphalt, concrete (base colour + roughness), sampled world-aligned with per-material tiling. +3. **Module kit** — `Tools/facade_kit_build.py`: 16 pieces at the measured **4.96 m bay** / **3.10 m storey**; `ue_import_facade_kit.py`, `ue_apply_facade_kit.py` assemble **625 pieces across 8 buildings**. +4. **Blockout frame correction** — the `0.1.2` regeneration had run without `--origin`; regenerated with the affine fit and re-verified every frontage span. +5. **Kit hygiene** — `SM_` asset naming, per-piece topology validation (all 16 manifold, 12 tris each), stale-asset removal. +6. **QA verdict** — `Docs/qa/0.1.4-facade-qa.md` with budgets, evidence, severities. +7. **Visual loop** — `Tools/visual_loop.py` + `visual_targets.json`: verify captures, measure against references, emit skill-addressed feedback. Iterations gitignored. +8. **Screenshots** — demo-map only; per-shot expectations and a verified column. +9. **Theatre trim** — marquee canopy, illuminated fascia, soffit, blade sign. + +New tools: `facade_kit_build`, `generate_facade_textures`, `theatre_trim_build`, `ue_apply_facade_kit`, `ue_import_facade_kit`, `ue_stage_theatre_trim`, `visual_loop` (+ `visual_targets.json`). New test files: `test_visual_loop`, plus the earlier `test_fbx_export_preset`, `test_ue_common`, `test_mapbox_buildings`, `test_facade_detail_concepts`, `test_block_height_report`, `test_input_emulation`. + +--- + +## 4. Evidence that holds up + +### Behaviour — packaged build, `-qaselftest` + +``` +start XYZ=(-13336,-1150,600) → settled XYZ=(-13336,-1150,456) +walk moved 761 cm in 2 s PASS (Z 456 → 456) +reset returned 0 cm from spawn PASS +pause / unpause PASS +transect 1456 samples, 0 holes PASS +wall probe 0/35 blockers PASS +facade probe 0/9 missing walls PASS +RESULT PASS +``` + +### Placement — probed from the live map, not assumed + +| Building | World X span | Verified against | +| --- | --- | --- | +| 6922 | −24276…−17700 | `Geo/verification/2026-11-06-el-capitan-block.md` | +| 6902 | −17749…−14591 | same | +| **6840 hero** | **−14644…−12028** | sits between 6902 and 6838 ✔ | +| 6838 theatre | −12082…−8210 | same | +| 6822 / 6806 / 6800 | −7854…−1437 | same | +| TCL / Tussaud's | −22889…−18442 / −27071…−22799 | same | + +Blockout affine fit residual **0.0 cm**; kit pieces land inside their building's span (theatre pieces at −12082…−8694). + +### Budgets + +| Asset | Count | Cost | +| ------------- | --------------- | ------------ | +| Hero façade | 148 parts | 3 044 tris | +| Kit | 16 meshes | 12 tris each | +| Kit instances | 625 actors | ~7 500 tris | +| Theatre trim | 6 pieces | boxes | +| Textures | 8 × 512² | 196 KB total | +| Screenshots | 4 demo captures | 11 MB | + +### Tests + +67 tests across 7 files: input driver, height classification, Mapbox cross-check, concept generator, FBX preset, `ue_common`, visual loop (metrics on synthetic images, comparison scoring, feedback rules, target spec). + +--- + +## 5. Defects found this cycle + +Severity per the `qa-review` scale. **Every one of these rendered convincingly.** + +| # | Sev | Defect | Root cause | Caught by | +| --- | --- | --- | --- | --- | +| 1 | Blocker | Frontage shifted ≈119 m X / 2.4 m Y; hero outside its gap | Blockout regenerated **without `--origin`** | Coordinate probe vs verification doc | +| 2 | Blocker | Kit pieces ~12 km from their buildings | Used mesh-local bbox; actors carry the offset | Coordinate probe | +| 3 | Blocker | Marquee on the **far side** of the boulevard | Blender +Y = Unreal −Y; used +10.01 not −10.01 | Coordinate probe | +| 4 | Major | Marquee canopy **5 cm above the pavement** | Absolute Z; pavement is 4.56 m above datum | QA wall probe | +| 5 | Major | Window bays invisible (inside the solid wall) | Piece modelled entirely at +Y | Edge-density flat in iteration metrics | +| 6 | Major | Kit had no materials — glazing wasn't glass | Grey `M_Kit_*` from FBX import, never overridden | QA review pass | +| 7 | Major | Windows floated 1.44 m in front of the wall | Wrong Y in the hero builder | Mesh measurement | +| 8 | Major | Medallions were pancakes on the coping | Built with the Z-axis cylinder helper | Mesh measurement | +| 9 | Major | Hero had **no usable collision** — walk through it | Complex-only; traces use simple | New façade probe | +| 10 | Minor | "No smoothing group information" on every import | `mesh_smooth_type="OFF"` in six exporters | Import logs | +| 11 | Minor | `save_map()` returning False silently | LFS `.umap` read-only; importers never chmod'd | Log read (`save_map: False`) | +| 12 | Minor | North-buildings import silently no-op (exit 255) | Missing `import sys` | Import result file | +| 13 | Minor | Kit folder held 24 assets (8 orphan materials) | No stale-asset sweep | Asset probe | +| 14 | Minor | Edge-density metric counted PIL's border ring | `FIND_EDGES` leaves a 128 ring | Unit test on a flat image | +| 15 | Minor | QA wall probe grazed the theatre wall | Scan row 1 cm from the building line | QA FAIL | + +**Pattern worth keeping:** 3 of the 4 blockers were _coordinate_ errors caught by probes, not by pictures. The probes are now permanent (`-qaselftest`, kit/asset probes, `visual_loop --verify`). + +--- + +## 6. The iteration toolchain (`Tools/visual_loop.py`) + +``` +reference photo ─┐ + ├─ compare ─► metrics + feedback ─► skill-named actions +demo capture ──┘ │ + └─ next iteration (uncommitted) +``` + +- **`--verify`** — gates each capture against its expectation in `Tools/visual_targets.json`: missing, blank, tone-less or wrong-size shots fail. +- **`--compare`** — luminance, RMS contrast, **edge density**, palette distance and a 3×3 luma grid, scored 0–1. +- **`--iteration N`** — writes `Art/reference/iterations/N/{metrics.json,feedback.md}`. **Gitignored** until you confirm a shot; only confirmed shots reach `Screenshots/`. +- Feedback names the skill to consult (`blender-modeler`, `archviz`, `materials`, `lookdev`, `camera-cinematography`). + +### Current measurements (iteration 4) + +| Shot | Score | Δ luma | Contrast | Edges | Palette | Composition | +| --- | --: | --: | --: | --: | --: | --: | +| demo-spawn-view | **0.68** | −9 | ×0.85 | ×0.28 | 18.2 | r=0.54 | +| demo-street-level | 0.33 | +39 | ×0.70 | ×0.27 | 67.7 | r=−0.91 | +| demo-crossing | 0.42 | +32 | ×0.70 | ×0.34 | 22.2 | r=−0.33 | +| demo-north-buildings | 0.34 | −44 | ×0.77 | ×0.14 | 61.9 | r=−0.46 | + +**Read this carefully.** Edge density is **0.14–0.34×** the reference everywhere — the render still carries a fraction of the relief in the photographs. The low scores are not a bug in the metric, but they are also **not a fair verdict on the buildings**: a wide block view compared with a tight façade crop will always report low edge similarity and poor composition correlation. Treat the scores as a _trend across iterations_, not as an absolute quality number. + +--- + +## 7. Known limitations + +1. **The QA self-test is time-based and can flake.** One run reported `walk 246 cm` and `pause FAIL`; an immediate re-run reported `761 cm` and `pause PASS` with identical content. Likely a starved process or a second instance. **Do not trust a single FAIL — re-run before acting**, and prefer two consecutive passes before calling a release good. +2. **The vision pre-check is unreliable on this content.** It has rejected shots you have since approved, and it disagreed with itself between runs. It stays advisory; it is never a gate. +3. **Kit pieces are boxes.** No reveals, sills or mouldings beyond the kit's bands. That is the intended fidelity for this patch — the kit is the vocabulary. +4. **`M_Kit_*` materials are deleted at import**; the Unreal material set is authoritative, the Blender materials carry no shading intent. +5. **Textures are generated, not authored.** They are deterministic and repeatable but generic: no decals, no signage text, no weathering maps. +6. **Cornice dentil spacing, abacus and plinth dimensions are assumptions** — the reference photography does not resolve them at our scale. +7. **`Screenshots/` holds 4 demo captures only** by design; the review staging map is no longer rendered for review. + +--- + +## 8. What is _not_ verified (this is what needs you) + +- **Does the block look like Hollywood Boulevard?** Compare `Screenshots/demo/*` against `Art/reference/hollywood/` and `Art/reference/el-capitan-*`. The metrics say the render is flatter and lighter than the photographs; only you can say whether it reads as the place. +- **Does the theatre read as the El Capitan?** Marquee proportions (12.0 × 2.6 m at a 4.6 m soffit) and blade sign (1.3 × 5.2 m) are assumptions from the reference set, not measurements. +- **Do the shopfronts and window rhythm look right at street level?** +- **Are the 4 shots in `Screenshots/README.md` approved?** Each row has a verified column for the mechanical check; approval is still yours. + +--- + +## 9. Decisions taken + +| Decision | Rationale | +| --- | --- | +| **Adopt Mapbox heights** (3.1 m per level + 3 overrides) | Second independent source; block now 66 matches, 0 disagreements | +| **Blosm `setupScript` style closed as superseded** | The module kit already gives every building an elevation; a second system would duplicate it with different assumptions | +| **Screenshots are demo-map only** | The review staging map is not what ships; a reviewer should see the game | +| **Iterations stay uncommitted** | Prevents unconfirmed geometry becoming "the record" | +| **Vision model advisory, never a gate** | Demonstrably unreliable on this content | +| **Textures generated, not committed** | Deterministic, reproducible, keeps the repo lean (196 KB regenerated on demand) | + +--- + +## 10. Risks for the next cycle + +1. **Placement drift is the dominant failure mode** (3 blockers in one patch). Any new asset should be probed for its world span before it reaches a render. +2. **The kit is not yet a _measured_ vocabulary.** Bay and storey are measured; the pilaster depth, sill projection and fascia height are assumptions. Scaling this to the remaining 7 buildings multiplies the assumption count. +3. **QA flakiness** (§7.1) could mask a real regression or manufacture a false one. +4. **Reference coverage is thin for the retail neighbours** — the 18-frame set is the El Capitan Theatre, not 6806/6822/6800. +5. **No performance measurement since `0.1.0`.** 625 kit actors and 8 textures have not been measured against the 60 fps budget (it had enormous headroom: 414 fps). + +--- + +## 11. Recommended next steps + +| # | Action | Why | +| --- | --- | --- | +| 1 | **Review `Screenshots/demo/*` and the 4 README rows** | The only unverified claim left | +| 2 | Decide whether to tag `v0.1.4` as-is (kit + materials + trim) and move the remaining geometry to `0.1.5`/`0.2.0` | The remaining items are scope, not fixes | +| 3 | Re-measure 1440p performance with the kit in place | 625 new actors, never measured | +| 4 | Retail neighbours from their own references (not the theatre's 18-frame set) | Prevents misattributed façades | +| 5 | Hero fluting + motto band as geometry | Last hero detail from `0.1.4` | + +--- + +## 12. How to verify any of this yourself + +```bash +# build + behaviour +cd /run/media/system/DATA/Engines/UE_5.8.4 +Engine/Build/BatchFiles/Linux/Build.sh GigLine Linux Development \ + -project=/run/media/system/DATA/Documents/06-games/gig-line/Game/GigLine/GigLine.uproject -WaitMutex +cd /run/media/system/DATA/Builds/GigLineQA/Linux +./GigLine.sh -windowed -ResX=1280 -ResY=720 -nosplash -qaselftest +grep "GigLine QA:" GigLine/Saved/Logs/GigLine.log + +# tool tests +cd /run/media/system/DATA/Documents/06-games/gig-line +python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py' + +# screenshots + verification + measurements +Tools/render_screenshots.sh --verify +python3 Tools/visual_loop.py --compare --iteration 5 +``` + +--- + +## 13. Appendix — tool inventory added this cycle + +| Tool | Purpose | +| --- | --- | +| `facade_kit_build.py` | 16-piece module kit at the 4.96 m bay / 3.10 m storey, with topology validation and a part report | +| `ue_import_facade_kit.py` | Import to `/Game/Hollywood/Kit`, complex-as-simple collision, stale-asset sweep | +| `ue_apply_facade_kit.py` | Assemble the kit from each building's **world** bounds (625 pieces) | +| `generate_facade_textures.py` | Deterministic stdlib PNG generator for 4 surface sets | +| `theatre_trim_build.py` | Marquee, fascia, soffit, blade sign in world coordinates | +| `ue_stage_theatre_trim.py` | Import + stage the theatre trim with site materials | +| `visual_loop.py` / `visual_targets.json` | Verify captures, measure against references, emit skill-addressed feedback | +| `fbx_export_preset.py` | One export preset (was six copies); exports smoothing groups | +| `ue_common.py` | Clear the LFS read-only bit, make save failures loud | + +Document written by the agent that did the work; it is deliberately blunt about what it could not check.