From 11a13042b615a8c6e1fe4186d30535510303bb4f Mon Sep 17 00:00:00 2001 From: nathan Date: Tue, 19 May 2026 10:23:22 -0700 Subject: [PATCH] Add GPU startup visual test gate --- AGRARIAN_DEVELOPMENT_ROADMAP.md | 2 +- .../Ops/PackagedClientGpuStartupVisualTest.md | 71 +++++++++++++++++++ Docs/Ops/WindowsBuilderGpuRemoteAccess.md | 6 +- Scripts/RunWindowsGpuStartupVisualCheck.bat | 55 ++++++++++++++ ...packaged_client_gpu_startup_visual_test.py | 59 +++++++++++++++ 5 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 Docs/Ops/PackagedClientGpuStartupVisualTest.md create mode 100644 Scripts/RunWindowsGpuStartupVisualCheck.bat create mode 100644 Scripts/verify_packaged_client_gpu_startup_visual_test.py diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 72da273..ca2c0d2 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -819,7 +819,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe - [x] Reclassify the current investor demo as systems-first, not investor visual MVP, until the visual/menu quality gate below is complete. Added an explicit investor-demo status document, legal notice wording, startup notice wording, packaged README classification, and verification so the current demo is presented as a systems-first investor prototype until 0.1.O visual/menu gates are actually complete. - [x] Replace the native painted MVP frontend with a proper UMG menu flow using real button widgets, hover/pressed states, keyboard/controller focus, mouse click targets, and predictable back/escape behavior. Converted the MVP frontend to a WidgetTree-built UMG flow with UButton/UTextBlock controls, hover/pressed button styling, focusable primary actions, mouse-click character selection, back handling, and save/quit actions while preserving the existing player-controller API. - [x] Make startup credits, character selection, server/join, loading, pause, save, and quit feel like separate intentional segments, with no impression that gameplay has started underneath the UI. Switched startup/menu control to UI-only input, added explicit segment labels for character selection, server join, loading, pause, and saving, and made Save & Quit transition through a dedicated saving screen before issuing save/quit. -- [ ] Add a visually verified packaged-client startup test using Sunshine/Moonlight or another real GPU desktop capture path, because QEMU guest-agent screenshots cannot validate the interactive rendered desktop. +- [x] Add a visually verified packaged-client startup test using Sunshine/Moonlight or another real GPU desktop capture path, because QEMU guest-agent screenshots cannot validate the interactive rendered desktop. Added a packaged-client GPU startup visual test runbook, a Windows helper that checks the packaged demo and Sunshine service before capture, and verifier coverage requiring Moonlight/Sunshine evidence instead of QEMU guest-agent screenshots. - [ ] Add first realistic playable character proxies for the selected young adult male and female archetypes, replacing the default mannequin/dummy presentation for investor builds. - [ ] Replace box/sphere/cylinder survival objects with readable MVP meshes for campfires, primitive shelter pieces, resource pickups, water sources, wildlife, and gathered items. - [ ] Replace the placeholder Ground Zero environment presentation with investor-facing biome dressing: believable terrain material, grass, brush, shrubs, bushes, trees, rocks, water visuals, and local coastal-scrub color variation. diff --git a/Docs/Ops/PackagedClientGpuStartupVisualTest.md b/Docs/Ops/PackagedClientGpuStartupVisualTest.md new file mode 100644 index 0000000..6dec4c7 --- /dev/null +++ b/Docs/Ops/PackagedClientGpuStartupVisualTest.md @@ -0,0 +1,71 @@ +# Packaged Client GPU Startup Visual Test + +This test validates the packaged Windows investor demo through the real GPU +desktop path. Do not use QEMU guest-agent screenshots for this gate; they are +useful for administration but cannot prove that the interactive rendered +desktop is visible, focused, or readable. + +## Purpose + +Run this before calling an investor package visually ready. The test is meant +to catch the problems that headless automation misses: black screens, unfocused +menus, mouse capture problems, startup credits appearing under gameplay, missing +foliage or terrain visuals, and pause/save/quit menu confusion. + +## Required Path + +- Windows build VM with the packaged demo in `Builds\WindowsDevelopment`. +- Sunshine running on the Windows build VM. +- Moonlight connected to the Windows build VM desktop from a real viewing + client. +- The packaged demo launched from the investor launcher, preferably + `Start Agrarian Demo - DX12.cmd`; use the compatibility launcher only when + validating fallback rendering. + +## Capture Set + +Save screenshots or a short clip under: + +`Saved\VisualQA\GpuStartup\\` + +Required evidence: + +- `01-startup-credits` - cinematic credits are full-screen and no gameplay + interaction appears active underneath. +- `02-character-selection` - the UMG character selection segment is readable, + clickable, and focused. +- `03-server-join` - the server/join segment is readable and separate from the + character segment. +- `04-loading` - the loading segment is readable and does not show accidental + gameplay input. +- `05-first-spawn` - first playable view after closing the frontend. +- `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. + +Create `visual-startup-check.txt` in the capture folder with: + +- package path; +- launcher used; +- capture method, normally Sunshine plus Moonlight; +- tester name; +- pass/fail result; +- notes on visible defects. + +## Windows Helper + +Run this from the Windows project checkout before the capture session: + +```bat +Scripts\RunWindowsGpuStartupVisualCheck.bat --check-tools +``` + +To print the full capture checklist: + +```bat +Scripts\RunWindowsGpuStartupVisualCheck.bat +``` + +This helper intentionally does not accept QEMU guest-agent screenshot evidence. +It verifies the packaged demo path and Sunshine service, then tells the tester +what real-GPU startup captures to collect. diff --git a/Docs/Ops/WindowsBuilderGpuRemoteAccess.md b/Docs/Ops/WindowsBuilderGpuRemoteAccess.md index 411f633..7cc26ab 100644 --- a/Docs/Ops/WindowsBuilderGpuRemoteAccess.md +++ b/Docs/Ops/WindowsBuilderGpuRemoteAccess.md @@ -40,6 +40,11 @@ Keep these LAN-only. Do not expose Sunshine directly to the public internet. Codex should continue using the headless build/control path for normal code, cook, package, and commandlet work. Use Sunshine only when a visual inspection is actually needed. +For packaged investor-demo startup validation, use the dedicated checklist in +`Docs/Ops/PackagedClientGpuStartupVisualTest.md` and run +`Scripts\RunWindowsGpuStartupVisualCheck.bat --check-tools` on the Windows +builder before capturing through Moonlight. + ## Verification The setup was validated by: @@ -59,4 +64,3 @@ The GTX 1660 SUPER does not support AV1 NVENC. Sunshine may log an AV1 encoder f - If Moonlight shows a black screen after using RDP, disconnect RDP, restart `SunshineService`, and reconnect through Moonlight. - If controller input is required later, install and validate the ViGEmBus gamepad driver. It is not required for visual inspection. - If Unreal rendering differs under RDP, use Moonlight before changing graphics settings. - diff --git a/Scripts/RunWindowsGpuStartupVisualCheck.bat b/Scripts/RunWindowsGpuStartupVisualCheck.bat new file mode 100644 index 0000000..ddcbddf --- /dev/null +++ b/Scripts/RunWindowsGpuStartupVisualCheck.bat @@ -0,0 +1,55 @@ +@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\GpuStartup" + +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 packaged-client real-GPU startup visual test +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. +echo Required capture labels: +echo 01-startup-credits +echo 02-character-selection +echo 03-server-join +echo 04-loading +echo 05-first-spawn +echo 06-pause-menu +echo 07-save-quit +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. +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 GPU visual test. + exit /b 3 +) + +exit /b 0 diff --git a/Scripts/verify_packaged_client_gpu_startup_visual_test.py b/Scripts/verify_packaged_client_gpu_startup_visual_test.py new file mode 100644 index 0000000..2695d9f --- /dev/null +++ b/Scripts/verify_packaged_client_gpu_startup_visual_test.py @@ -0,0 +1,59 @@ +#!/usr/bin/env python3 +"""Verify the real-GPU packaged startup visual test gate is documented.""" + +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +DOC = ROOT / "Docs" / "Ops" / "PackagedClientGpuStartupVisualTest.md" +BAT = ROOT / "Scripts" / "RunWindowsGpuStartupVisualCheck.bat" +ROADMAP = ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md" + + +def require(condition: bool, message: str) -> None: + if not condition: + raise SystemExit(f"FAILED: {message}") + + +def main() -> None: + doc = DOC.read_text(encoding="utf-8") + bat = BAT.read_text(encoding="utf-8") + roadmap = ROADMAP.read_text(encoding="utf-8") + + for token in ( + "Do not use QEMU guest-agent screenshots", + "Sunshine", + "Moonlight", + "Builds\\WindowsDevelopment", + "01-startup-credits", + "02-character-selection", + "03-server-join", + "04-loading", + "05-first-spawn", + "06-pause-menu", + "07-save-quit", + "visual-startup-check.txt", + ): + require(token in doc, f"visual startup test doc missing {token!r}") + + for token in ( + "SunshineService", + "Builds\\WindowsDevelopment", + "AgrarianGame.exe", + "--check-tools", + "Do not use QEMU guest-agent screenshots", + "01-startup-credits", + "07-save-quit", + ): + require(token in bat, f"Windows visual startup helper missing {token!r}") + + require( + "- [x] Add a visually verified packaged-client startup test using Sunshine/Moonlight or another real GPU desktop capture path" in roadmap, + "0.1.O real-GPU startup visual test roadmap item is not checked off", + ) + + print("OK: packaged-client real-GPU startup visual test gate is documented and scripted.") + + +if __name__ == "__main__": + main()