# Subsystem Glossary & Module Map

This is the orientation map for V4 — the page to read before any deep
architecture page, so that every later reference to "the `V4Tactical` module,"
or "the `V4Mode_Stealth_Hitman` plugin," or "the tournament-server target" lands
on a name you already trust. V4 is a single Unreal Engine 5.5 tactical-action
game whose ambition is **per-cell feel**: one shared roster and online backbone,
with tactical-FPS, real-time-stealth-tactics, action-RPG, RTS, and 2D
run-and-gun gameplay layers swapped in as plugins. Its module split is not
cosmetic packaging — it exists so that each cell's gameplay can be authored,
compiled, and cooked in isolation behind an explicitly declared, acyclic
dependency graph, and so that a frame-critical system (combat authority, RTS
lockstep) stays in C++ rather than Blueprint. The single source of truth is the
engine project at `V4/ue/`: its `.uproject` enumerates **28 C++ modules** and
force-enables a curated set of engine and project plugins, and every module
under `V4/ue/Source/` carries its own `*.Build.cs` declaring exactly what it
links. This page reconciles that on-disk reality with the prose glossary in the
architecture monolith, and names the surrounding Rust services and web surfaces
the game talks to. It is the companion to the catalogue at
[../V4_ARCHITECTURE.md](../V4_ARCHITECTURE.md).

The reason to read the _code_ rather than the glossary table is that, even when
a table is mostly right, the load-bearing edges are where it drifts. V4 is the
happy case: its 27-row "engine modules" glossary maps **one-to-one** onto real
`Source/` directories — there are no spec-only modules here, unlike V2. But the
dependency table understates several real edges, the build targets do far less
than the determinism prose implies, and the "GameFeatures hot-swap" framing
describes an aspiration the plugins only partly realize. Where the map and the
territory disagree, this page treats the `.uproject` and the `Build.cs` files as
authoritative and says so each time — an honest "the table omits this edge" is
worth more than a confident restatement the compiler would expand differently.

## What ships, honestly

**Real and on-disk (the compiler agrees):** the **28** module directories under
`V4/ue/Source/` are all present, each with a `*.Build.cs`, a
`Public/`/`Private/` split, and a module class; the `.uproject` `Modules` array
lists the matching 28 names (verified: 28 source directories == 28 `.uproject`
entries). The 27 glossary engine-module names (`V4Core` … `V4Tests`) map exactly
onto 27 of those directories; the 28th is the `V4` primary game module, which
the glossary table omits but the Project Layout names. **No module is a
three-file skeleton** — even the leanest (`V4Crowd`, `V4VFX`, `V4Telemetry`,
`V4Procgen`, ~4 source files each) ship a real `U*Subsystem` plus a `*Types.h`,
not just a `.cpp`/`.h`/`.Build.cs` stub. The depth is concentrated where the
genre needs it: `V4OnlineServices` (34 source files), `V4Tactical` (24),
`V4ActionRPG` and `V4RTS` (22 each), `V4Core` and `V4Netcode` (19), with **461
`.cpp`+`.h` files across the 28 modules** and a `V4Tests` module holding **90
automation specs** (`AttributeSetSpec`, `CoverSpec`, `CoDWarzoneSpec`,
`CommandosSpec`, `ContractScheduleSpec`, `AIDirectorSpec`, …). The cell plugins
are real code, not content shells: the **28 enabled `V4Mode_*` plugins** carry
their own runtime C++ modules totalling **~234 authored `.cpp`+`.h` files**
under `V4/ue/Plugins/` (the gitignored UHT codegen under `Intermediate/Build` is
not counted).

**Glossary and layout drift (found by reading the disk), labelled:**

- **The Module Split table is directionally correct but understated.** Every
  cross-module `V4*` edge it lists is real in the `Build.cs` files, and the
  graph is acyclic as claimed. But it omits the GAS plugin dependencies
  (`GameplayAbilities`, `GameplayTags`) that nearly every cell module actually
  links, omits **`V4UI → V4Stealth`** and
  **`V4Editor → {V4Schedules, V4Tactical}`** entirely, and drops a long tail of
  engine deps (`RenderCore` on Core, `Json` + `ReplicationGraph` +
  `OnlineSubsystem` on Netcode, `GeometryCollectionEngine` on Vehicles,
  `MotionWarping` on Animation, `GameFeatures` on Modes, `UMG` on Schedules).
