gig-line/Docs/reviews/0.1.4-review.md

# 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.