| # GitWorld Phase 2 — Unreal walkable worlds | |
| ## Objective | |
| Move the completed browser-local GitWorld concept into a real-time Unreal project with a walkable third-person space, repository-owned sandbox state, visible build progress, and a high-resolution rendering profile. | |
| ## Player experience | |
| The player spawns in a GitWorld map containing repository districts. Each repository is an `AGitWorldRepoWorld` actor with its own deterministic snapshot, geometry, events, and terminal transcript. Walking into an `AGitWorldRepoPortal` activates that repository in the world subsystem. Build ticks change district geometry and the sign above the world, so construction is visible in-world rather than represented only by UI. | |
| ## Architecture | |
| - `GitWorldSimulation.*` — deterministic, headless repository state transitions and terminal output. | |
| - `AGitWorldRepoWorld` — one sandboxed repository world; owns its snapshot, generated blocks, sign, and compute result. | |
| - `AGitWorldRepoPortal` — overlap trigger that switches the active repository when the player walks in. | |
| - `UGitWorldWorldSubsystem` — registry and active-world selection; no repository actor mutates another repository’s state. | |
| - `FGitWorldCudaBridge` — optional dynamic CUDA DLL boundary with a deterministic CPU fallback. | |
| - `AGitWorldGameMode` — temporary demo catalog for `pax-coder`, `agent-minefield`, and `cuda-lab`; replace with a data asset in Phase 3. | |
| ## Rendering and 8K target | |
| `Config/DefaultEngine.ini` enables a DX12-oriented Nanite/Lumen profile, virtual shadow maps, hardware ray tracing, and a 7680×4320 game-user resolution target. Use `r.SetRes 7680x4320f` for a desktop viewport or Movie Render Queue for a high-resolution capture. A real 8K interactive session is a performance target, not a promise that every GPU can sustain 60 FPS at native resolution. | |
| The local machine currently exposes an RTX 3080 with 10,240 MiB VRAM. Unreal Editor and `nvcc` were not available on PATH during scaffold validation, so Unreal compilation, CUDA device execution, and native 8K frame-time measurement remain pending until those tools are installed. | |
| ## Run when Unreal is installed | |
| 1. Right-click `GitWorldUnreal.uproject` and generate Visual Studio project files. | |
| 2. Build `GitWorldUnrealEditor` in Development Editor / Win64. | |
| 3. Open the project, press Play, and walk with the default pawn. | |
| 4. Confirm the repository sign, build tick, portal activation, and terminal transcript. | |
| 5. If desired, build `Compute/GitWorldCuda.dll` and place it in `Binaries/Win64/` to enable the CUDA compute pass. | |
| ## Local verification | |
| From the parent `gitworld` folder: | |
| ```text | |
| node tools/verify-phase2.mjs | |
| ``` | |
| This verifies the project manifest, Unreal source contract, isolated repository identifiers, CUDA boundary, and 8K settings without requiring Unreal or CUDA to be installed. | |