zwitschi/gig-line
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plan: give realistic buildings their own minor milestone (0.9.0)

Browse Source 
The facade work started as a patch (0.1.4) and the 0.1.6 retail pass showed what
that costs: a patch has no release gate of its own, so a first pass that does not
yet read as the building can sit inside a done patch series. Realism is also the
leading quality goal, which a patch cannot carry.

New 0.9.0 - Realistic buildings, before the feature freeze: facade system with more
than one order, a profile library, storefront types, signage as decals, per-building
photo-matched models, a measured material library with a texel-density rule, and
LODs plus collision proxies. Former 0.9.0 freeze/beta/audit becomes 0.10.0 with
patches 0.10.1-0.10.3; 1.0.0 moves to weeks 39-44.

Recorded as ADR-8 (append-only) with a measurable gate BR-1..BR-5 in the quality
requirements, mirrored into the combined architecture.md. The 0.1.6 item now says
which of its gaps move to 0.9.0 and why more geometry cannot close them.
This commit is contained in:
zwitschi committed 2026-11-09 09:54:15 +01:00
1 parent c53386fcf4
commit 4132f42ca1
6 files changed
+112 -18
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Docs/Architecture/09_architecture_decisions.md
+8
View File
@@ -55,3 +55,11 @@
- **Decision**: All Blender work driven by Python scripts in `Tools/`. Skill packs used as method guides (checklists, naming, proportions) only.
- **Consequences**: Scripts are version-controlled and repeatable. No live Blender session needed for CI.
## ADR-8: Realistic building façades are a minor milestone, not a patch
- **Context**: `0.1.4` carried the first façade pass as a _patch_, while the release policy says patches contain fixes and refinements and never new scope. The `0.1.6` retail pass then showed what that costs: a façade built in a patch has no release gate of its own, so a first pass that does not yet read as the building (`Screenshots/README.md`, 0.1.6 gaps) can sit inside a "done" patch series. Realism is also the project's leading quality goal, which a patch cannot carry.
- **Decision**: Building realism gets its own minor milestone, `0.9.0 — Realistic buildings`, placed before the feature freeze. Its scope is the façade system (orders, profile library, storefront types, signage as decals), per-building photo-matched models, a measured material library with a texel-density rule, and LODs plus collision proxies. Patches keep fixes and refinements only. Renumbered by this decision: the former `0.9.0` freeze/beta/audit milestone becomes `0.10.0`, its patches `0.10.1`–`0.10.3`, and `1.0.0` moves to weeks 39–44.
- **Consequences**: Façade work now has a release gate — every building measured against its own photograph, every building with a collision proxy and a LOD, no placeholder materials — so "modelled" means verified, not merely present. The price is that realism work stops being sliced into patches, and the schedule shifts by one minor cycle. Blockouts without a photograph stay blockouts and are listed as such, rather than being dressed up to fill the milestone.
Docs/Architecture/10_quality_requirements.md
+10
View File
@@ -33,3 +33,13 @@ Ordered by priority: realism first, performance last. The order decides design t
| QS-9 | Game runs on dev workstation at 1440p | Frame rate holds the floor | ≥ 60 FPS, 99th percentile ≥ 55 FPS |
> QS-9 is last on purpose. Performance is a floor that every release must meet, not the goal that shapes the content: realism decides what gets built, the frame budget decides how much of it.
### Building realism gate (0.9.0)
| ID | Check | Metric |
| --- | --- | --- |
| BR-1 | A building with a reference photograph has a review shot compared against it | Silhouette and proportion deltas recorded per building in `Screenshots/README.md`; owner approval per shot |
| BR-2 | Every building is either photo-matched or explicitly recorded as an unfounded blockout | List in `TODO.md`; no building in an in-between state |
| BR-3 | Every building has a collision proxy and at least one LOD | Count of buildings missing either = 0 |
| BR-4 | No surface carries a placeholder material | Material audit in `Tools/ue_audit_scene.py` reports 0 placeholder slots |
| BR-5 | The realism pass does not break the floor | QS-9 still holds at 1440p, with the measured cost of the pass recorded |
Docs/Architecture/architecture.md
+18
View File
@@ -455,6 +455,14 @@ Rule: place a building only against a neighbour or street mesh, never in isolati
# Quality Requirements
## ADR-8: Realistic building façades are a minor milestone, not a patch
- **Context**: `0.1.4` carried the first façade pass as a _patch_, while the release policy says patches contain fixes and refinements and never new scope. The `0.1.6` retail pass then showed what that costs: a façade built in a patch has no release gate of its own, so a first pass that does not yet read as the building (`Screenshots/README.md`, 0.1.6 gaps) can sit inside a "done" patch series. Realism is also the project's leading quality goal, which a patch cannot carry.
- **Decision**: Building realism gets its own minor milestone, `0.9.0 — Realistic buildings`, placed before the feature freeze. Its scope is the façade system (orders, profile library, storefront types, signage as decals), per-building photo-matched models, a measured material library with a texel-density rule, and LODs plus collision proxies. Patches keep fixes and refinements only. Renumbered by this decision: the former `0.9.0` freeze/beta/audit milestone becomes `0.10.0`, its patches `0.10.1`–`0.10.3`, and `1.0.0` moves to weeks 39–44.
- **Consequences**: Façade work now has a release gate — every building measured against its own photograph, every building with a collision proxy and a LOD, no placeholder materials — so "modelled" means verified, not merely present. The price is that realism work stops being sliced into patches, and the schedule shifts by one minor cycle. Blockouts without a photograph stay blockouts and are listed as such, rather than being dressed up to fill the milestone.
## Quality Requirements Overview
Ordered by priority: realism first, performance last. The order decides design trade-offs; it does not license dropping a lower item silently (see the trade-off rule below the table).
@@ -489,6 +497,16 @@ Ordered by priority: realism first, performance last. The order decides design t
> QS-9 is last on purpose. Performance is a floor that every release must meet, not the goal that shapes the content: realism decides what gets built, the frame budget decides how much of it.
### Building realism gate (0.9.0)
| ID | Check | Metric |
| --- | --- | --- |
| BR-1 | A building with a reference photograph has a review shot compared against it | Silhouette and proportion deltas recorded per building in `Screenshots/README.md`; owner approval per shot |
| BR-2 | Every building is either photo-matched or explicitly recorded as an unfounded blockout | List in `TODO.md`; no building in an in-between state |
| BR-3 | Every building has a collision proxy and at least one LOD | Count of buildings missing either = 0 |
| BR-4 | No surface carries a placeholder material | Material audit in `Tools/ue_audit_scene.py` reports 0 placeholder slots |
| BR-5 | The realism pass does not break the floor | QS-9 still holds at 1440p, with the measured cost of the pass recorded |
# Risks and Technical Debts
| ID | Risk / Debt | Priority | Mitigation |
PLAN.md
+3 -2
View File
@@ -108,8 +108,9 @@ Solo-development estimate: **approximately 30–40 weeks**, subject to asset qua
| `0.6.0` | 22–24 | Visual/audio pass and evening lighting preset | `0.6.1` lighting fixes; `0.6.2` material corrections; `0.6.3` audio balancing |
| `0.7.0` | 25–27 | Settings, control rebinding, save/load, accessibility basics | `0.7.1` save fixes; `0.7.2` UI fixes; `0.7.3` input persistence fixes |
| `0.8.0` | 28–30 | Performance budgets and broader Linux hardware testing | `0.8.1` VRAM reductions; `0.8.2` frame-time fixes; `0.8.3` compatibility fixes |
| `0.9.0` | 31–34 | Feature freeze, public beta, license and build audit | `0.9.1` blocker fixes; `0.9.2` regression fixes; `0.9.3` documentation fixes |
| `1.0.0` | 35–40 | Stable neighborhood-scale walking/driving release | `1.0.x` maintenance and compatibility fixes |
| `0.9.0` | 31–34 | Realistic buildings: façade system, per-building models, measured material library, LODs and collision proxies | `0.9.1` façade fixes |
| `0.10.0` | 35–38 | Feature freeze, public beta, license and build audit | `0.10.1` blocker fixes; `0.10.2` regression fixes; `0.10.3` documentation fixes |
| `1.0.0` | 39–44 | Stable neighborhood-scale walking/driving release | `1.0.x` maintenance and compatibility fixes |
Finish each milestone's release checks before expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience.
ROADMAP.md
+22 -6
View File
@@ -168,22 +168,38 @@ Workstation, geo pipeline, and engine validation are done. The art pipeline has
**Goal:** fix compatibility issues from the hardware testing matrix.
## 0.9.0 — Feature freeze, public beta, license and build audit (weeks 31–34)
## 0.9.0 — Realistic buildings (weeks 31–34)
**Goal:** every building in the demo area reads as the building it is, at walking distance, judged against its own photograph — and where no photograph exists it stays an honest blockout rather than an invented façade. This is the milestone that turns the façade system from "a kit applied to volumes" into architecture: a shared bay-and-profile vocabulary, a material library with measured albedo and roughness, modelled storefronts and signage, and per-building reference matching with a measured tolerance.
**Scope:**
- A façade system that carries more than one order: Art Deco, neoclassical and streamline-moderne variants on the same 4.96 m bay module, with a profile library for cornices, copings, string courses and storefront surrounds.
- Per-building façades for the six south-side buildings and the two north-side buildings inside the 50 m buffer, each from its own reference set; the hero keeps its existing model and gains the detail levels this pass defines.
- Storefronts and signage as first-class geometry plus decals: mullions, bulkheads, recessed entries, awning and canopy brackets, painted wall lettering, blade and projecting signs. Wall lettering is a texture/decal problem, not a block of geometry — the `0.1.6` attempt proved plates do not read.
- A material library with measured values per surface type (stucco, painted render, ashlar, brick, terrazzo, glazing, bronze and steel trim) and a texel-density rule, replacing per-building ad-hoc colours.
- LOD chain and collision proxies per building, so realism does not cost the 60 FPS floor.
**Out of scope:** interiors, night lighting and audio (the `0.6.0` evening preset owns those), vehicles, pedestrians, and any change to footprints or massing — OSM stays the source for those.
**Release gate:** each building has a review shot compared against its own photograph with the silhouette and proportion deltas recorded in `Screenshots/README.md`; no building carries an unverified façade; every building has a collision proxy and at least one LOD; 60 FPS at 1440p holds; no surface is left with a placeholder material; `THIRD_PARTY_NOTICES.md` covers every photographic reference used.
## 0.10.0 — Feature freeze, public beta, license and build audit (weeks 35–38)
**Goal:** freeze features, produce a public beta for testers, and complete the audits: licences for `THIRD_PARTY_NOTICES.md` and all MPFB, texture, animation, vehicle, and audio assets; Epic distribution requirements; and a fresh checkout that builds and packages reproducibly.
## 0.9.1 — Blocker fixes (patch)
## 0.10.1 — Blocker fixes (patch)
**Goal:** fix blockers reported during the public beta.
## 0.9.2 — Regression fixes (patch)
## 0.10.2 — Regression fixes (patch)
**Goal:** fix regressions introduced by `0.9.x` fixes.
**Goal:** fix regressions introduced by `0.10.x` fixes.
## 0.9.3 — Documentation fixes (patch)
## 0.10.3 — Documentation fixes (patch)
**Goal:** update all `Docs/` for accuracy before `1.0.0`.
## 1.0.0 — Stable neighborhood-scale walking/driving release (weeks 35–40)
## 1.0.0 — Stable neighborhood-scale walking/driving release (weeks 39–44)
**Goal:** a final acceptance sweep across all `0.x` features, confirmation that the agreed scope (neighbourhood-scale walking and driving) is met, and final build, documentation, and licensing verification. `1.0.0` marks the stable scope, not completion of a whole city.
TODO.md
+51 -10
View File
@@ -15,7 +15,7 @@ Suggested blender skills: **references** (reference-image-match), **archviz**, *
### Patch tasks - active - session-5598ce7e-27e3-4c64-bb49-c04a4a31ee58 (branch `facade-retail-0.1.6`)
- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`; `Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two. **Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`.
- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`; `Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two. **Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`. **Not fixable by more geometry:** a second pass moved the plates 0.10–0.20 m off the wall and they still do not read at 40 m; wall lettering and the portrait panels need the decal/texture route scoped in `0.9.0 — Realistic buildings`. This patch stops at the trim that does read — cornice, fascia, storefronts, window bars, parapet tiers.
- [D] **Model 6822 Budget.** Deferred: no photograph exists for it (Commons has nothing usable) and the single-storey 6.0 × 5.5 m volume cannot be read from the neighbour shot. Needs photography before it can be modelled honestly; do not substitute the El Capitan Theatre's set or the 6806–6820 shot.
- [ ] Review every façade change with `Tools/render_screenshots.sh --verify` before tagging.
- [ ] Tag `v0.1.6` and write `CHANGELOG.md` entry; then remove this section.
@@ -286,7 +286,48 @@ Suggested blender skills: **references** (reference-image-match), **archviz**, *
- [ ] Fix compatibility issues from the hardware testing matrix.
- [ ] Tag `v0.8.3` and write `CHANGELOG.md` entry; then remove this section.
## 0.9.0 — Feature freeze, public beta, license and build audit (weeks 31–34)
## 0.9.0 — Realistic buildings (weeks 31–34)
Suggested blender skills: **archviz** (real-world scale, façade composition, elevation read), **references** (reference-image-match and visual-match checklists — every building is judged against its own photograph), **procedural-modeling** + **geometry-nodes** (the façades system: bay module, cornice and coping profiles, storefront types as reusable node groups), **materials** (measured albedo and roughness per surface type), **texture-workflow** (baked AO/curvature/normal, decals for painted lettering and signs), **uv-workflow** (texel density and modular UVs), **lod-pipeline** (LOD chain per building), **collision-proxy** (UCX proxies so detail geometry is not the collider), **lookdev** (screenshot comparison loop), **camera-cinematography** (reproducing each building's reference angle), **asset-optimization** + **unreal-export** (pre-export validation, `ue_metric_v1`), **qa-review** (the gate before every review shot).
### Façade system
- [ ] **Extend the module kit beyond one order.** Art Deco, neoclassical and streamline-moderne variants on the shared 4.96 m bay: alternate window proportions, spandrel and transom bands, and the way each order terminates at the roof.
- [ ] **Build a profile library** for cornices, copings, string courses, sills and storefront surrounds, so a building is assembled from named profiles rather than ad-hoc boxes.
- [ ] **Storefront types**: recessed entry, bulkhead and kickplate, mullion spacing, transom, awning/canopy brackets, and grille/shutter variants.
- [ ] **Signage and lettering as decals.** Painted wall lettering, blade signs and fascia panels become texture and decal work with a documented projection; `0.1.6` proved that lettering built as geometry plates cannot resolve at review distance.
- [ ] Document the system in `Art/blender/README.md` and the arc42 building block view.
### Per-building models
Each building needs its own reference set; where none exists the blockout stays and the item says so.
- [ ] Hero façade (6840): raise to this pass's detail level — capitals and fluting, window rhythm behind the colonnade, parapet motto band and medallions.
- [ ] El Capitan Theatre (6838): marquee, blade sign, entrance and the theatre's own elevation from its 18-frame set.
- [ ] 6800 Lee Drug and 6806–6820: second pass on the `0.1.6` trim — parapet profile, mural panels, and the lettering decal.
- [ ] 6822 Budget, 6806–6820 and 6800 photography gap: acquire references before modelling anything not yet photographed, and record the sources checked in `Geo/`.
- [ ] 6902, 6922 and the remaining south frontage.
- [ ] North side: TCL Chinese Theatre and Madame Tussaud's façades from their reference sets.
- [ ] Reconcile every modelled height against `Geo/tools/block_height_report.py` and record the source per building.
### Materials, UVs and performance
- [ ] **Measured material library**: stucco, painted render, ashlar, brick, terrazzo, glazing, bronze and steel trim, with albedo and roughness taken from the photographs rather than guessed; one Unreal material instance per surface type.
- [ ] **Texel-density rule** per building class, applied through modular UVs; lightmap UVs where required.
- [ ] **LOD chain and collision proxies** per building: UCX proxies for blocking volume, detail geometry non-colliding.
- [ ] Re-validate the 60 FPS floor at 1440p once the detail lands, and record the cost of the pass.
### Release checks
- [ ] Every building with a photograph has a review shot measured against it, with silhouette and proportion deltas recorded in `Screenshots/README.md`.
- [ ] No building carries an unverified façade; blockouts without references are listed as such in `TODO.md`.
- [ ] Every building has a collision proxy and at least one LOD.
- [ ] No surface left on a placeholder material.
- [ ] `THIRD_PARTY_NOTICES.md` covers every photographic reference used in this pass.
- [ ] Performance target still met at 1440p.
- [ ] Tag `v0.9.0` and write `CHANGELOG.md` entry; then remove this section.
## 0.10.0 — Feature freeze, public beta, license and build audit (weeks 35–38)
### Freeze and audit
@@ -298,29 +339,29 @@ Suggested blender skills: **references** (reference-image-match), **archviz**, *
### Release checks
- [ ] Beta feedback triaged; blockers logged for `0.9.x`.
- [ ] Tag `v0.9.0` and write `CHANGELOG.md` entry; then remove this section.
- [ ] Beta feedback triaged; blockers logged for `0.10.x`.
- [ ] Tag `v0.10.0` and write `CHANGELOG.md` entry; then remove this section.
## 0.9.1 — Blocker fixes (patch)
## 0.10.1 — Blocker fixes (patch)
### Patch tasks
- [ ] Fix blockers reported during the public beta.
- [ ] Tag `v0.9.1` and write `CHANGELOG.md` entry; then remove this section.
- [ ] Tag `v0.10.1` and write `CHANGELOG.md` entry; then remove this section.
## 0.9.2 — Regression fixes (patch)
## 0.10.2 — Regression fixes (patch)
### Patch tasks
- [ ] Fix regressions introduced by `0.9.x` fixes.
- [ ] Tag `v0.9.2` and write `CHANGELOG.md` entry; then remove this section.
- [ ] Tag `v0.10.2` and write `CHANGELOG.md` entry; then remove this section.
## 0.9.3 — Documentation fixes (patch)
## 0.10.3 — Documentation fixes (patch)
### Patch tasks
- [ ] Update all `Docs/` for accuracy before `1.0.0`.
- [ ] Tag `v0.9.3` and write `CHANGELOG.md` entry; then remove this section.
- [ ] Tag `v0.10.3` and write `CHANGELOG.md` entry; then remove this section.
## 1.0.0 — Stable neighborhood-scale walking/driving release (weeks 35–40)