- **The cells are modular C++ plugins, not V3-style content-only
  GameFeatureData.** Each `V4Mode_*` `.uplugin` declares a `Runtime` module that
  depends on `V4Core`, `V4Modes`, and its cell module. But they are
  **force-enabled by the project** (`"EnabledByDefault": false` in the
  `.uplugin`, `"Enabled": true` in the `.uproject`), not `ExplicitlyLoaded`
  runtime-toggled features — so the "hot-swap" framing is aspirational. The
  activation _machinery_ is nonetheless real C++: `V4Modes` ships
  `UV4GameFeatureAction_ActivateModeAssets` and a `V4ModeSubsystem`.
- **The three build targets are minimal.** `V4.Target.cs` (Game),
  `V4Editor.Target.cs` (Editor), and `V4TournamentServer.Target.cs` (Server) set
  only `BuildSettingsVersion.V5`, the include-order version, and
  `ExtraModuleNames.Add("V4")`. None sets `bUseUnityBuild = false`, strict
  floating-point flags, `DETERMINISM=*` defines, a `PreBuildStep`, or
  per-platform module stripping. The monolith's "stripping is `.Target.cs`
  driven" and its determinism posture are aspirational at the target layer;
  determinism logic lives _inside_ `V4Netcode`/`V4RTS`, not stamped by the
  target as in V2/V3.
- **There is no `V4Server` source module.** The Project Layout's
  `Source/V4Server/` does not exist; the dedicated-server build is the
  `V4TournamentServer` target, which adds four broadcast defines
  (`V4_TOURNAMENT_BUILD`, `V4_BROADCAST_TOOLS`, `V4_OBSERVER_CAMERAS`,
  `V4_PAUSE_ON_DISCONNECT`) and no extra source.
- **V4 has no TypeScript/contracts/libs footprint.** There is no `libs/v4`, no
  `libs/contracts/src/v4`, no `apps/v4`, and no web tile under
  `apps/oshun/web/.../v4`. V4 is self-contained under `V4/`; its backend is a
  compact **three-crate Rust workspace**, not the nine services the layout
  lists.
- **V4 ships essentially no binary content** — exactly one `.uasset`/`.umap` in
  the whole tree. It is a C++ logic skeleton; the `Content/` trees and the
  top-level data directories (`balance/`, `modes/`, `maps/`, `codex/`, …) are
  JSON authoring data, not cooked assets.

Everything below is grounded in those files; where a claim is the glossary's
intent rather than shipped code, it is labelled.

## The module graph as it is built

Unlike V2 and V3, V4 does **not** hoist any module into the `PreDefault` loading
phase: all 28 modules load at `Default` except `V4Editor` (`Editor` type,
`PostEngineInit`) and `V4Tests` (`DeveloperTool`). Reading every `*.Build.cs`
and extracting the `V4*` dependencies yields a clean **directed acyclic graph**
whose single sink is `V4Core` — the monolith's "no circular deps" claim holds in
code. The diagram below is the graph as actually declared (engine-plugin deps
elided), grouped by concern.

```mermaid
flowchart TB
    subgraph FOUND["Foundation"]
        Core[V4Core]
    end
    subgraph SPINE["GAS spine"]
        Gameplay[V4Gameplay]
        Anim[V4Animation]
        Input[V4Input]
        Net[V4Netcode]
        Modes[V4Modes]
    end
    subgraph AI["Perception / crowd / schedules"]
        Perc[V4Perception]
        Crowd[V4Crowd]
        Sched[V4Schedules]
    end
    subgraph CELLS["Per-cell gameplay"]
        Tac[V4Tactical]
        Stl[V4Stealth]
        Tcs[V4Tactics]
        ARPG[V4ActionRPG]
        RTS[V4RTS]
        Arc[V4Arcade]
    end
    subgraph PRES["Presentation & services"]
        UI[V4UI]
        LevelOps[V4LevelOps]
        Veh[V4Vehicles]
        Editor[V4Editor]
    end

    Gameplay --> Core
    Anim --> Core
    Input --> Core
    Net --> Core
    Modes --> Core & Gameplay
    Perc --> Core
    Crowd --> Core & Perc
    Sched --> Core & Crowd & Perc
    Tac --> Core & Gameplay & Anim & Input
    Stl --> Core & Gameplay & Perc
    Tcs --> Core & Gameplay & Perc & Sched
    ARPG --> Core & Gameplay & Anim
    RTS --> Core & Gameplay & Net
    Arc --> Core & Gameplay & Anim
    UI --> Core & Stl
    LevelOps --> Core & Sched
    Veh --> Core & Gameplay
    Editor --> Core & Sched & Tac
```

