From 1ac7166942d5ae40ea7fda35120e81b1f5f0e188 Mon Sep 17 00:00:00 2001 From: nathan Date: Tue, 19 May 2026 11:20:45 -0700 Subject: [PATCH] Add investor visual QA evidence gate --- AGRARIAN_DEVELOPMENT_ROADMAP.md | 2 +- .../Ops/PackagedClientGpuStartupVisualTest.md | 10 +++ Docs/Ops/PackagedDemoVisualQAEvidence.md | 44 +++++++++++ Scripts/RunWindowsGpuStartupVisualCheck.bat | 5 ++ Scripts/RunWindowsInvestorVisualQACheck.bat | 60 +++++++++++++++ ...verify_packaged_demo_visual_qa_evidence.py | 75 +++++++++++++++++++ 6 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 Docs/Ops/PackagedDemoVisualQAEvidence.md create mode 100644 Scripts/RunWindowsInvestorVisualQACheck.bat create mode 100644 Scripts/verify_packaged_demo_visual_qa_evidence.py diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index b2ee045..298222d 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -828,7 +828,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe - [x] Preserve realism as the target: use assets, materials, lighting, and environmental dressing that can survive toward MVP production rather than cosmetic throwaways where practical. Added MVP realism target rules to the shared art/UX/code/asset standards, tied current 0.1.O visual passes to production-directed proxy expectations, and added a verifier that requires Ground Zero materials, water, density/sightline, character, and survival-object docs to point toward production realism instead of cosmetic throwaways. - [x] Define default, recommended, and cinematic investor rendering presets, with ray tracing available only as an optional high-end/cinematic mode and never required for baseline visual credibility. Added `Config/AgrarianRenderingPresets.ini`, `Docs/Rendering/InvestorRenderingPresets.md`, and a verifier that requires Default and Recommended to remain non-ray-traced while Cinematic is the only optional high-end ray-tracing profile. - [x] Verify the non-ray-traced compatibility/default path still looks credible on common investor, tester, and remote-session hardware. Added a dedicated non-ray-traced default verifier that checks Default and Recommended disable `r.RayTracing`, `r.Lumen.HardwareRayTracing`, and `r.PathTracing`, keeps Cinematic as the only optional ray-tracing profile, and documents that packaged investor demos should launch on Default unless another profile is explicitly selected. -- [ ] Add packaged-demo visual QA screenshots or short clips for startup credits, character selection, first spawn, terrain, vegetation, water, campfire, shelter, pause menu, and save/quit before each investor build is called ready. +- [x] Add packaged-demo visual QA screenshots or short clips for startup credits, character selection, first spawn, terrain, vegetation, water, campfire, shelter, pause menu, and save/quit before each investor build is called ready. Added a full investor-demo visual QA evidence runbook, Windows helper, startup capture expansion, and verifier requiring Sunshine/Moonlight or equivalent real-GPU captures for startup credits, character selection, first spawn, terrain, vegetation, water, campfire, shelter, pause, and save/quit before a packaged build is called investor-ready. - [ ] Add an investor-demo acceptance gate: no current build should be described as investor visual MVP if menus are confusing, character art is mannequin-only, terrain is flat/tan, foliage is absent or unreadable, or core objects still read as primitive debug shapes. ## 0.1.P MVP Audio And Atmosphere diff --git a/Docs/Ops/PackagedClientGpuStartupVisualTest.md b/Docs/Ops/PackagedClientGpuStartupVisualTest.md index 6dec4c7..89594f5 100644 --- a/Docs/Ops/PackagedClientGpuStartupVisualTest.md +++ b/Docs/Ops/PackagedClientGpuStartupVisualTest.md @@ -42,6 +42,16 @@ Required evidence: - `06-pause-menu` - Escape opens the pause menu, mouse cursor is visible, and gameplay is blocked. - `07-save-quit` - Save & Quit shows the saving segment before closing. +- `08-terrain` - Ground Zero terrain reads as shaped coastal terrain, not a + flat tan placeholder. +- `09-vegetation` - grasses, shrubs, bushes, and trees are visible without + hiding interaction targets. +- `10-water` - the freshwater source reads as collectable water with bank/edge + dressing. +- `11-campfire` - the campfire reads as a campfire object, not a primitive + debug shape. +- `12-shelter` - the primitive shelter reads as a shelter object, not primitive + debug blocks. Create `visual-startup-check.txt` in the capture folder with: diff --git a/Docs/Ops/PackagedDemoVisualQAEvidence.md b/Docs/Ops/PackagedDemoVisualQAEvidence.md new file mode 100644 index 0000000..a98f4de --- /dev/null +++ b/Docs/Ops/PackagedDemoVisualQAEvidence.md @@ -0,0 +1,44 @@ +# Packaged Demo Visual QA Evidence + +Each Windows investor build needs a real-GPU visual evidence set before it is +called ready. Headless automation and QEMU guest-agent screenshots can confirm +process state, but they cannot prove that the rendered desktop, menus, terrain, +foliage, water, and survival objects are visually credible. + +Use Sunshine plus Moonlight, or an equivalent real-GPU desktop capture path, and +save evidence under: + +`Saved\VisualQA\InvestorDemo\\` + +Required screenshots or short clips: + +- `01-startup-credits` +- `02-character-selection` +- `03-first-spawn` +- `04-terrain` +- `05-vegetation` +- `06-water` +- `07-campfire` +- `08-shelter` +- `09-pause-menu` +- `10-save-quit` + +Evidence may be screenshots, a single labeled clip, or a short clip plus stills. +Do not commit raw captures to Git; keep them in `Saved\VisualQA` or publish +links/paths in release notes. + +Create `visual-qa-summary.txt` beside the captures with: + +- package path; +- build/version label; +- rendering preset used, normally Default; +- capture method, normally Sunshine plus Moonlight; +- tester name; +- pass/fail result; +- visible defects; +- whether the build is acceptable for investor viewing. + +The package is not investor visual MVP ready if any required segment is missing +or if the first-spawn view still reads as flat terrain, absent foliage, +placeholder water, debug-shape campfire/shelter objects, confusing menus, or +broken save/quit flow. diff --git a/Scripts/RunWindowsGpuStartupVisualCheck.bat b/Scripts/RunWindowsGpuStartupVisualCheck.bat index ddcbddf..0cab4d9 100644 --- a/Scripts/RunWindowsGpuStartupVisualCheck.bat +++ b/Scripts/RunWindowsGpuStartupVisualCheck.bat @@ -29,6 +29,11 @@ echo 04-loading echo 05-first-spawn echo 06-pause-menu echo 07-save-quit +echo 08-terrain +echo 09-vegetation +echo 10-water +echo 11-campfire +echo 12-shelter echo. echo Create visual-startup-check.txt in the capture folder with package path, echo launcher used, capture method, tester, pass/fail result, and notes. diff --git a/Scripts/RunWindowsInvestorVisualQACheck.bat b/Scripts/RunWindowsInvestorVisualQACheck.bat new file mode 100644 index 0000000..1d987c4 --- /dev/null +++ b/Scripts/RunWindowsInvestorVisualQACheck.bat @@ -0,0 +1,60 @@ +@echo off +setlocal EnableExtensions + +set "PROJECT_DIR=%~dp0.." +set "PACKAGE_DIR=%PROJECT_DIR%\Builds\WindowsDevelopment" +set "DEMO_EXE=%PACKAGE_DIR%\AgrarianGame.exe" +set "CAPTURE_ROOT=%PROJECT_DIR%\Saved\VisualQA\InvestorDemo" + +if /I "%~1"=="--check-tools" goto CHECK_TOOLS + +call :CHECK_COMMON || exit /b %ERRORLEVEL% + +if not exist "%CAPTURE_ROOT%" mkdir "%CAPTURE_ROOT%" >nul 2>nul + +echo. +echo Agrarian investor-demo full visual QA evidence checklist +echo -------------------------------------------------------- +echo Package: "%PACKAGE_DIR%" +echo Capture root: "%CAPTURE_ROOT%" +echo. +echo Use Sunshine plus Moonlight or an equivalent real GPU desktop capture path. +echo Do not use QEMU guest-agent screenshots for this visual gate. +echo Use the Default rendering preset unless intentionally validating another profile. +echo. +echo Required capture labels: +echo 01-startup-credits +echo 02-character-selection +echo 03-first-spawn +echo 04-terrain +echo 05-vegetation +echo 06-water +echo 07-campfire +echo 08-shelter +echo 09-pause-menu +echo 10-save-quit +echo. +echo Create visual-qa-summary.txt beside the captures with package path, +echo version label, rendering preset, capture method, tester, pass/fail result, +echo visible defects, and investor-viewing decision. +echo. +exit /b 0 + +:CHECK_TOOLS +call :CHECK_COMMON || exit /b %ERRORLEVEL% +echo READY: packaged demo exists and SunshineService is running. +exit /b 0 + +:CHECK_COMMON +if not exist "%DEMO_EXE%" ( + echo ERROR: Packaged demo executable not found: "%DEMO_EXE%" + exit /b 2 +) + +sc query SunshineService | find /I "RUNNING" >nul 2>nul +if errorlevel 1 ( + echo ERROR: SunshineService is not running. Start Sunshine before the investor visual QA capture. + exit /b 3 +) + +exit /b 0 diff --git a/Scripts/verify_packaged_demo_visual_qa_evidence.py b/Scripts/verify_packaged_demo_visual_qa_evidence.py new file mode 100644 index 0000000..ebdd039 --- /dev/null +++ b/Scripts/verify_packaged_demo_visual_qa_evidence.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +"""Verify the packaged investor-demo visual QA evidence gate is documented.""" + +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +DOC = ROOT / "Docs" / "Ops" / "PackagedDemoVisualQAEvidence.md" +STARTUP_DOC = ROOT / "Docs" / "Ops" / "PackagedClientGpuStartupVisualTest.md" +BAT = ROOT / "Scripts" / "RunWindowsInvestorVisualQACheck.bat" +STARTUP_BAT = ROOT / "Scripts" / "RunWindowsGpuStartupVisualCheck.bat" +ROADMAP = ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md" + +REQUIRED_LABELS = [ + "01-startup-credits", + "02-character-selection", + "03-first-spawn", + "04-terrain", + "05-vegetation", + "06-water", + "07-campfire", + "08-shelter", + "09-pause-menu", + "10-save-quit", +] + + +def require(condition, message): + if not condition: + raise SystemExit(f"FAILED: {message}") + + +def main(): + doc = DOC.read_text(encoding="utf-8") + startup_doc = STARTUP_DOC.read_text(encoding="utf-8") + bat = BAT.read_text(encoding="utf-8") + startup_bat = STARTUP_BAT.read_text(encoding="utf-8") + roadmap = ROADMAP.read_text(encoding="utf-8") + + for token in [ + "Sunshine plus Moonlight", + "Saved\\VisualQA\\InvestorDemo", + "visual-qa-summary.txt", + "Do not commit raw captures to Git", + "Default", + "investor visual MVP ready", + ]: + require(token in doc, f"visual QA evidence doc missing {token!r}") + + for label in REQUIRED_LABELS: + require(label in doc, f"visual QA evidence doc missing {label!r}") + require(label in bat, f"Windows visual QA helper missing {label!r}") + + for token in [ + "08-terrain", + "09-vegetation", + "10-water", + "11-campfire", + "12-shelter", + ]: + require(token in startup_doc, f"startup GPU visual doc missing expanded label {token!r}") + require(token in startup_bat, f"startup GPU visual helper missing expanded label {token!r}") + + require("SunshineService" in bat, "Windows visual QA helper must check SunshineService") + require("--check-tools" in bat, "Windows visual QA helper must support --check-tools") + require( + "[x] Add packaged-demo visual QA screenshots or short clips" in roadmap, + "0.1.O packaged-demo visual QA evidence roadmap item is not checked off", + ) + + print("OK: packaged investor-demo visual QA evidence gate is documented and scripted.") + + +if __name__ == "__main__": + main()