diff --git a/docs/DEVELOPMENT_SETUP.md b/docs/DEVELOPMENT_SETUP.md index d181b57cf8..e206e8e6af 100644 --- a/docs/DEVELOPMENT_SETUP.md +++ b/docs/DEVELOPMENT_SETUP.md @@ -81,7 +81,7 @@ See [CSHARP.md](CSHARP.md). Lua `Engine.*` bindings register on the **client** w ### FreeUSD (default ON) -`USE_FREEUSD=ON` is the CMake default. The library lives in the **Git submodule** `src/external/FreeUSD` ([gopexllc/FreeUSD](https://github.com/gopexllc/FreeUSD)); `./scripts/compile_engine.sh` runs `git submodule update --init` when needed. If the submodule is missing, CMake **FetchContent** can fetch the same pin (network). Init manually with `./scripts/init_optional_submodules.sh --freeusd`. Disable with `./scripts/compile_engine.sh vulkan nofreeusd` or `-DUSE_FREEUSD=OFF`. +`USE_FREEUSD=ON` is the CMake default. The library lives in the **Git submodule** `third_party/FreeUSD` ([gopexllc/FreeUSD](https://github.com/gopexllc/FreeUSD)); `./scripts/compile_engine.sh` runs `git submodule update --init` when needed. If the submodule is missing, CMake **FetchContent** can fetch the same pin (network). Init manually with `./scripts/init_optional_submodules.sh --freeusd`. Disable with `./scripts/compile_engine.sh vulkan nofreeusd` or `-DUSE_FREEUSD=OFF`. See [FREEUSD.md](FREEUSD.md) for mesh import cvars (`r_freeusd`, `r_freeusdPickLargest`, …) and console tools (`usd_info`, `usd_meshes`, `usd_load`, …). Test USDA files: `tests/data/usd/`. @@ -304,6 +304,24 @@ cd build-vk-Release && ctest -C Release --output-on-failure ctest --preset test-vulkan-release ``` +### Renderer Spine static checks (headless) + +For Vulkan renderer, G-buffer, Ambient Visibility, temporal-history, and profile-contract changes, run the Spine static gates before GPU work: + +```bash +./scripts/spine_stability_check.sh # umbrella: profiles + gbuffer/AV + temporal + WBOIT guards +./scripts/gbuffer_av_lifecycle_check.sh # G-buffer / AV soft-fail, presentation teardown/restore +./scripts/temporal_ownership_check.sh # shared temporal resets, weapon-after-TAA, portal isolation +``` + +These scripts grep source contracts only (no GPU). In-game diagnostics after boot or `vid_restart`: + +```cfg +exec demo_gbuffer_av_lifecycle.cfg +``` + +Console: `deferred_gbuffer_status`, `ambient_visibility_status`, `temporal_status`, `havenrp_renderer_status`. Recovery from bad experiments: `exec gfx_safe.cfg` then `vid_restart`. See [RENDERER_SPINE_1.0.md](RENDERER_SPINE_1.0.md) and [RENDERER_CONFIDENCE.md](RENDERER_CONFIDENCE.md). + ## IDE Setup ### VS Code / Cursor diff --git a/docs/README.md b/docs/README.md index 9aeaf0c3a9..fb50ead848 100644 --- a/docs/README.md +++ b/docs/README.md @@ -68,7 +68,7 @@ Documentation is grouped by **tier**. Most files remain at their historical path ## Repository layout (2026) -Top-level symlinks (`engine/`, `runtime/`, `modules/`, `extensions/`, `renderers/`) → canonical `src/*` tree. **Legacy paths under `src/` remain authoritative.** See [core/REPOSITORY_LAYOUT_2026.md](core/REPOSITORY_LAYOUT_2026.md), [core/LEGACY_AND_MODERN.md](core/LEGACY_AND_MODERN.md), and [ENGINE_REORG_PLAN.md](ENGINE_REORG_PLAN.md). +Canonical sources live under **`engine/`**, **`runtime/`**, **`modules/`**, **`extensions/`**, and **`renderers/`** (Phase 5c/5e). **`src/`** is README-only after shim removal; cross-domain `#include` paths still use **`scripts/layout_forwarding_symlinks.sh`** until the include rewrite finishes. See [core/REPOSITORY_LAYOUT_2026.md](core/REPOSITORY_LAYOUT_2026.md), [core/SHIM_REMOVAL_CHECKLIST.md](core/SHIM_REMOVAL_CHECKLIST.md), [core/LEGACY_AND_MODERN.md](core/LEGACY_AND_MODERN.md), and [ENGINE_REORG_PLAN.md](ENGINE_REORG_PLAN.md). ## Archive diff --git a/docs/RENDERERS.md b/docs/RENDERERS.md index ebc9ae7bea..47fc66fef1 100644 --- a/docs/RENDERERS.md +++ b/docs/RENDERERS.md @@ -106,7 +106,7 @@ renderer_deferred_safe vid_restart ``` -This profile sets `r_renderMode 1`, `r_deferredGBuffer 1`, `r_deferredGBufferFill 1`, and `r_deferredLighting 1`. It uses the same **opaque deferred + Forward+ transparent** split as mode 3 (`r_forwardPlusShade 1` on transparent; opaque handoff skips Forward+ add). Prefer `r_ext_multisample 0` for direct material export; MSAA uses depth-fallback fill with `deferredMsaaSafeMaterials` confidence floor. Safe debug: `renderer_deferred_safe`. Shipping default remains `modern_vulkan.cfg` (mode 3). +This profile sets `r_renderMode 1`, `r_deferredGBuffer 1`, `r_deferredGBufferFill 1`, and `r_deferredLighting 1`. It uses the same **opaque deferred + Forward+ transparent** split as mode 3 (`r_forwardPlusShade 1` on transparent; opaque handoff skips Forward+ add). Prefer `r_ext_multisample 0` for direct material export; MSAA uses depth-fallback fill with `deferredMsaaSafeMaterials` confidence floor. Safe debug: `renderer_deferred_safe`. Shipping default remains `modern_vulkan.cfg` → `modern_vulkan_stable.cfg` (**mode 2** Forward+). The G-buffer fill copies scene albedo. On **non-MSAA** FBO frames, opaque PBR shaders **directly export** normals and material (metalness/roughness/AO). **MSAA** forces the depth-derived fallback (default metal/rough/AO=1). Prefer `r_ext_multisample 0` with `modern_vulkan.cfg` for true material export. Fallback defaults: `r_deferredDefaultMetalness`, `r_deferredDefaultRoughness`, `r_deferredNormalEdgeThreshold`. @@ -308,7 +308,7 @@ The old SSAO/HBAO implementation remains available only as mode 1 and as a fallb |------|---------|-------------| | `r_fbo` | 1 | Framebuffer objects (required for PBR, HDR, bloom, MSAA, SMAA, SSAO). Use vid_restart after changing. | | `r_pbr` | 1 | Physically Based Rendering (metalness/roughness, IBL). Requires r_fbo 1. | -| `r_renderMode` | 0 | **0** forward, **1** deferred lighting mode, **2** Forward+ primary, **3** Unified Clustered (heterogeneous shading / lighting ownership). `modern_vulkan.cfg` sets **3**. Latched; `vid_restart`. | +| `r_renderMode` | 0 | **0** forward, **1** deferred lighting mode, **2** Forward+ primary (**Spine shipping default** via `modern_vulkan_stable.cfg`), **3** Unified Clustered (heterogeneous shading / lighting ownership; `modern_clustered.cfg`). Latched; `vid_restart`. | | `r_deferredGBuffer` | 0 | With `r_renderMode` 1/2/3: allocate albedo/normal/material/lighting G-buffer images. `modern_vulkan.cfg` sets **1** as a sidecar. Latched; `r_fbo` 1. | | `r_deferredGBufferFill` | 0 | With G-buffer RTs: copy scene albedo after geometry (mode 3: after opaque). On non-MSAA FBO frames, opaque PBR material shaders directly export normals and material; MSAA/legacy paths keep the depth-derived fallback. Material is RGBA16F: metalness, roughness, AO, source confidence. `modern_vulkan.cfg` sets **1**. | | `r_deferredGBufferDebug` | 0 | Before bloom: show G-buffer on scene color (1=albedo, 2=normal, 3=material, 4=lighting, 5=normal confidence, 6=motion vectors from the main material pass). | @@ -445,6 +445,56 @@ See [HDR_GAPS.md](HDR_GAPS.md) for HDR pipeline gaps, risks, and render order. - Cvars: `r_svgRasterScale`, `r_svgMaxRasterSize`, `r_svgMaxFileBytes` - Use `.svg` files in textures/ or gfx/ for scalable UI elements +### Spine diagnostics and recovery + +Use these when bisecting black frames, temporal trails, AO regressions, resize/`vid_restart` failures, or DEVICE_LOST on the modern Vulkan path. Full exit criteria: [RENDERER_SPINE_1.0.md](RENDERER_SPINE_1.0.md). + +**Headless static gates** (run after renderer/G-buffer/temporal changes): + +```bash +./scripts/spine_stability_check.sh +./scripts/gbuffer_av_lifecycle_check.sh +./scripts/temporal_ownership_check.sh +``` + +**In-game status dump** (packaged as `demo_gbuffer_av_lifecycle.cfg`): + +```cfg +exec demo_gbuffer_av_lifecycle.cfg +``` + +| Command | What it reports | +|---------|-----------------| +| `deferred_gbuffer_status` | G-buffer scaffold extent, generation, fill/lighting/composite availability, soft-fail fallback reason | +| `ambient_visibility_status` | Requested/effective AV mode, TLAS/RTAO readiness, history state, GPU timings, reference-error metrics | +| `temporal_status` | Shared reset reasons (applied/sticky/pending), TAA history validity, weapon-after-TAA, world-matrix capture | +| `havenrp_renderer_status` | Aggregated renderer spine summary (gbuffer, temporal, weapon deferral, lighting rows) | +| `input_status` | Relative mouse / focus lifecycle (Spine presentation path) | + +**Recovery presets:** + +```cfg +exec gfx_safe.cfg +vid_restart + +renderer_modern_safe +vid_restart +``` + +**Dev fail-inject cvars** (`CVAR_CHEAT`, clear to recover without `vid_restart` where noted): + +| Cvar | Values | Effect | +|------|--------|--------| +| `r_dgbFailInject` | `alloc`, `view`, `pipeline`, `descriptor`, `all` | Forces G-buffer soft-fail → legacy SSAO owner; clears when set `0` | +| `r_avFailInject` | `history`, `rtao`, `all` | Demotes AO only (`legacy_ssao`); G-buffer fill stays live. `history` thrash-resets AV temporal each frame | + +**Common pitfalls:** + +- `r_ambientVisibilityMode 4` (adaptive hybrid) is **not** promoted in `modern_vulkan_quality.cfg` until the manual GPU matrix in `gbuffer_av_lifecycle_check.sh` passes. +- Presentation teardown+restore sticky-resets temporal history (`VK_TEMPORAL_RESET_SWAPCHAIN_CHANGE`) and rebinds deferred/AV — expect one-frame resets after resize/alt-tab. +- RDF_NOWORLDMODEL after `doneWorldScene` does not thrash shared temporal history; weapon draws defer until after world TAA when temporal reconstruction is on (`r_temporalWeaponAfterTaa`). +- Set `r_temporalDebug 2` for reset-reason logging during TAA/OIT bisects. + ## Future Renderers (Planned) See [RENDERERS_FUTURE.md](RENDERERS_FUTURE.md) for architecture and implementation plans: diff --git a/docs/RENDERER_2027.md b/docs/RENDERER_2027.md index 0b362d36fe..6ac89a316e 100644 --- a/docs/RENDERER_2027.md +++ b/docs/RENDERER_2027.md @@ -10,8 +10,8 @@ This is more than “deferred plus Forward+.” Shipping today uses those as fou | Layer | Role | |-------|------| -| **`r_renderMode 2`** | Forward+ primary (opt-in overlay / legacy modern path) | -| **`r_renderMode 3`** | [Unified Clustered](UNIFIED_CLUSTERED_RENDERER.md) — unified heterogeneous shading / lighting ownership (2D tiles today; depth clusters planned). **Shipping default** (`modern_vulkan.cfg`) and **spine** for 2027 layers | +| **`r_renderMode 2`** | Forward+ primary — **Spine 1.0 shipping default** (`modern_vulkan.cfg` → `modern_vulkan_stable.cfg`) | +| **`r_renderMode 3`** | [Unified Clustered](UNIFIED_CLUSTERED_RENDERER.md) — unified heterogeneous shading / lighting ownership (2D tiles today; depth clusters planned). **Experimental** until Spine exit; opt-in via `modern_clustered.cfg` | | **2027 target** | Mode 3 + visibility buffer + meshlets + reservoir RT + neural reconstruction | Do **not** invent `r_renderMode 4` for this architecture. Opt-in sidecars stack on mode 3. diff --git a/docs/RENDERER_CONFIDENCE.md b/docs/RENDERER_CONFIDENCE.md index cba97f8f30..fec9c92003 100644 --- a/docs/RENDERER_CONFIDENCE.md +++ b/docs/RENDERER_CONFIDENCE.md @@ -6,7 +6,7 @@ This document lists **automated** checks you can run today and **manual** passes Treat this file as a **default gate** for any change that touches rendering, shaders, mesh tangents, or image loaders used by the renderer: -1. Run **automated** rows in the table below (at minimum `renderer_regression_check.sh` + your usual build). +1. Run **automated** rows in the table below (at minimum `renderer_regression_check.sh` + **`spine_stability_check.sh`** for renderer/G-buffer/temporal changes + your usual build). 2. For **graphics PRs**, run the **manual** short list or note why it is N/A (e.g. docs-only). 3. Prefer **first-party** warning/correctness fixes over new subsystems until the gate is green. @@ -21,6 +21,9 @@ On **`main`**, GitHub Actions **`.github/workflows/build.yml`** runs **`renderer | Check | Command | What it proves | |--------|---------|----------------| | Renderer regression (repo) | `./scripts/renderer_regression_check.sh` | Regression docs present (manifest includes `docs/ARCHITECTURE.md`, `docs/ROADMAP.md`, `BUILD.md`, `docs/FORWARD_PLUS_PIPELINE_AUDIT.md`, `src/renderers/vulkan/vk_temporal.h`, …); `shader_data.c` / `shader_binding.c` exist; recursive GLSL `glslang` pass; IQM/glTF morph **#define** parity; Forward+ **tile cull vs `tr_types.h` / `vk_forward_plus.c`** caps; **`gen_frag.tmpl`** tile stride `tileId * Nu` matches **`MAX_PER_TILE`**; **`r_forwardPlusMaxPerTile`** range wired to `vk_forward_plus_get_*_per_tile_cap`; PBR **`forward_plus_shade_strength`** `constant_id` matches `vk_create_pipeline.c`; Forward+ **`depthCull`** push + depth binding **3**; volumetric VDB binding **17** + **`vdbParams`** UBO fields; **`vk_temporal`** reset bitmask count matches switch + `knownReasons[]` table. Manifest lines strip **CRLF** so Windows checkouts do not false-fail path existence. Optional: set `GAME_BASE` and uncomment BSP paths in `OPTIONAL_GAME_ASSETS.txt` to require packaged maps. | +| **Renderer Spine stability** | `./scripts/spine_stability_check.sh` | Umbrella static contract for [Spine 1.0](RENDERER_SPINE_1.0.md): `modern_vulkan_stable.cfg` / quality / gfx_safe profile pins, mouse `input_status` symbols, WBOIT clears/barriers, packaging. Delegates to `gbuffer_av_lifecycle_check.sh` and `temporal_ownership_check.sh`. | +| **G-buffer / AV lifecycle** | `./scripts/gbuffer_av_lifecycle_check.sh` | Soft-fail create paths for deferred G-buffer, Ambient Visibility, and visibility-buffer scaffolds; presentation teardown/restore order; `r_dgbFailInject` / `r_avFailInject`; descriptor generation; TLAS→AV history invalidation; stable profile keeps `r_ambientVisibilityMode 2`. | +| **Temporal ownership** | `./scripts/temporal_ownership_check.sh` | Shared `apply_resets` (TAA/AV/volumetric/motion/occlusion); RDF_NOWORLDMODEL thrash guard; weapon-after-TAA deferral; portal/world-matrix isolation; `temporal_status` registration; stable profile must not enable `r_taa 1`. | | Map load sanity (content) | `GAME_BASE=/abs/path/to/base ./scripts/renderer_regression_maps.sh` | Dedicated server runs `+map` for each `rtest_*` map; log scanned for `ERROR:`, `couldn't load`, `CM_LoadMap`, crashes. Requires full game base (VM + assets), not the regression pk3 alone. `RELEASE_DIR` optional (default `/release`). Optional `MAPS_EXTRA="name1 name2"` (or repo var `IDTECH3_MAPS_EXTRA` on Tier B self-hosted) appends more BSPs. Mixed dlights checklist: `docs/samples/renderer_regression/scenes/08_tier_b_mixed_dlights.md`. | | Full local CI parity | `./scripts/validate_ci_build.sh` | SPIR-V generation, Vulkan Release build, smoke test, renderer regression check. | | CMake smoke + artifacts | `ctest --output-on-failure` (from `build-vk-Release`) | Smoke, **renderer_regression_check**, artifacts, unit hooks, **demo_game pk3 layout** (`test_demo_game_pk3`). | @@ -138,5 +141,6 @@ That sequence closes the gap between engine-side confidence and renderer evidenc ## See also - [RENDERERS.md](RENDERERS.md) - feature inventory and cvars +- [RENDERER_SPINE_1.0.md](RENDERER_SPINE_1.0.md) - production-certified frame matrix and exit criteria - [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) - pre-release steps - `./scripts/validate_ci_build.sh` - local mirror of Ubuntu CI expectations diff --git a/docs/UNIFIED_CLUSTERED_RENDERER.md b/docs/UNIFIED_CLUSTERED_RENDERER.md index cbd2280dcc..e9486e4575 100644 --- a/docs/UNIFIED_CLUSTERED_RENDERER.md +++ b/docs/UNIFIED_CLUSTERED_RENDERER.md @@ -64,7 +64,7 @@ Also called historically: Hybrid Clustered Deferred Renderer / Deferred + Forwar ## Enable -Shipping default is **`modern_vulkan.cfg`** (`r_renderMode 3`). Equivalent profile: `exec modern_clustered.cfg`. +**Shipping default** is **`modern_vulkan.cfg`** → **`modern_vulkan_stable.cfg`** (`r_renderMode 2` Forward+). Mode 3 is opt-in: `exec modern_clustered.cfg` or `exec vulkan_overlay_unified_clustered.cfg`. ``` exec vulkan_overlay_unified_clustered.cfg