# 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.