`V4Audio`, `V4VFX`, `V4Cinematics`, `V4Persistence`, `V4OnlineServices`,
`V4Telemetry`, and `V4Procgen` each depend on `V4Core` only (plus engine
plugins), so they are leaves and are omitted from the diagram for clarity.
`V4Tests` sits above everything — its `Build.cs` depends on **all** runtime
modules _and_ the `V4Mode_*` plugins, which is why the automation harness can
exercise any cell.

### The thin composition root: the `V4` module

The module named simply `V4` (`V4/ue/Source/V4/`, six files) is the only module
the `Game`, `Editor`, and `Server` targets name via
`ExtraModuleNames.Add("V4")`. But unlike V2's composition root — which fused the
spine by hard-depending on combat, modes, and netcode — **V4's `V4` module
depends on no `V4*` module at all**; its `Build.cs` lists only `Core`,
`CoreUObject`, `Engine`, `GameplayTags`, `InputCore`. It is a thin bootstrap:
`UV4BootstrapSubsystem` (a `UGameInstanceSubsystem` that resolves the boot map
and platform config root) and `V4GameplayTagsManager`. The gameplay spine is
pulled in instead by the cell plugins (each depends on its cell module) and by
`V4Tests`. So the "primary game module" is a launcher, and the real fusing
happens through the modular-plugin layer rather than a monolithic root.

### The per-cell plugins carry real code

The 28 enabled `V4Mode_*` plugins live **directly under `V4/ue/Plugins/`** (not
under a `Plugins/GameFeatures/` subfolder as in V3). Each is a code+content
plugin: a `.uplugin` declaring a `Runtime` module, a `Source/` tree, and a
`Content/` tree. Their depth tracks the cells' complexity —
`V4Mode_Tactical_CoDWarzone` (26 `.cpp`), `V4Mode_Stealth_SplinterCell` (20),
`V4Mode_Tactical_CoDMultiplayer` and `V4Mode_Stealth_SpiesVsMercs` (18 each),
the three RavenShield/R6Modern/CoDCampaign tactical plugins (16 each) — while
the lighter modes (`V4Mode_ARPG_Wukong`, `V4Mode_Arcade_Contra`, …) carry ~10. A
typical `Build.cs` (`V4Mode_ARPG_Wukong`) depends on `V4Core`, `V4Modes`,
`V4ActionRPG` plus `GameplayTags` — i.e. the plugin binds a cell module to the
mode-registration layer. Two artifacts are present that the glossary's plugin
table omits: **`V4Mode_Crossover_ShadowWar`** (a real, enabled, 6-file crossover
mode) and **`V4Tools_DataLinter`** (an editor linter alongside the documented
`V4Tools_AssetLinter`). Four **`V4DLC_*`** plugins (`ADR_CommunityRemix01`,
`ADR_ParodyPack01`, `Campaign_Season01_Blacksite`, `Operator_Season01_Nyx`)
exist on disk but are **content-only** (zero `.cpp`) and **not enabled** in the
`.uproject` — they are season-DLC containers, not runtime code.

## The module map, by concern

The 28 modules group into seven concerns. Dependency notes below are the
_verified_ `Build.cs` contents; where they exceed the Module Split table, that
is the drift called out above.

**Foundation.** `V4Core` (19 files) is the sink of the graph — engine
subsystems, the gameplay-tag registry, save scaffolding, dev cheats. It links
`Core`/`CoreUObject`/`Engine`/`InputCore`/`RenderCore`/`Slate`/`SlateCore` and
no `V4*` module.

**GAS spine.** `V4Gameplay` (15) is the ability-system layer
(`GameplayAbilities`, `GameplayTags`, `GameplayTasks`). `V4Animation` (10) adds
`AnimGraphRuntime`, `PoseSearch`, `Mover`, `Chooser`, `MotionWarping`. `V4Input`
(14) wraps `EnhancedInput`. `V4Netcode` (19) is the networking core
(`NetworkPrediction`, `Iris`, `ReplicationGraph`, `OnlineSubsystem`, `Json`) and
hosts the client-server, deterministic-lockstep, and rollback-prediction paths.
`V4Modes` (14) is the mode registry — `ModularGameplay` + `GameFeatures` +
`Json` — and owns `UV4GameFeatureAction_ActivateModeAssets` and
`V4ModeSubsystem`.

