From b8209ce82baf7f9f5ebecda6eebb4cad353ca5c1 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sun, 8 Nov 2026 20:37:19 +0100 Subject: [PATCH] Revert "docs(arch): realism leads the quality list; performance moves to the end" This reverts commit a1d52aa583dd67b8aa39947056b8f1d1d09de3ba. --- 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 | 20 ++++--- MEMORY.md | 16 ------ ROADMAP.md | 4 -- 8 files changed, 47 insertions(+), 99 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 676b7db..0f03b30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,7 +67,6 @@ 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 c5e9aaf..7b7d8a7 100644 --- a/Docs/Architecture/01_introduction_and_goals.md +++ b/Docs/Architecture/01_introduction_and_goals.md @@ -20,14 +20,11 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio | Priority | Quality Goal | Scenario | | --- | --- | --- | -| 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) | +| 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 | | 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 7f7d693..d58cd61 100644 --- a/Docs/Architecture/04_solution_strategy.md +++ b/Docs/Architecture/04_solution_strategy.md @@ -30,8 +30,7 @@ All modelling and geographic processing live outside the game project in `Art/`, ## Quality achievement -- **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. +- **Performance**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry). - **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 6a5a48c..255c0f1 100644 --- a/Docs/Architecture/10_quality_requirements.md +++ b/Docs/Architecture/10_quality_requirements.md @@ -2,34 +2,24 @@ ## 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). - -| Priority | Category | Requirement | +| Category | Requirement | Priority | | --- | --- | --- | -| 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. +| 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 | ## Quality Scenarios | ID | Source/Stimulus | Response | Metric | | --- | --- | --- | --- | -| 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. +| 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 | diff --git a/Docs/Architecture/architecture.md b/Docs/Architecture/architecture.md index 6986eb0..2fef2ca 100644 --- a/Docs/Architecture/architecture.md +++ b/Docs/Architecture/architecture.md @@ -27,14 +27,11 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio | Priority | Quality Goal | Scenario | | --- | --- | --- | -| 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) | +| 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 | | 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 @@ -132,9 +129,7 @@ All modelling and geographic processing live outside the game project in `Art/`, ## Quality achievement -- **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. +- **Performance**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry). - **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. @@ -455,37 +450,27 @@ Rule: place a building only against a neighbour or street mesh, never in isolati ## 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). - -| Priority | Category | Requirement | +| Category | Requirement | Priority | | --- | --- | --- | -| 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. +| 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 | ## Quality Scenarios | ID | Source/Stimulus | Response | Metric | | --- | --- | --- | --- | -| 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. +| 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 | # Risks and Technical Debts diff --git a/Docs/release-checks.md b/Docs/release-checks.md index ef5964b..bf30856 100644 --- a/Docs/release-checks.md +++ b/Docs/release-checks.md @@ -13,6 +13,15 @@ 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 + +Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB. + +- Record the quality preset, the exact upscaling state (off, DLSS/TSR/FXAA and mode), and the engine version. +- Report frame rate without frame generation and with frame generation, separately. +- 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. @@ -23,17 +32,6 @@ Record results in the table at the end of this file, with the date, the exact bu 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`). -## 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. - -- Record the quality preset, the exact upscaling state (off, DLSS/TSR/FXAA and mode), and the engine version. -- Report frame rate without frame generation and with frame generation, separately. -- 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. - ## Check-record template | Version | Check | Result | Evidence | Date | diff --git a/MEMORY.md b/MEMORY.md index 2df3716..2b12115 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -420,19 +420,3 @@ 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 de7162b..c3519b5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,10 +2,6 @@ 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).