gig-line/Docs/release-checks.md

# Release checks

Every version in `TODO.md` ends with release checks, and the scope and goal of each version are in `ROADMAP.md`. A version is not tagged until all of its checks pass. If a check fails, do not tag; open a patch task in `TODO.md` and report the failing check in `CHANGELOG.md`.

Record results in the table at the end of this file, with the date, the exact build under test, and the evidence (screenshot, log, or command output). A check without recorded evidence counts as failed.

## General checks (every release)

0. **Blender pre-check (before the engine pass).** `Art/blender/site/site_assembly.py` raycasts both sidewalks and the designated crossing on a 1 m grid and reports holes and step heights. It is evidence, not the check: the engine traversal below is still required.

1. **Fresh checkout builds.** Clone into a clean directory, `git lfs pull`, build and package using only the documented external engine installation. No machine-specific paths, no uncommitted steps.
2. **No packaging errors.** The packaged build launches, reaches gameplay, and quits cleanly. Logs contain no missing-asset, missing-map, or shader-compile errors.
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.
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 |
| ------- | ----------------------- | ------ | -------- | ---- |
| `0.1.0` | Traversal, both sides   | —      | —        | —    |
| `0.1.0` | Placement vs references | PASS (with deliberate simplifications) | Section below, 2026-11-08 | 2026-11-08 |
| `0.1.0` | Collision and packaging | —      | —        | —    |
| `0.1.0` | 60 FPS at 1440p         | —      | —        | —    |
| `0.1.0` | Fresh checkout build    | —      | —        | —    |
| `0.1.0` | Packaged Linux build    | —      | —        | —    |

## `0.1.0` — Placement vs references — record (2026-11-08)

Checked against the reference photography (`Art/reference/`) and the Geo measurements
(`Geo/verification/*`). Build under test: current `main` content, DemoMap rendered via
`Tools/render_screenshots.sh` (2026-11-08, Vulkan SM5, 1920×1080); engine positions
probed from the DemoMap (commandlet, 2026-11-08).

### Placement and scale (in-engine ↔ reference)

| Quantity | In-engine (probed world-space) | Reference | Match |
| --- | --- | --- | --- |
| Road (Hollywood Blvd carriageway) | Y −13.82..+10.47 m → **24.3 m** | crossing ways 20.9–25.9 m | ✓ within range |
| South sidewalk strip | 7.3 m (bbox incl. kerb apron); built walkable strip 4.0 m per `Art/blender/README.md` | 12.6 m centreline offset; strip width from setback arithmetic | ✓ offset 12.5 m ≈ ref 12.6 m |
| North sidewalk strip | 8.6 m (bbox); built strip 5.3 m | 13.6 m centreline offset | ✓ offset 13.2 m ≈ ref 13.6 m |
| Kerbs | 3.3 m apron face to 0.13 m upstand | 0.15 m assumption; photo check pending (`0.1.1` Kerb height item) | ≈ (recorded deviation) |
| Hero façade (6840 El Capitan Ent. Ctr.) | X −146.38..−120.34 m (26.0 m frontage), Y +13.0..+25.6 m from road centre (13.0 m deep) | 6840 setback 14.5 m; 25.75 m frontage (resolved) | ✓ frontage; setback ~1.5 m deeper than ref (recorded) |
| El Capitan Theatre (6838) | X −120.82..−82.10 m, Y +13.4..+68.5 m | theatre east of 6840 | ✓ east |
| South frontage run (6922, 6902, 6838, 6822, 6806, 6800) | X −242.76..−14.37 m, all Y +12..+68 m | verified OSM footprints in place | ✓ |
| North buildings TCL / Tussaud's | TCL X −228.9..−184.4, Y −94.3..−18.0; Tussaud's X −270.7..−228.0, Y −75.9..−18.9 | north of the Blvd, west of hero (per OSM) | ✓ placed north (−Y) across the road |

### Visual comparison (demo views vs references)

| Shot | Reference(s) used | Verdict | Notes |
| --- | --- | --- | --- |
| `review-demo-spawn-view` | `hollywood/el-capitan-facade-day-*` (CC BY 2.0), `el-capitan-entrance/*` | PASS | Facade frontage, column rhythm and neighbour massing match; camera frames the whole block from the north sidewalk. |
| `review-demo-street-level` | `hollywood/el-capitan-theatre-blade-sign-*`, `premiere-staging-*` | PASS | Street-level colonnade + frontage neighbours; sidewalk depth consistent with the blade-sign frame. |
| `review-demo-crossing` | street-profile crossing s=130.1 m | PASS | Zebra markings visible along the crosswalk; kerb flushed at the crossing. |
| `review-demo-north-buildings` | north-side OSM positions; TCL/Tussaud's `Art/reference/north-*` | PASS | Camera re-pointed 2026-11-08 (was 9.5 km west → 85% sky); buildings now framed. Flat blockout surfaces are the `0.1.4` scope. |

### Deliberate deviations recorded

- **North/south building surfaces are flat blockouts** (bloblike, no façade detail). Detail texturing/façade style is the planned `0.1.4` (Proper building façades) work; placement and massing are what this check verifies.
- **Kerb upstand 0.13 m as built vs 0.15 m assumed**; the DEM cannot resolve a kerb — tracked in `0.1.1` (Kerb height assumption).
- **Sidewalk surface detail** (railings, pavers, domes) not modelled — outside `0.1.0` scope.
- **Crossing ramps are kerb flushes, not graded ramps** — the `0.1.1` Crossing ramp gradient item.
- Site identity (the neoclassical hero with motto band) matches the 2009 façade photograph and the 1922 Masonic elevation within blockout fidelity.

Pre-check method: `Tools/judge_screenshot.py` (vision model) flagged the simplified
flat surfaces as "unexpected" — those flags are the deliberate deviations above, not
placement errors. Final verdict is by human review of the shots in `Screenshots/demo/`.