From 71c7ca734bf0a67a8d4f2af8f993f053fbffb819 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sun, 8 Nov 2026 20:37:32 +0100 Subject: [PATCH] docs(arch): realism leads the quality list; performance moves to the end MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner decision: prioritise realism, keep the performance target but put it last. Re-applied on a branch after the first attempt landed directly on main (reverted there; see b8209ce). - Quality goals (01 + combined architecture.md): 1 visual realism, 2 geographic fidelity, 3 walkability/usability, 4 reproducibility/portability, 5 provenance, 6 performance efficiency. - Quality requirements (10 + combined) reordered to match, with two realism requirements added (a façade reads like the photographs; placement within ~1 m) and the scenarios renumbered so QS-1 is the reference comparison, QS-9 the frame rate. - Guard on both documents so the order cannot become an excuse: performance is a floor, not a preference - 60 FPS at 1440p without frame generation must be met at every release; if realism cannot fit, cut the realism scope deliberately and record it, never the frame rate. Walkability outranks realism in one direction: a block you fall through is not a demo. - Solution strategy and 'quality achievement' lead with realism and describe performance as a budget, not a driver. - Docs/release-checks.md: the performance check is the last section and the per- version check list now opens with realism and closes with performance. - ROADMAP gains a 'Quality priority' section; AGENTS.md gains the tie-break rule beside the existing scope-cutting rule. --- AGENTS.md | 1 + .../Architecture/01_introduction_and_goals.md | 9 ++-- Docs/Architecture/04_solution_strategy.md | 3 +- Docs/Architecture/10_quality_requirements.md | 40 ++++++++------ Docs/Architecture/architecture.md | 53 ++++++++++++------- Docs/release-checks.md | 24 +++++---- MEMORY.md | 16 ++++++ ROADMAP.md | 4 ++ 8 files changed, 101 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f03b30..676b7db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,7 @@ Rules for `TODO.md`: - When **all** steps in a version section are done: write a short descriptive entry to `CHANGELOG.md`, remove the version section from `TODO.md`, and leave its goal in `ROADMAP.md`. - Release checks for each version are listed at the end of its `TODO.md` section; `Docs/release-checks.md` defines the checks themselves. If a check fails, do not tag the release; open a patch task in `TODO.md` and report the failing check in `CHANGELOG.md`. - Finish each milestone's release checks **before** expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience. +- **Realism leads, performance is a floor.** When a realism improvement costs frame time, realism wins and the cost is paid — but 60 FPS at 1440p without frame generation must still be met at every release. If realism cannot fit the budget, reduce the realism scope deliberately and record it in `CHANGELOG.md`; never ship below the floor without the owner's approval. Walkability outranks realism in one direction only: a block the player falls through is not a demo. ## Git workflow diff --git a/Docs/Architecture/01_introduction_and_goals.md b/Docs/Architecture/01_introduction_and_goals.md index 7b7d8a7..c5e9aaf 100644 --- a/Docs/Architecture/01_introduction_and_goals.md +++ b/Docs/Architecture/01_introduction_and_goals.md @@ -20,11 +20,14 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio | Priority | Quality Goal | Scenario | | --- | --- | --- | -| 1 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation | -| 2 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) | -| 3 | **Geographic fidelity** | Building placement, street scale, and façade identity match reference photography | +| 1 | **Visual realism** | Renders read as the reference photographs: façade identity, proportion, material and light — judged side by side, shot against photo | +| 2 | **Geographic fidelity** | Building placement and street scale match the measured data and the photographs | +| 3 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) | | 4 | **Build reproducibility** | Fresh checkout + documented engine path produces a runnable Linux build | | 5 | **Provenance** | Every committed asset has recorded provenance | +| 6 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation | + +**How the order is used.** It decides trade-offs. When realism and performance disagree, realism wins and the cost is paid — but never by silently shipping a frame rate below the floor. The 60 FPS figure is a **budget that must still be met**, so the response to "realism costs too much frame time" is to cut the realism feature deliberately, record the cut, and keep the floor — not to let frames slip. Walkability outranks realism in one direction only: a beautiful block the player falls through is not a demo. ## Stakeholders diff --git a/Docs/Architecture/04_solution_strategy.md b/Docs/Architecture/04_solution_strategy.md index d58cd61..7f7d693 100644 --- a/Docs/Architecture/04_solution_strategy.md +++ b/Docs/Architecture/04_solution_strategy.md @@ -30,7 +30,8 @@ All modelling and geographic processing live outside the game project in `Art/`, ## Quality achievement -- **Performance**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry). +- **Realism first**: reference photography and measured data drive every façade decision; renders are compared against the photographs with `Tools/visual_loop.py`, and a façade is built from the shared 4.96 m module kit so the street wall reads consistently. Materials are authored in Unreal with world-aligned generated textures, and lighting is fixed daytime so a shot is comparable between runs. +- **Performance as a budget, not a driver**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw for street-level geometry, and a 60 FPS at 1440p floor that every release must meet. It closes the quality list because it constrains how much realism fits, not what the block should look like. - **Walkability**: complex-as-simple collision on terrain (C++ helper forces the flag on the asset), block-all collision on every site mesh, swept transect QA verifies zero raycast holes. diff --git a/Docs/Architecture/10_quality_requirements.md b/Docs/Architecture/10_quality_requirements.md index 255c0f1..6a5a48c 100644 --- a/Docs/Architecture/10_quality_requirements.md +++ b/Docs/Architecture/10_quality_requirements.md @@ -2,24 +2,34 @@ ## Quality Requirements Overview -| Category | Requirement | Priority | +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). + +| Priority | Category | Requirement | | --- | --- | --- | -| Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | 1 | -| Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | 1 | -| Accuracy / Fidelity | Building placement matches reference photography within ~1 m | 2 | -| Accuracy / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of measured profile | 2 | -| Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | 2 | -| Maintainability | Fresh checkout builds with documented engine installation | 2 | -| Portability | Linux build packages and runs; Windows build ships | 3 | +| 1 | Realism / Fidelity | Façade identity, proportion, material and lighting read like the reference photographs when compared side by side | +| 2 | Realism / Fidelity | Building placement matches the measured footprints and the photographs (within ~1 m) | +| 2 | Realism / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of the measured profile | +| 3 | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | +| 3 | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | +| 4 | Maintainability | Fresh checkout builds with the documented engine installation | +| 4 | Portability | Linux build packages and runs; Windows build ships | +| 5 | Provenance | Every committed asset has a recorded source and licence | +| 6 | Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | + +**Trade-off rule.** Realism leads: when a realism improvement costs frame time, the improvement wins. Performance is still a **floor, not a preference** — 60 FPS at 1440p without frame generation must be met at every release. If realism cannot fit inside that budget, reduce the realism scope deliberately and record the reduction in `CHANGELOG.md`; never ship below the floor without the owner's explicit approval. Walkability outranks realism in one direction: a block the player falls through is not a demo, whatever it looks like. ## Quality Scenarios | ID | Source/Stimulus | Response | Metric | | --- | --- | --- | --- | -| QS-1 | Player walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | -| QS-2 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | -| QS-3 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | -| QS-4 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | -| QS-5 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | -| QS-6 | Game runs on dev workstation at 1440p | Frame rate stable | ≥ 60 FPS, 99th percentile ≥ 55 FPS | -| QS-7 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced | +| QS-1 | Screenshot is compared against its reference photograph | The render reads as the same building | Similarity score and visual match confirmed by the owner; `Tools/visual_loop.py` reports the deltas | +| QS-2 | A façade is placed from measured data | It sits on its verified footprint | World span probed against `Geo/verification/` within ~1 m | +| QS-3 | Player walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | +| QS-4 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | +| QS-5 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | +| QS-6 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | +| QS-7 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | +| QS-8 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced | +| 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. diff --git a/Docs/Architecture/architecture.md b/Docs/Architecture/architecture.md index 2fef2ca..6986eb0 100644 --- a/Docs/Architecture/architecture.md +++ b/Docs/Architecture/architecture.md @@ -27,11 +27,14 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio | Priority | Quality Goal | Scenario | | --- | --- | --- | -| 1 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation | -| 2 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) | -| 3 | **Geographic fidelity** | Building placement, street scale, and façade identity match reference photography | +| 1 | **Visual realism** | Renders read as the reference photographs: façade identity, proportion, material and light — judged side by side, shot against photo | +| 2 | **Geographic fidelity** | Building placement and street scale match the measured data and the photographs | +| 3 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) | | 4 | **Build reproducibility** | Fresh checkout + documented engine path produces a runnable Linux build | | 5 | **Provenance** | Every committed asset has recorded provenance | +| 6 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation | + +**How the order is used.** It decides trade-offs. When realism and performance disagree, realism wins and the cost is paid — but never by silently shipping a frame rate below the floor. The 60 FPS figure is a **budget that must still be met**, so the response to "realism costs too much frame time" is to cut the realism feature deliberately, record the cut, and keep the floor — not to let frames slip. Walkability outranks realism in one direction only: a beautiful block the player falls through is not a demo. ## Stakeholders @@ -129,7 +132,9 @@ All modelling and geographic processing live outside the game project in `Art/`, ## Quality achievement -- **Performance**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry). +- **Realism**: reference photography drives every façade decision, measured data fixes placement and scale, and renders are compared against the photographs (`Tools/visual_loop.py`, `Screenshots/README.md`). One module kit at the 4.96 m bay keeps the street wall coherent; materials are world-aligned and lit by a fixed daytime rig so a shot is comparable between runs. + +- **Performance holds the floor, it does not set the agenda**: dynamic-only lighting (no build step, no static shadow maps), cheap procedural materials, minimal overdraw for street-level geometry, and 60 FPS at 1440p as a budget every release must meet. - **Walkability**: complex-as-simple collision on terrain (C++ helper forces the flag on the asset), block-all collision on every site mesh, swept transect QA verifies zero raycast holes. @@ -450,27 +455,37 @@ Rule: place a building only against a neighbour or street mesh, never in isolati ## Quality Requirements Overview -| Category | Requirement | Priority | +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). + +| Priority | Category | Requirement | | --- | --- | --- | -| Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | 1 | -| Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | 1 | -| Accuracy / Fidelity | Building placement matches reference photography within ~1 m | 2 | -| Accuracy / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of measured profile | 2 | -| Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | 2 | -| Maintainability | Fresh checkout builds with documented engine installation | 2 | -| Portability | Linux build packages and runs; Windows build ships | 3 | +| 1 | Realism / Fidelity | Façade identity, proportion, material and lighting read like the reference photographs when compared side by side | +| 2 | Realism / Fidelity | Building placement matches the measured footprints and the photographs (within ~1 m) | +| 2 | Realism / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of the measured profile | +| 3 | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | +| 3 | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | +| 4 | Maintainability | Fresh checkout builds with the documented engine installation | +| 4 | Portability | Linux build packages and runs; Windows build ships | +| 5 | Provenance | Every committed asset has a recorded source and licence | +| 6 | Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | + +**Trade-off rule.** Realism leads: when a realism improvement costs frame time, the improvement wins. Performance is still a **floor, not a preference** — 60 FPS at 1440p without frame generation must be met at every release. If realism cannot fit inside that budget, reduce the realism scope deliberately and record the reduction in `CHANGELOG.md`; never ship below the floor without the owner's explicit approval. Walkability outranks realism in one direction: a block the player falls through is not a demo, whatever it looks like. ## Quality Scenarios | ID | Source/Stimulus | Response | Metric | | --- | --- | --- | --- | -| QS-1 | Player walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | -| QS-2 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | -| QS-3 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | -| QS-4 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | -| QS-5 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | -| QS-6 | Game runs on dev workstation at 1440p | Frame rate stable | ≥ 60 FPS, 99th percentile ≥ 55 FPS | -| QS-7 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced | +| QS-1 | Screenshot is compared against its reference photograph | The render reads as the same building | Similarity score and visual match confirmed by the owner; `Tools/visual_loop.py` reports the deltas | +| QS-2 | A façade is placed from measured data | It sits on its verified footprint | World span probed against `Geo/verification/` within ~1 m | +| QS-3 | Player walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | +| QS-4 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | +| QS-5 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | +| QS-6 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | +| QS-7 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | +| QS-8 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced | +| 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. # Risks and Technical Debts diff --git a/Docs/release-checks.md b/Docs/release-checks.md index bf30856..ad2eb14 100644 --- a/Docs/release-checks.md +++ b/Docs/release-checks.md @@ -13,7 +13,19 @@ Record results in the table at the end of this file, with the date, the exact bu 3. **Licensing.** Every new asset has provenance in `THIRD_PARTY_NOTICES.md`, or is recorded as unresolved and kept out of the build. 4. **Version discipline.** Patch releases contain fixes, optimisation, docs, or tuning only — no new scope. -## Performance check +## `0.1.0` checks + +1. **Realism first.** Building placement, street width, sidewalk depth, material read and site identity match the reference photography. Compare side by side and note every deliberate deviation. "Looks right" is not evidence. +2. Player traverses both the south-side frontage and the north-side frontage of the demo without falling through geometry, including the designated crossing. Walk the route twice: once normally, once with collision debug visualisation enabled. +3. No blocking collision, no invisible walls, no gaps at sidewalk/road seams. +4. Fresh checkout builds against the documented external engine installation. +5. Linux build packaged and launched; controls documented in `Docs/` and shown in-game. +6. **Performance last.** 60 FPS at 1440p per the performance check below — a floor every release meets, not the goal that shapes the content. +7. Tag `v0.1.0`, write the `CHANGELOG.md` entry, then remove the completed section from `TODO.md` (its goal stays in `ROADMAP.md`). + +## Performance check (last) + +Performance is the **last** check on purpose: realism leads the design and the frame budget only decides how much of it fits. It is still a floor — a release is not tagged below 60 FPS at 1440p without the owner's explicit approval. Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB. @@ -22,16 +34,6 @@ Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB - Target: 60 FPS at 1440p without frame generation. - Capture a frame-time graph over a fixed traversal route, not a single sample. State the route. -## `0.1.0` checks - -1. Player traverses both the south-side frontage and the north-side frontage of the demo without falling through geometry, including the designated crossing. Walk the route twice: once normally, once with collision debug visualisation enabled. -2. Building placement, street width, sidewalk depth, and site identity match the reference photography. Compare side by side and note every deliberate deviation. "Looks right" is not evidence. -3. No blocking collision, no invisible walls, no gaps at sidewalk/road seams. -4. 60 FPS at 1440p per the performance check above. -5. Fresh checkout builds against the documented external engine installation. -6. Linux build packaged and launched; controls documented in `Docs/` and shown in-game. -7. Tag `v0.1.0`, write the `CHANGELOG.md` entry, then remove the completed section from `TODO.md` (its goal stays in `ROADMAP.md`). - ## Check-record template | Version | Check | Result | Evidence | Date | diff --git a/MEMORY.md b/MEMORY.md index 2b12115..2df3716 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -420,3 +420,19 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO. - Owner reviewed the four demo captures locally and approved the set. Signoff recorded in `Docs/reviews/0.1.4-review.md` (7/7 items) and in the per-shot `Approved` column of `Screenshots/README.md`. - The three geometry items that `0.1.4` did not finish — retail neighbours from their own references, hero fluting/motto band, blockout cleaning — move to a new **`0.1.5` Façade finishing** patch rather than growing this one, plus a much-needed **1440p performance re-measure** (625 kit actors have never been measured; `0.1.0` measured 414 fps). - Decision recorded because it sets a precedent: finish and sign off a version when its _stated_ scope is done, and carry leftover scope into the next patch — do not let a patch accumulate unmeasured geometry. + +## 2026-11-09 — quality priority flipped: realism first, performance last + +- Owner decision: realism leads; performance closes the quality list. Applied in + `Docs/Architecture/01_introduction_and_goals.md`, `10_quality_requirements.md`, + `04_solution_strategy.md`, the combined `architecture.md`, `Docs/release-checks.md` + (performance section now last, with the reason), `ROADMAP.md` (a "Quality priority" + section) and `AGENTS.md` (the tie-break rule next to the scope-cutting rule). +- Ordering used: 1 visual realism, 2 geographic fidelity, 3 walkability/usability, + 4 build reproducibility/portability, 5 provenance, 6 performance. +- **Both revisions carry the same guard so the order cannot be used as an excuse:** + performance is a *floor*, not a preference — 60 FPS at 1440p without frame + generation must be met at every release, and if realism cannot fit, the realism + 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. diff --git a/ROADMAP.md b/ROADMAP.md index c3519b5..de7162b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,6 +2,10 @@ Development roadmap for this project: milestone goals, scope, decisions, and release gates. Actionable tasks, claims, and progress marks live in [TODO.md](TODO.md). +## Quality priority + +**Realism leads; performance is a floor.** Façade identity, proportion, material and light are judged against the reference photographs and drive design decisions. Performance closes the quality list: 60 FPS at 1440p without frame generation is a budget every release must meet, and if realism cannot fit inside it the realism scope is cut deliberately and recorded — never the frame rate. + ## Status at a glance — 2026-11-08 15:30 Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. **Project bootstrap is complete**: `Game/GigLine` builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. **`v0.1.0` released 2026-11-08**: the walkable demo, hero façade, verified block frontage, first-person controls, ODbL attribution, and every release check pass (traversal, placement, collision, 60 fps at 1440p, fresh-checkout build, packaged build with controls). Next: the `0.1.1`–`0.1.4` patch series (collision detail, scale/façade corrections, packaging fixes, real building façades), then `0.2.0` (player body, third-person camera, animation).