tests: add regression coverage for run_vulkan launcher selection

.github/workflows/renderer-tier-b.yml

@@ -0,0 +1,84 @@
+# Tier B: content-backed renderer checks (GAME_BASE) on every main push.
+#
+# This job runs only when a repository variable OR secret provides the absolute path
+# to a game **base** directory (see docs/renderer_validation/SELF_HOSTED_TIER_B.md).
+# Prefer variable IDTECH3_GAME_BASE_PATH; use secret of the same name if the path must not appear in Settings UI.
+#
+# Requires a self-hosted runner labeled `idtech3-tierb` (plus `self-hosted`) with:
+#   - GAME_BASE path readable on that machine
+#   - Build deps (same family as docs/DEVELOPMENT_SETUP.md for Linux)
+#   - glslangValidator for renderer_regression_check.sh
+#
+# Note: GitHub does not allow `secrets.*` in job-level `if:` (workflow validation fails).
+# A small ubuntu gate job evaluates var/secret in a step and sets `enabled` for the self-hosted job.
+
+name: renderer-tier-b
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: renderer-tier-b-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tier_b_gate:
+    name: Tier B gate (config check)
+    runs-on: ubuntu-24.04
+    outputs:
+      enabled: ${{ steps.check.outputs.enabled }}
+    steps:
+      - id: check
+        env:
+          GAME_BASE_VAR: ${{ vars.IDTECH3_GAME_BASE_PATH }}
+          GAME_BASE_SECRET: ${{ secrets.IDTECH3_GAME_BASE_PATH }}
+        run: |
+          if [ -n "$GAME_BASE_VAR" ] || [ -n "$GAME_BASE_SECRET" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+            echo "Tier B: IDTECH3_GAME_BASE_PATH is set (variable and/or secret); self-hosted job will run."
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "Tier B: IDTECH3_GAME_BASE_PATH unset — skipping self-hosted regression (forks/engine-only repos)."
+          fi
+
+  gamebase-regression:
+    name: Tier B (GAME_BASE regression)
+    needs: tier_b_gate
+    if: needs.tier_b_gate.outputs.enabled == 'true'
+    runs-on: [self-hosted, idtech3-tierb]
+    env:
+      DEBIAN_FRONTEND: noninteractive
+      # Variable wins if both are set (same rule as docs/renderer_validation/SELF_HOSTED_TIER_B.md).
+      GAME_BASE: ${{ vars.IDTECH3_GAME_BASE_PATH != '' && vars.IDTECH3_GAME_BASE_PATH || secrets.IDTECH3_GAME_BASE_PATH }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify GAME_BASE
+        run: |
+          set -euo pipefail
+          test -d "$GAME_BASE" || { echo "GAME_BASE is not a directory: $GAME_BASE" >&2; exit 1; }
+          echo "Using GAME_BASE=$GAME_BASE"
+
+      - name: Build Vulkan (Release)
+        env:
+          CFLAGS: "-DSKIP_IDPAK_CHECK=1"
+          CXXFLAGS: "-DSKIP_IDPAK_CHECK=1"
+        run: |
+          set -euo pipefail
+          ./scripts/compile_engine.sh vulkan
+
+      - name: Renderer regression check (repo + optional BSP)
+        run: |
+          set -euo pipefail
+          GAME_BASE="$GAME_BASE" ./scripts/renderer_regression_check.sh
+
+      - name: Renderer regression map load (dedicated)
+        run: |
+          set -euo pipefail
+          GAME_BASE="$GAME_BASE" ./scripts/renderer_regression_maps.sh

.gitignore

@@ -32,4 +32,15 @@ build_log.txt
 src/renderers/vulkan/shaders/spirv/generated/backups/
 android/.gradle/
 android/app/.cxx/
-android/local.properties
+android/local.properties
+.ci-android-deps/
+
+# Local copies of examples/*/*.env.example (optional secrets / machine paths)
+/local_validation.env
+/game_base.env
+/examples/demo_skeleton/local.env
+
+# demo_skeleton/base/ is otherwise matched by `base/` above — keep only the placeholder tracked
+!/examples/demo_skeleton/base/
+/examples/demo_skeleton/base/*
+!/examples/demo_skeleton/base/README.txt

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `examples/demo_game`: `idtech3_demo.pk3` embeds a minimal native UI module (`vm/ui<arch>.so` or `.dll`) so the demo skeleton can open a window without retail `ui.qvm` (`examples/demo_game/native/ui_skeleton_stub.c`, CMake target `demo_ui_skeleton`).
+- `examples/demo_skeleton/`: user-friendly demo playfield (`./scripts/run_demo.sh`, auto-detect layout, `baseq3` hint, help text); `scripts/run_demo.sh` entry point; `base/` + `idtech3_demo/` README stubs.
+- CTest `test_demo_game_pk3`: verifies `examples/demo_game` zip layout (configs + optional **`cc`**-built **`vm/ui*.so`**) matches CMake staging.
+- Vulkan: `vk_procs.c` holds `qvk*` function pointer definitions (split from `vk.c`); `vk_instance.c` no longer duplicates `extern` declarations.
+- Vulkan: `vk_shader_modules.c` holds `vk_create_shader_modules` and includes `shader_data.c` / `shader_binding.c` (split from `vk.c`).
+- Vulkan: `vk_pipelines_persistent.c` holds `vk_alloc_persistent_pipelines` (split from `vk.c`).
 - CHANGELOG.md for release tracking
 - Semantic versioning in CMake (project VERSION 1.0.0)
 - ENABLE_FORTIFY_SOURCE option for buffer overflow protection (default ON)
@@ -23,6 +29,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - FORTIFY_SOURCE now enabled by default in Release builds (compile_engine.sh)
 - Vulkan cinematic path: r_fboCinematic cvar, vk_in_render_pass reset, luminance skip workaround
+- Vulkan PBR: direct specular uses **anisotropic GGX** when an anisotropy map is bound (`r_pbr_anisotropicSpecular` default 1); replaces the old roughness-only blend. Re-run `scripts/compile_shaders.sh` after changing `gen_frag.tmpl`.
+- Vulkan PBR: **anisotropic visibility** for direct light; optional **IBL roughness stretch** from the anisotropy map (`r_pbr_iblAnisoStretch`); **clearcoat** base attenuation and **Charlie sheen** with optional fourth `sheenScale` roughness token.
+
+### Removed
+- Legacy `r_vfog*` engine cvars and `vk_vfog.c`/`vk_vfog.h`: volumetric fog is configured only via `r_volumetricFog*` (and map/`r_fog*` as documented). Editor `worldspawn` keys `vfog_*` remain separate map data, not console cvars.
 
 ### Security
 - _FORTIFY_SOURCE=2 enabled for GCC/Clang Release builds when ENABLE_FORTIFY_SOURCE=ON

CLAUDE.md

@@ -134,6 +134,7 @@ The renderer abstraction layer is **architecturally sensitive**:
 - **C**: C23 with modern features (designated initializers, constexpr, etc.)
 - **C++**: C++23 for complex systems (RAII, templates, smart pointers)
 - **Compatibility**: Code must compile with GCC 15+ and Clang 18+
+- **Booleans**: On native builds, **`qboolean` is `bool`** (from `<stdbool.h>`) and **`qtrue` / `qfalse`** expand to **`true` / `false`** (`q_shared.h`). Prefer **`qboolean`** for engine/game APIs and **`qtrue` / `qfalse`** in literals so code stays compatible with the legacy **`Q3_VM`** path, which still uses an enum-backed `qboolean`. Do not reintroduce **`typedef enum { qfalse, qtrue } qboolean`** for native targets.
 
 ### Naming Conventions
 
@@ -275,6 +276,10 @@ sudo apt-get install cmake clang-18 gcc-15 ninja-build
 
 # Clean build
 ./scripts/compile_engine.sh clean vulkan
+
+# Optional link-time optimization (Release/RelWithDebInfo; GCC/Clang; longer links)
+./scripts/compile_engine.sh vulkan lto
+# Equivalent: cmake -DENABLE_LTO=ON ... (see CMakeLists.txt; MSVC not wired for this option)
 ```
 
 #### Windows (Cross-Platform Validation)