MEMORY.md

@@ -436,3 +436,19 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO.
   scope is cut deliberately and recorded in `CHANGELOG.md`, never the frame rate.
   Walkability outranks realism in one direction: a block the player falls through is
   not a demo.
+
+## 2026-11-09 — 0.1.5 start: retail reference + kit layout maths
+
+- Commons holds exactly **one** usable reference for the retail run:
+  `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA
+  4.0, 1920×953) — 6800 Lee Drug **and** its neighbour at street level, shopfronts
+  and parapets visible (vision pre-check: yes). Nothing for 6822 or 6806–6820, so
+  those two façades still have no reference and stay blocked.
+- **Kit layout was wrong for tall/wide buildings**, not just ugly: bays were
+  `round(width / 496)`, so 6922 (65.8 m wide, 37.1 m tall) got **13 bays** — a
+  window every 4.96 m across the whole frontage — and the storey count came out at
+  11 × 310 cm = 34.1 m against a 35.7 m window zone, leaving bare wall under the
+  cornice. Fixed: `MAX_BAYS = 9` (module widens instead of subdividing), and the
+  storey spread is derived from the available height (`usable / storeys`) so the top
+  band always lands inside the building. Result: 6922 9 × 11, theatre 8 × 6,
+  6806 7 × 3, 6800 4 × 3, TCL 9 × 5.

TODO.md

@@ -17,7 +17,7 @@ The `0.1.4` kit, materials and theatre trim are signed off; these are the geomet
 
 ### Patch tasks
 
-- [ ] **Retail neighbours (6822 Budget, 6806–6820, 6800 Lee Drug) from their own references.** The 18-frame set is the El Capitan Theatre, so it cannot stand in for these façades. Fetch or shoot per-building references first, then model the shopfront line and upper storeys rather than relying on the kit alone.
+- [A] **Retail neighbours (6822 Budget, 6806–6820, 6800 Lee Drug) from their own references.** **Started 2026-11-09.** Fetched the one usable reference Commons holds for this run — `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0, 1920×953) — which shows 6800 **and** its neighbour at street level; the vision pre-check confirmed shopfronts and parapets are visible. The 18-frame theatre set cannot stand in for these façades, and Commons has nothing else for 6822 or 6806–6820, so per-building references for those two remain the blocker. **Kit layout fixed while here:** bay count was `round(width / 4.96)`, which gave 6922 thirteen bays across 65.8 m (a window every 4.96 m on a 37 m block) and left bare wall under the cornice; bays are now capped at 9 with the module widened, and the storey spread fills the available height (6922 9 × 11, 6806 7 × 3, 6800 4 × 3, theatre 8 × 6).
 - [ ] **Hero façade: fluting and the motto band as geometry.** The colonnade is plain cylinders and the motto/medallions are flat panels; both are legible in the reference photography.
 - [ ] **Blosm blockout cleaning pass.** Roofs and facades remain untextured volumes and the `setupScript` styles stay unused; with the kit carrying the elevations, this is now cleanup rather than a second façade system.
 - [ ] **Re-measure 1440p performance** with 625 kit actors and 8 generated textures in the map. `0.1.0` measured 414 fps average, so there is headroom, but it has not been re-run since.

Tools/ue_apply_facade_kit.py

@@ -123,12 +123,28 @@ def apply_to_actor(actor, kit, materials=None, prefix=None):
             f"({width / 100:.1f} x {height / 100:.1f} m)")
         return 0
 
+    # Bays: the kit module is one window bay (4.96 m). A very wide building gets a
+    # bay count that keeps the rhythm readable rather than one window per 4.96 m of
+    # frontage — 6922 is 65.8 m wide, which is 13 bays, giving a window every 4.96 m
+    # across a 37 m tall block: the rhythm reads as a wall of glass, not a building.
+    # Above MAX_BAYS the module is widened instead, so the bay count stays legible.
+    MAX_BAYS = 9
     bays = max(1, int(round(width / BAY_CM)))
+    if bays > MAX_BAYS:
+        bays = MAX_BAYS
     bay_w = width / bays                      # actual bay width for this building
     # Street face: the frontage runs along X, and the street is at smaller Y.
     face_y = mn.y
     base_z = mn.z
-    storeys = max(1, int((height - SHOP_FLOOR_CM) // STOREY_CM))
+    # Storeys never overrun the volume: cap the count so the top band (cornice +
+    # parapet, 145 cm) always lands inside the building.
+    storeys = max(1, int((height - SHOP_FLOOR_CM - 145.0) // STOREY_CM) + 1)
+    top_z = base_z + height
+    # Windows above the shopfront, spread over the available height rather than
+    # assumed to be exactly STOREY_CM apart, so a 37 m block does not leave a gap
+    # of bare wall under the cornice.
+    usable = max(0.0, (top_z - 145.0) - (base_z + SHOP_FLOOR_CM))
+    storey_step = (usable / storeys) if storeys else STOREY_CM
 
     def kit_material(name):
         if materials is None:
@@ -153,7 +169,7 @@ def apply_to_actor(actor, kit, materials=None, prefix=None):
         # upper storeys: window bays
         for storey in range(storeys):
             if "Kit_WindowBay" in kit:
-                z = base_z + SHOP_FLOOR_CM + STOREY_CM * storey + 65.0
+                z = base_z + SHOP_FLOOR_CM + storey_step * storey + 65.0
                 if _spawn(kit["Kit_WindowBay"], unreal.Vector(cx, face_y, z),
                           f"{prefix}window_{bay}_{storey}", kit_material("Kit_WindowBay")):
                     placed += 1