**Per-cell gameplay (Tier 2).** Six mutually-exclusive cell modules:
`V4Tactical` (24) for FPS aim/ADS/recoil/cover; `V4Stealth` (16) for
light/shadow/disguise; `V4Tactics` (16) for the RTST command queue and
time-stop; `V4ActionRPG` (22) for souls-like stamina/parry/posture; `V4RTS` (22)
for economy/build-orders/fog-of-war (the only cell that depends on `V4Netcode`,
for lockstep); and `V4Arcade` (18) for the 2D run-and-gun layer over `Paper2D`.
Every cell also links `GameplayAbilities`/`GameplayTags` (the table omits this).

**Perception, crowd, schedules.** `V4Perception` (10) is the unified
sight/sound/suspicion model (`AIModule`, `NavigationSystem`). `V4Crowd` (4) is
the Mass-ECS crowd layer — lean in files but linking six Mass modules
(`MassEntity`, `MassNavigation`, `MassAIBehavior`, `MassMovement`,
`MassReplication`, `MassSignals`). `V4Schedules` (12) layers NPC daily routines
over both (`V4Crowd`, `V4Perception`, plus `UMG`).

**Presentation.** `V4UI` (17) is the CommonUI/MVVM front-end — and it depends on
`V4Stealth` (for stealth-gauge HUD), an edge the table omits. `V4Audio` (12,
MetaSounds), `V4VFX` (4, Niagara), and `V4Cinematics` (8, Sequencer +
MovieRenderPipeline, with `Sequencer` editor-gated) round out the A/V layer.

**Online, persistence, telemetry, world.** `V4OnlineServices` (34, the deepest
module — `OnlineServicesInterface`/`Common`, `EOSShared`), `V4Persistence` (18,
`Serialization`), `V4Telemetry` (4, `HTTP`+`Json`), `V4Vehicles` (10,
`ChaosVehicles` + `GeometryCollectionEngine`, and the P3 sports-vehicle
registry), `V4Procgen` (4, `PCG`), and `V4LevelOps` (8, NPC-schedule and
environmental-kill authoring over `V4Schedules`).

**Tools, editor, tests.** `V4Editor` (5,
`UnrealEd`/`EditorSubsystem`/`ToolMenus` plus `V4Schedules` and `V4Tactical`) is
the in-editor mission/contract tooling; `V4Tests` (96 files) is the automation
and gauntlet harness.

## Build targets and the determinism gap

Three `*.Target.cs` files exist: `V4` (Game), `V4Editor` (Editor), and
`V4TournamentServer` (Server). All three are minimal — they set the
build-settings version, include-order version, and the single `V4` extra module,
and the server target additionally disables developer tools and adds its four
broadcast defines. What they conspicuously do **not** do is what V2's and V3's
targets do: there is no `bUseUnityBuild = false`, no `/fp:strict` /
`-fno-fast-math` strict-FP block, no `DETERMINISM`/`V4_STRICT_FP` defines, no
`PreBuildStep`, and no platform stripping of
`V4Mode_Tactical_CoDWarzone`/`R6Modern`. So the architecture's "RTS
deterministic lockstep," "rollback-emulated prediction," and "stripping is
`.Target.cs` driven" descriptions are implemented (if at all) **inside the
runtime modules**, not stamped onto every module by the target. Read the
determinism and stripping prose as a module-level intent, not a build-target
guarantee. (See [./high-level-architecture.md](./high-level-architecture.md) for
the runtime-tier picture this implies.)

## Project layout: where V4 actually lives

V4 is unusually self-contained. Four homes hold all of it, and three of the four
are under `V4/` itself.

