From 0e33b3f25765b69a9bf0d809395bed78503b4135 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 14 Jun 2026 16:03:52 +0000 Subject: [PATCH] docs: sync open-world residency, sector graph, and agent runbooks - AGENTS.md: add world residency, sector graph, Wwise mixer, animgraph bullets - ARCHITECTURE.md: document src/world/ modules and streaming flow - README.md: link world streaming, residency, graph compute, animgraph - WORLD_RESIDENCY.md: quick-start cvar block and MP note - GRAPH_COMPUTE.md: troubleshooting table (vid_restart, block_unloaded) - DISTRICTS.md: residency + graph reachability integration - DEVELOPMENT_SETUP.md: ctest targets for open-world unit tests Co-authored-by: Tim Fox --- AGENTS.md | 4 ++++ README.md | 8 ++++++++ docs/ARCHITECTURE.md | 32 ++++++++++++++++++++++++++++++++ docs/DEVELOPMENT_SETUP.md | 7 +++++++ docs/DISTRICTS.md | 2 ++ docs/GRAPH_COMPUTE.md | 12 ++++++++++++ docs/WORLD_RESIDENCY.md | 22 ++++++++++++++++++++++ 7 files changed, 87 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4468860c4..d815b6e3a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,10 +58,14 @@ Build artifacts go to `build-vk-Release/` and are copied to `release/`. - **FreeUSD (default ON)**: Git submodule **`src/external/FreeUSD`** ([gopexllc/FreeUSD](https://github.com/gopexllc/FreeUSD)); **`USE_FREEUSD=ON`** in CMake and **`./scripts/compile_engine.sh`** (auto `git submodule update --init`; pass **`nofreeusd`** to disable). Targets link **`freeusd::runtime`** + **`freeusd::c`** via **`idtech3_freeusd`**. Renderer **`r_freeusd` 1**; client **`usd_*`** tools. Init: **`./scripts/init_optional_submodules.sh --freeusd`**. See **`docs/FREEUSD.md`**. - **World districts + proxy meshes**: **`r_district` 1** (default) — USD manifest via **`district_load world/playfield.usda`**, FreeUSD snapshot parse, proxy residency (`r_districtProxy`), optional **`cm_districtStream`** sector prefetch. Console: **`district_list`**, **`district_proxy`**, **`district_load_full`**. Demo: **`exec demo_districts.cfg`**. See **`docs/DISTRICTS.md`**. - **Infinite open worlds**: **`r_openWorld` 1** — view-driven sector residency: **`cm_stream`** + **`cm_streamMerge` 1** (overlay sector BSP collision), per-chunk **`nav/sector_X_Y.nav`**, **`sprites/sector_X_Y.ents`** billboard scatter. Console: **`openworld_start`**, **`openworld_sector`**, **`openworld_status`**. Demo: **`exec demo_openworld.cfg`**. See **`docs/OPEN_WORLD.md`**. +- **Consistent sector residency (open world)**: **`r_openWorldResidency` 1** — value-aware cardinality selection under per-layer budgets (`r_openWorldMaxSectors`, `r_openWorldMaxNavSectors`, `r_openWorldMaxSpriteSectors`) with bounded swaps (`r_openWorldResidencyMaxSwaps`). MP: **`sv_openWorldResidency` 1** plans server collision from player unions; clients clamp to **`CS_ENGINE_OPENWORLD_SECTORS`**. Nav/sprites subject to **`cl_openWorldResidencyNavLocal`**. See **`docs/WORLD_RESIDENCY.md`**. **`ctest -R unit_world_residency`** / **`test_openworld_residency`**. +- **Sector graph reachability (open world)**: **`r_graphStreamReach` 1** — k-hop BFS filter on residency candidates (`r_graphStreamHops`, default 8); optional GPU path **`r_graphCompute` 1** + **`vid_restart`**. Console: **`graph_reach_test`**, **`graph_bfs_status`**, **`graph_bfs_bench`**. See **`docs/GRAPH_COMPUTE.md`**. **`ctest -R unit_sector_graph`** / **`test_graph_compute`**. - **Procedural patterns**: **`r_proc` 1** — deterministic Voronoi/grid/hex/radial/stripe/noise sector typing. Console: **`proc_pattern`**, **`proc_map`**, **`proc_sample`**. Scatter fallback: **`sprites/region_.ents`** when **`r_procScatterRegion` 1**. Demo: **`exec demo_proc.cfg`**. See **`docs/PROC_PATTERNS.md`**. - **Sector BSP fixtures**: **`python3 scripts/tools/gen_sector_bsp.py maps/sector_0_0.bsp`** — minimal collision overlay for **`cm_streamMerge`**. **`ctest -R test_cm_stream_merge`**. - **Nav sector bake**: **`nav_bake_sector 0 0`** / **`nav_bake_view`** — Recast tile from sector BSP → **`nav/sector_X_Y.nav`**. Server collision residency: **`sv_openWorld 1`**. **`ctest -R test_nav_bake`**. - **MP sector sync**: **`sv_openWorldSync` 1** → **`CS_ENGINE_OPENWORLD_SECTORS`**; client **`cl_openWorldSync` 1**. Visual overlay: **`r_bspStream` 1**. **`ctest -R test_openworld_sync`**. +- **Wwise-style runtime mixer (audio)**: **`s_mixer_enable` 1** (default) — output buses (`s_bus_*`), RTPCs, state groups (`snd_setstate`), auto-duck, sound events (`snd_playevent`), replay capture. See **`docs/AUDIO_WWISE_PARITY.md`**. +- **Animgraph (native game module)**: **`g_animgraph` 1** — JSON state machine for glTF/IQM clip selection (`animgraph/*.json`); Lua **`Engine.AnimGraph.*`**. See **`docs/ANIMGRAPH.md`**. ### Linting / Static Analysis diff --git a/README.md b/README.md index baaba414a..f0f54e8bd 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Modern id Tech 3: **Vulkan renderer with PBR**, validation and smoke-tested buil **Audio**: * OpenAL backend with HRTF for 3D positional audio * Real-time reverb and occlusion effects via OpenAL EFX (heuristic environmental acoustics) +* Wwise-inspired runtime mixer (buses, RTPCs, state groups, sound events) — [docs/AUDIO_WWISE_PARITY.md](docs/AUDIO_WWISE_PARITY.md) * Audio codec support: mp3, ogg, wav, flac, webm, opus **Video**: @@ -61,7 +62,14 @@ Modern id Tech 3: **Vulkan renderer with PBR**, validation and smoke-tested buil * Optional TLS-secured remote console (off by default) * Console/logging for connection diagnostics and real-time network statistics +**World streaming** (engine-original open worlds): +* View-driven sector residency — collision merge, per-chunk nav tiles, billboard scatter — [docs/OPEN_WORLD.md](docs/OPEN_WORLD.md) +* Optional consistent cardinality planner (`r_openWorldResidency`) — [docs/WORLD_RESIDENCY.md](docs/WORLD_RESIDENCY.md) +* Sector graph k-hop reachability filter + optional Vulkan compute BFS — [docs/GRAPH_COMPUTE.md](docs/GRAPH_COMPUTE.md) +* USD world districts + proxy meshes — [docs/DISTRICTS.md](docs/DISTRICTS.md) + **Systems** (game and engine extensions): +* Animgraph JSON state machine for glTF/IQM clip selection — [docs/ANIMGRAPH.md](docs/ANIMGRAPH.md) * AIML 2.1-oriented chatbot scripting (see `g_aiml.c` / Lua `Engine.AIML`) * GOAP (AI planning) * Flocking and boids (crowd AI) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 65943f93b..2e64b4d59 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -86,7 +86,14 @@ src/ ├── qcommon/ Shared engine (VM, filesystem, network) │ ├── vm.c / vm_local.h VM create, native load, QVM path │ ├── vm_native_module.c/h Native `.so`/`.dll` filename candidates +│ ├── cm_stream.c Sector pk3 prefetch + collision merge overlay │ └── files.c FS_LoadLibrary search (modules/vm/gamedir) +├── world/ Open-world streaming + districts +│ ├── world_open.c/h Sector residency (collision, nav, scatter) +│ ├── world_residency.c/h Value-aware cardinality planner (optional) +│ ├── sector_graph.c/h k-hop reachability pre-filter (CPU + optional GPU BFS) +│ ├── world_district.c/h USD district manifest + proxy residency +│ └── world_proc.c/h Procedural sector typing (Voronoi/grid/hex/…) ├── server/ Dedicated server ├── botlib/ Bot AI (Q3 AAS pathfinding) └── external/ Vendored libraries @@ -146,6 +153,31 @@ For goals and longer notes, see [RENDERER_2026_ARCHITECTURE_PASS.md](RENDERER_20 **Bootstrap game data** (minimal `base/` layout that still satisfies the filesystem): [MINIMAL_GAME_SHELL.md](MINIMAL_GAME_SHELL.md). +## Open-world streaming + +View-driven **sector residency** lives in `src/world/` and is ticked from `CL_OpenWorld_Frame` / `SV_OpenWorld_Frame`: + +``` +View / player origin(s) + └── WorldOpen_UpdateView + ├── r_openWorldResidency 0 → radius disk (r_openWorldRadius) + └── r_openWorldResidency 1 → WorldResidency (budget + bounded delta) + ├── optional SectorGraph k-hop filter (r_graphStreamReach) + ├── cm_stream merge → collision overlay + ├── nav/sector_X_Y.nav → Detour addTile + └── sprites/sector_X_Y.ents → billboard scatter +``` + +| Module | Role | +|--------|------| +| `world_open.c` | Layer load/unload, `openworld_*` console, MP configstring sync | +| `world_residency.c` | Consistent submodular sector selection (collision/nav/sprite budgets) | +| `sector_graph.c` | Grid CSR + multi-source BFS; optional `vk_graph_bfs.c` compute path | +| `world_district.c` | USD districts; integrates with WorldOpen when `r_openWorld 1` | +| `world_proc.c` | Deterministic region/palette typing for scatter and matroid mode | + +Docs: [OPEN_WORLD.md](OPEN_WORLD.md), [WORLD_RESIDENCY.md](WORLD_RESIDENCY.md), [GRAPH_COMPUTE.md](GRAPH_COMPUTE.md), [DISTRICTS.md](DISTRICTS.md), [PROC_PATTERNS.md](PROC_PATTERNS.md). + ## Native game modules (VM) When `fs_restrict` is **0** (default), `VM_Create` always tries a **native** shared library before falling back to a `.qvm` (`src/qcommon/vm.c`). Native load is disabled when `fs_restrict` is set (demo-style restriction). diff --git a/docs/DEVELOPMENT_SETUP.md b/docs/DEVELOPMENT_SETUP.md index 334ae7c6c..7876f66ea 100644 --- a/docs/DEVELOPMENT_SETUP.md +++ b/docs/DEVELOPMENT_SETUP.md @@ -294,6 +294,13 @@ cd build-vk-Release && ctest -C Release --output-on-failure ctest --preset test-vulkan-release ``` +Open-world / residency / sector-graph unit and script tests (no GPU or game data required for unit targets): + +```bash +cd build-vk-Release +ctest -R 'unit_world_residency|unit_sector_graph|test_openworld|test_graph_compute' -V +``` + ## IDE Setup ### VS Code / Cursor diff --git a/docs/DISTRICTS.md b/docs/DISTRICTS.md index 88670f43c..96dde6424 100644 --- a/docs/DISTRICTS.md +++ b/docs/DISTRICTS.md @@ -88,6 +88,8 @@ Shipped in `idtech3_demo.pk3` when built with `demo`: `exec demo_districts.cfg` When **`r_openWorld 1`**, `district_load_full` calls **`WorldOpen_LoadSector`** for each cell in the district grid (collision + nav + scatter per cvars). When **`r_openWorld 0`**, full district load uses legacy **`CM_Stream_LoadSector`** (collision prefetch only). See [OPEN_WORLD.md](OPEN_WORLD.md#limitations). +With **`r_openWorldResidency 1`**, `WorldDistrict_StreamSectors` sets a district candidate filter and plans residency at the district centroid instead of brute-force loading every cell in the grid. Optional **`r_graphStreamReach 1`** further constrains candidates to k-hop reachable sectors. See [WORLD_RESIDENCY.md](WORLD_RESIDENCY.md) and [GRAPH_COMPUTE.md](GRAPH_COMPUTE.md). + ## Related docs - [OPEN_WORLD.md](OPEN_WORLD.md) — view-driven sector streaming (BSP prefetch, per-chunk nav, billboard scatter) diff --git a/docs/GRAPH_COMPUTE.md b/docs/GRAPH_COMPUTE.md index 591cddb96..953046244 100644 --- a/docs/GRAPH_COMPUTE.md +++ b/docs/GRAPH_COMPUTE.md @@ -54,6 +54,18 @@ Player origin(s) → SectorGraph_UpdateReachability (CPU BFS) → WorldOpen load/unload ``` +## Troubleshooting + +| Symptom | Cause / fix | +|---------|-------------| +| `[GraphBfs] pipeline not ready` | Set **`r_graphCompute 1`**, then **`vid_restart`** so `vk_graph_bfs.c` registers the GPU reach fn | +| Residency ignores graph filter | **`r_graphStreamReach`** must be **1**; filter applies only when `WorldResidency` is active (`r_openWorldResidency 1`) | +| Cells unexpectedly unreachable | Window is centered on view cell with radius from **`r_openWorldUnloadRadius`**; cells outside the 64×64 window fail `SectorGraph_IsReachable` | +| Edges through unloaded sectors | Enable **`r_graphBlockUnloaded 1`** to cut adjacency into sectors not resident in `WorldOpen` | +| CPU/GPU mismatch warnings | **`r_graphStreamVerify 1`** compares bitsets; disable verify in shipping, fix shader or CSR upload if mismatches persist | + +**`r_graphCompute 1`** alone does not change which sectors load — it only runs the GPU BFS path (and enables verify-friendly cache bypass). Pair with **`r_graphStreamReach 1`** for streaming behavior. + ## Phase 1 follow-ons (not implemented) - Nav influence heatmaps from sector reachability diff --git a/docs/WORLD_RESIDENCY.md b/docs/WORLD_RESIDENCY.md index ba8f0d618..df4093ebf 100644 --- a/docs/WORLD_RESIDENCY.md +++ b/docs/WORLD_RESIDENCY.md @@ -40,6 +40,28 @@ Inspired by the consistent submodular optimization framework (Dütting et al., 2 Startup log when enabled: `[world_residency] enabled epsilon=… k_col=… max_swaps=… matroid=…` +## Quick start + +After hub map load and `openworld_start` (see [OPEN_WORLD.md](OPEN_WORLD.md)): + +```text +set r_openWorldResidency 1 +set r_openWorldLoadRadius 12288 +set r_openWorldUnloadRadius 14336 +set r_openWorldMaxSectors 64 +set r_openWorldMaxNavSectors 32 +set r_openWorldMaxSpriteSectors 64 +set r_openWorldResidencyMaxSwaps 4 + +// Optional: k-hop reachability pre-filter +set r_graphStreamReach 1 +set r_graphStreamHops 8 + +openworld_status +``` + +Demo mod ships commented defaults in `demo_openworld.cfg` (`exec demo_openworld.cfg`). For MP, also set **`sv_openWorldResidency 1`** on the dedicated server. + ## Multiplayer rules - **Server collision is authoritative.** `SV_OpenWorld_Frame` with `sv_openWorldResidency 1` plans collision from the union of active player origins, then publishes via `CS_ENGINE_OPENWORLD_SECTORS`.