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

Revert "docs(arch): realism leads the quality list; performance moves to the end"

Browse Source 
This reverts commit a1d52aa583.
This commit is contained in:
zwitschi committed 2026-11-08 20:37:19 +01:00
1 parent a1d52aa583
commit b8209ce82b
8 files changed
+47 -99
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
-1
View File
@@ -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`. - 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`. - 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. - 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 ## Git workflow
Docs/Architecture/01_introduction_and_goals.md
+3 -6
View File
@@ -20,14 +20,11 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio
| Priority | Quality Goal | Scenario | | 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 | | 1 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation |
| 2 | **Geographic fidelity** | Building placement and street scale match the measured data and the photographs | | 2 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) |
| 3 | **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 | | 4 | **Build reproducibility** | Fresh checkout + documented engine path produces a runnable Linux build |
| 5 | **Provenance** | Every committed asset has recorded provenance | | 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 ## Stakeholders
Docs/Architecture/04_solution_strategy.md
+1 -2
View File
@@ -30,8 +30,7 @@ All modelling and geographic processing live outside the game project in `Art/`,
## Quality achievement ## 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**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry).
- **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. - **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.
Docs/Architecture/10_quality_requirements.md
+15 -25
View File
@@ -2,34 +2,24 @@
## Quality Requirements Overview ## 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). | Category | Requirement | Priority |
| Priority | Category | Requirement |
| --- | --- | --- | | --- | --- | --- |
| 1 | Realism / Fidelity | Façade identity, proportion, material and lighting read like the reference photographs when compared side by side | | Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | 1 |
| 2 | Realism / Fidelity | Building placement matches the measured footprints and the photographs (within ~1 m) | | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | 1 |
| 2 | Realism / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of the measured profile | | Accuracy / Fidelity | Building placement matches reference photography within ~1 m | 2 |
| 3 | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | | Accuracy / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of measured profile | 2 |
| 3 | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | 2 |
| 4 | Maintainability | Fresh checkout builds with the documented engine installation | | Maintainability | Fresh checkout builds with documented engine installation | 2 |
| 4 | Portability | Linux build packages and runs; Windows build ships | | Portability | Linux build packages and runs; Windows build ships | 3 |
| 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 ## Quality Scenarios
| ID | Source/Stimulus | Response | Metric | | 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-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 | A façade is placed from measured data | It sits on its verified footprint | World span probed against `Geo/verification/` within ~1 m | | 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 walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | | QS-3 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` |
| QS-4 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | | QS-4 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true |
| QS-5 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | | QS-5 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false |
| QS-6 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | | QS-6 | Game runs on dev workstation at 1440p | Frame rate stable | ≥ 60 FPS, 99th percentile ≥ 55 FPS |
| QS-7 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | | QS-7 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced |
| 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.
Docs/Architecture/architecture.md
+19 -34
View File
@@ -27,14 +27,11 @@ Full requirements and progress are in [TODO.md](../../TODO.md); version directio
| Priority | Quality Goal | Scenario | | 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 | | 1 | **Performance efficiency** | 60 FPS at 2560×1440 on RTX 5070 Ti, documented preset, no frame generation |
| 2 | **Geographic fidelity** | Building placement and street scale match the measured data and the photographs | | 2 | **Terrain walkability** | Zero raycast holes across both sidewalks and the carriageway (84-sample transect passes) |
| 3 | **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 | | 4 | **Build reproducibility** | Fresh checkout + documented engine path produces a runnable Linux build |
| 5 | **Provenance** | Every committed asset has recorded provenance | | 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 ## Stakeholders
@@ -132,9 +129,7 @@ All modelling and geographic processing live outside the game project in `Art/`,
## Quality achievement ## 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**: dynamic-only lighting (no build step, no static shadow maps), world-space-noise materials (cheap procedural variation), minimal overdraw (simple street-level geometry).
- **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. - **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 ## 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). | Category | Requirement | Priority |
| Priority | Category | Requirement |
| --- | --- | --- | | --- | --- | --- |
| 1 | Realism / Fidelity | Façade identity, proportion, material and lighting read like the reference photographs when compared side by side | | Performance efficiency | 60 FPS at 2560×1440, documented preset, no frame generation | 1 |
| 2 | Realism / Fidelity | Building placement matches the measured footprints and the photographs (within ~1 m) | | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | 1 |
| 2 | Realism / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of the measured profile | | Accuracy / Fidelity | Building placement matches reference photography within ~1 m | 2 |
| 3 | Reliability / Terrain | Zero raycast holes across sidewalks and carriageway (84-sample transect) | | Accuracy / Fidelity | Street scale (lane width, sidewalk width) within ~10 cm of measured profile | 2 |
| 3 | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | | Usability | WASD + mouse look, jump, reset (R), pause (Escape) — no tutorial needed | 2 |
| 4 | Maintainability | Fresh checkout builds with the documented engine installation | | Maintainability | Fresh checkout builds with documented engine installation | 2 |
| 4 | Portability | Linux build packages and runs; Windows build ships | | Portability | Linux build packages and runs; Windows build ships | 3 |
| 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 ## Quality Scenarios
| ID | Source/Stimulus | Response | Metric | | 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-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 | A façade is placed from measured data | It sits on its verified footprint | World span probed against `Geo/verification/` within ~1 m | | 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 walks both sides of the demo | No fall-through, character stays at ground Z | 0 raycast holes in 84-sample transect | | QS-3 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` |
| QS-4 | Player holds W for 2 s on flat road | Character moves forward | ≥ 200 cm displacement, Z constant within ±5 cm | | QS-4 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true |
| QS-5 | Player presses R | Character teleports to spawn | < 100 cm from `StartLocation` | | QS-5 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false |
| QS-6 | Player presses Escape | Game pauses, cursor appears | `IsGamePaused()` = true | | QS-6 | Game runs on dev workstation at 1440p | Frame rate stable | ≥ 60 FPS, 99th percentile ≥ 55 FPS |
| QS-7 | Player presses Escape while paused | Game unpauses, cursor hides | `IsGamePaused()` = false | | QS-7 | Fresh checkout + engine install | Build succeeds | Exit code 0, runnable binary produced |
| 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 # Risks and Technical Debts
Docs/release-checks.md
+9 -11
View File
@@ -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. 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. 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 ## `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. 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. 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`). 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 ## Check-record template
| Version | Check | Result | Evidence | Date | | Version | Check | Result | Evidence | Date |
MEMORY.md
-16
View File
@@ -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`. - 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). - 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. - 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.
ROADMAP.md
-4
View File
@@ -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). 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 ## 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). 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).