- **`V4/ue/`** — the one UE5.5 project: 28 `Source/` modules, 3 targets, ~34
  enabled plugins (engine + project), and `Plugins/` containing the 28 enabled
  `V4Mode_*` code plugins, 2 `V4Tools_*` editor linters, and 4 content-only
  `V4DLC_*` plugins. Engine plugins read like a genre bill of materials:
  `GameplayAbilities`, `EnhancedInput`, `CommonUI` + `ModelViewViewModel`, the
  animation stack (`MotionWarping`, `PoseSearch`, `Mover`, `Chooser`),
  `Niagara`, the Chaos set (`ChaosVehicles`, `ChaosCloth`, `ChaosFlesh`,
  `GeometryCollection`), `Metasound` + `SteamAudio` + `ResonanceAudio`, the
  networking set (`ReplicationGraph`, `NetworkPrediction`, `Iris`), the Mass set
  (`MassEntity`/`MassAI`/`MassGameplay`), `PCG`, `Paper2D`, `OpenXR` + hand/eye
  tracking, `AppleARKit`/`AppleVision`, and `Gauntlet`.
- **`apps/v4/`** — a Rust (`resolver = "2"`, `axum`) workspace with **three**
  crate members: `shared` (343 lines), `telemetry-ingest` (587 lines), and
  `online-services` (**8,581 lines**, consolidating `oauth`, `matchmaking`,
  `brackets` (leaderboards/ladders), `sfu`, and `http`). The Project Layout's
  nine separate services (login, matchmaking, replay, leaderboard, anti-cheat,
  workshop, moderation, balance-ledger) are aspirational; the real backend folds
  most of them into `online-services`.
- **Web & companion surfaces** — `apps/v4/web` (`@v4/web`, Next.js, port 3045,
  the marketing site), `apps/v4/spectator` (`@v4/spectator`, Next.js, port 3044,
  the spectator/esports portal), and `apps/v4/companion` (`@v4/companion`,
  Expo/React Native, including the flat-surface AR replay projection).
  `V4/tools/` holds only the `esports` toolkit — the layout's `missions/`,
  `rts-maps/`, `arcade-art/`, `balance/`, and `release/` tool dirs do not exist
  there.
- **Data-authoring trees** — the many top-level `V4/` directories (`balance/`,
  `modes/`, `maps/`, `codex/`, `narrative/`, `liveops/`, `progression/`, `loc/`,
  `release/`, `roadmap/`, `wiki/`, `ops/`, `perf/`, …) are JSON/Markdown
  authoring and ops data that feed the game and the live-service backend, not
  compiled code.

Because there is no `libs/contracts/src/v4`, V4's data contracts live in UE C++
`UDataAsset`/`DataTable` types and in the per-service Rust structs, not a shared
cross-language registry — the same posture V2 took, and a deliberate contrast
with V3's Zod-registry spine. For how V4 nonetheless rides the shared Oshun
platform for identity and gateway concerns, see
[../../platform/overview.html](../../platform/overview.html).

## Glossary reconciliation table

The fastest way to use the monolith glossary safely is to read it through this
column. "Module" = a directory under `V4/ue/Source/` with a `Build.cs`; "Plugin"
= a plugin under `V4/ue/Plugins/`; "Service" = a Rust crate under `apps/v4/`.

| Glossary name                                | On disk as                                                                                 |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `V4Core` … `V4Tests` (27 engine modules)     | **Module** — all 27 present, 1:1, none spec-only                                           |
| `V4` (primary game module)                   | **Module** — present; omitted from the glossary table, named in Project Layout             |
| `V4Mode_*` (27 listed)                       | **Plugin (code+content)** — all present and force-enabled; each ships a runtime C++ module |
| `V4Mode_Crossover_ShadowWar`                 | **Plugin** — real and enabled, **not in the glossary**                                     |
| `V4Tools_AssetLinter` / `V4Tools_DataLinter` | **Plugin (editor)** — AssetLinter in layout; DataLinter undocumented                       |
| `V4DLC_*` (4)                                | **Plugin (content-only, disabled)** — 0 `.cpp`; season-DLC containers, not in glossary     |
| `V4Server` (Project Layout)                  | **Spec** — no such source module; the server build is the `V4TournamentServer` target      |
| 9-service backend / 6-tool tree              | **Spec/partial** — real backend is 3 Rust crates; `tools/` holds only `esports`            |

## Where to go next

- The product framing this topology serves:
  [./product-promise.md](./product-promise.md).
- The runtime-tier and cross-cutting-services picture:
  [./high-level-architecture.md](./high-level-architecture.md).
- How V4 rides the shared Oshun platform (identity, BFF, contracts):
  [../../platform/overview.html](../../platform/overview.html).
- The full catalogue, including the GAS layout, netcode, AI/perception, and
  per-cell deep-dives: [../V4_ARCHITECTURE.md](../V4_ARCHITECTURE.md).