# V4 Product Promise & Architectural Overview

```mermaid
flowchart TB
  Shared[Shared engine spine] --> Cell{Activated ruleset cell}
  Cell --> Tactical[Tactical FPS layer]
  Cell --> Stealth[Stealth tactics layer]
  Cell --> ARPG[Action RPG layer]
  Cell --> RTS[Strategy layer]
  Cell --> Arcade[Run-and-gun layer]
  Tactical --> Runtime[Authoritative match runtime]
  Stealth --> Runtime
  ARPG --> Runtime
  RTS --> Runtime
  Arcade --> Runtime
  Runtime --> Common[Shared roster, online, creator, narrative]
```

Architecturally, the active cell is a bounded gameplay layer rather than a
forked executable. It specializes abilities, attributes, content, and feel, then
rejoins the common runtime for the systems that must remain coherent across the
universe.

V4 is one game — a tactical-action _universe_ built on Unreal Engine 5.5 — not a
launcher bolted over five unrelated titles. It commits to delivering
**per-ruleset feel**: when you are in a Hitman-style mission it must feel like
Hitman, when you are fighting a Wukong boss it must feel like a souls-like, and
when you are macro-managing a base it must feel like StarCraft — "no compromise
blends" — yet every one of those experiences shares one roster, one creator
suite, one online backbone, and one unifying narrative (The Shadow War). The
architecture exists to make that ambition shippable: each game-style _cell_ is a
swappable gameplay layer over a common engine, so cells can be enabled,
disabled, stripped per platform, or sold as DLC without forking the foundation.

That is not aspirational prose — it is wired through the repository. The UE
project at `V4/ue/V4.uproject` pins `"EngineAssociation": "5.5"`, declares **28
C++ modules**, and enables a SOTA plugin set (GameplayAbilities, EnhancedInput,
Mover + PoseSearch + Chooser motion matching, Niagara, MetaSounds, Chaos
cloth/flesh/ vehicles, ReplicationGraph + NetworkPrediction + Iris, MassEntity,
PCG, Paper2D, OpenXR, EOS). Exactly those 28 module names exist as directories
under `V4/ue/Source/` — there is no drift between the project file and disk —
and the tree carries **272 `.cpp` and 189 `.h`** files of genuine,
domain-specific gameplay code plus **34 plugin directories** under
`V4/ue/Plugins/`, of which 28 are `V4Mode_*` Game Feature plugins with their own
C++ modules. Like V2, V4 holds itself to a target-artifact discipline: "Where a
section names a module or path, it names a **target artifact** unless the path
already exists in the repo. The TODO that first references the artifact owns
creating it with tests and validation" (`V4/V4_ARCHITECTURE.md`, Purpose). This
page is the orientation door to that architecture — it states the product V4
commits to and separates what is real on disk from what is spec; the deep module
map is its sibling [./glossary.md](./glossary.md), the runtime topology is
[./high-level-architecture.md](./high-level-architecture.md), and the full
section hub is [../V4_ARCHITECTURE.md](../V4_ARCHITECTURE.md).

## What ships, honestly

The **module skeleton is real and consistent.** `V4.uproject` lists 28 modules
and exactly 28 directories exist under `V4/ue/Source/`; the three build targets
— `V4.Target.cs` (Game), `V4Editor.Target.cs` (Editor), and
`V4TournamentServer.Target.cs` (a real `TargetType.Server` with
broadcast/observer/ pause-on-disconnect definitions) — are all present. Several
modules carry genuine weight rather than stubs: `V4Tactical` (12 `.cpp`: aim,
ADS, cover, stance, grenade, revive, weapon-attachment, recoil-curve assets,
weapon-switch), `V4RTS` (11 `.cpp`: resource economy, build/train queues,
tech-tree, age-up, wonders, fog-of-war, a pathfinding subsystem, unit groups),
`V4ActionRPG` (11 `.cpp`: stamina, posture, parry, dodge, hero-combo,
transformation, charm, spell-craft), and `V4OnlineServices` (15 `.cpp` / 19
`.h`). `V4Tests` is the largest module at **92 `.cpp`** — a per-cell automation
harness, not a token directory.

The **Gameplay Ability System spine is real.**
`V4/ue/Source/V4Gameplay/Public/ V4AttributeSets.h` defines per-cell attribute
sets that extend a shared `UV4AttributeSetBase` and are mutually exclusive at
runtime: `UV4Attr_Tactical` (Health, Armor, Suppression, StaminaSprint,
AmmoCurrent, AmmoReserve), `UV4Attr_Stealth` (Health, Detection, DisguiseClass,
Noise), `UV4Attr_Tactics` (Health, ActionPoints, Vision), and the
ARPG/RTS/Arcade sets alongside them — plus a real `UV4AbilitySystemComponent`
and a `UV4MatchStateSubsystem`.

The **per-cell netcode is real, and its determinism lives in code, not in
compiler flags.** This is the most important honest distinction from V2. V2
enforces rollback determinism through strict-FP build-target flags
(`/fp:strict`, `-ffp-contract=off`) and a deterministic cook policy; **V4's
build targets carry no such flags.** Instead, `V4Netcode` implements determinism
as runtime logic: `UV4RTSLockstepSubsystem`
(`Source/V4Netcode/Public/V4RTSLockstepSubsystem.h`) runs seed-configured
lockstep with per-frame state hashing —
`ConfigureMatch(MatchConfigHash, RngSeed)`, `AdvanceLockstepFrame`,
`CheckRemoteFrameHash` for desync detection, `RecoverFromDesync`,
`BuildLateJoinerRebuildFrame`, a deterministic `DrawMatchRandomInt`, and a
`ValidateRngConsumptionOrder` audit — backed by a seeded `FSeededRng` and
`UV4DeterministicRngStream` in `V4LocalDeterminism.h`. Twitch PvP gets
`UV4RollbackEmulatedComponent` (`SimulatePredictedInputFrame`,
`ReconcileAuthoritativeInputFrame`), and dedicated-server modes get
`UV4ServerAuthorityComponent` + `UV4ReplicationBandBudgeter`. The three netcode
strategies the promise names are each implemented as a distinct C++ surface.

The **Game Feature plugins are stronger than V2's and weaker than V3's, and the
page says exactly where.** Unlike V2 — whose 60-plus mode plugins were _planned_
surfaces with no on-disk presence — V4 ships **34 real plugin directories**,
each with a valid `.uplugin` descriptor (correct module declarations and
inter-plugin dependencies, e.g. `V4Mode_Tactical_CoDWarzone` depends on
`V4Mode_Tactical_CoDMultiplayer`): 28 `V4Mode_*` cells/modes, 4 `V4DLC_*`
content packs, and 2 `V4Tools_*` linters. Those 28 mode plugins carry **343
`.cpp` files** of real module code. But — unlike V3's 21 shipped
`GameFeatureData.uasset` descriptors — **there are zero `GameFeatureData.uasset`
binaries in-tree**, and the `.uplugin` files declare
`"EnabledByDefault": false, "Installed": false`. The plugin _code_ and
_descriptors_ are real; the binary GameFeature data assets that hot-activate
them are not yet authored.

**Verification is by UE automation, not a python-checker army.** V2 ships 826
JSON contracts paired with 1,155 `check-v2-*.py` scripts; V4 has exactly **one**
`.py` file. Its backbone is instead `V4Tests` (92 `.cpp` of per-cell/per-mode
specs — `V4ModeARPGWukongTests`, `V4ModeRTSAsymmetricTests`,
`V4ModeStealthHitmanTests`, …) run through the on-box editor by
`V4/.ci/run-ue-automation-all.sh` (`-ExecCmds="Automation RunTests V4.;Quit"`,
executed as the `ueagent` user because the editor refuses root), with companion
`run-gauntlet-feel-tests.sh` and `run-golden-replays.sh` for feel-gates and
replay regression. The cloud backend under `apps/v4/` is a genuine Rust + axum
0.7 Cargo workspace (`shared`, `telemetry-ingest`, `online-services`).

The honest gaps are these, and the page names them rather than implying
ship-state:

- **No authored binary content.** `V4/ue/Content/` holds **0 `.uasset` and 1
  `.umap`**. What it _does_ hold is **428 `*.uasset.v4asset.json`** manifest
  sidecars (e.g. `DA_ShaderWarmupPlan.uasset.v4asset.json`, which carries a
  structured PSO- precache / shader-prewarm / mission-preload plan). V4 is a
  **logic-and-manifest skeleton**: real C++ systems and real data manifests, but
  no hand-authored meshes, textures, MetaHumans, mocap, VO, or cinematics
  in-tree. Every "AAA SOTA quality" claim depends on art/audio production that
  is not in the repository.
- **Reserved seams.** `V4TournamentServer.Target.cs` adds `V4_TOURNAMENT_BUILD`,
  `V4_BROADCAST_TOOLS`, `V4_OBSERVER_CAMERAS`, and `V4_PAUSE_ON_DISCONNECT` as
  global definitions, but **no `.cpp`/`.h` under `Source/` or `Plugins/`
  branches on them** — they are reserved compile seams, exactly the honesty
  caveat V2 carries for its `V2_DETERMINISM` defines.
- **Provider-gated surfaces.** Cross-play and cross-progression across the 9
  day-one platforms depend on `OnlineServices`/`EOSShared` and per-platform back
  ends; these are real integrations awaiting credentials and platform sign-off,
  not failures.
- **Unverifiable ops claims.** With launch dated **2026-10-01**, the planning
  corpus marks real-world operations claims `[~]` (cannot be verified from the
  repo, and mostly cannot have occurred yet) — a convention established in
  `V4/REMEDIATION_2026-06-12.md`.

## The product promise

V4's promise, authored in `V4_features.md` § "V4 Product Promise" and mirrored
in the architecture's `V4 Product Promise` section, is a small set of
non-negotiable commitments. The unifying idea is **per-ruleset feel, one shared
spine.**

| #   | Commitment                                                                                                             | Code-grounding / status                                                                                                |
| --- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 1   | One product, not five — per-ruleset feel with no compromise blends                                                     | Six cell modules under `Source/` + 28 `V4Mode_*` plugins; identity routed by `UV4ModeSubsystem`                        |
| 2   | Dedicated-server client-server netcode **default** for tactical PvP (5v5, 6v6, BR)                                     | `UV4ServerAuthorityComponent` + `UV4ReplicationBandBudgeter` (`V4Netcode`); `V4TournamentServer.Target.cs` is `Server` |
| 3   | Deterministic lockstep for RTS; rollback-emulated prediction for twitch PvP                                            | `UV4RTSLockstepSubsystem` (seeded RNG + frame-hash desync) and `UV4RollbackEmulatedComponent` — both real C++          |
| 4   | One shared AI perception model across every NPC in every cell                                                          | `UV4PerceptionComponent` + `UV4SuspicionStateMachine` (`V4Perception`), used by Stealth, Tactics, Crowd                |
| 5   | Complete launch content across every advertised mode — no "coming soon" panels                                         | 34 plugins on disk; gap: no `GameFeatureData.uasset` / authored content yet (logic+manifest skeleton)                  |
| 6   | First-class single-player per cell (campaigns, mocap principals, VO, 4K cinematics)                                    | `V4Cinematics` (Sequencer) module present; mocap/VO/render art **not in-tree** — production-gated                      |
| 7   | Degrade safely (offline, partial-net, controller-loss, mid-match-disconnect, provider-outage; RTS pause-on-disconnect) | `V4_PAUSE_ON_DISCONNECT` seam in the server target; PvE replay serializer in `V4LocalDeterminism`                      |
| 8   | Run on 9 platforms day-one (+ PixelStreaming thin-client where contract permits)                                       | Per-platform stripping is `.Target.cs`-driven; cross-play is provider-gated via `OnlineServices`/`EOSShared`           |
| 9   | Live service from day one — seasonal contracts, out-of-band balance, a public balance ledger                           | Rust `apps/v4/` + `V4/balance/`, `V4/esports/`; ops cadence marked `[~]` pre-launch                                    |

The netcode commitments (2–3) are one decision expressed as a **per-cell
envelope**, because no single strategy fits a 100-player battle royale, a 2v2
RTS, and a 60 Hz twitch duel. The promise draws the line and the code mirrors
it: dedicated-server authority for large-roster and free-roam tactical play,
deterministic lockstep for RTS (where re-simulation demands bit-identical state,
enforced by `FSeededRng` + frame hashing rather than by floating-point compiler
flags), and rollback-emulated client prediction for tight twitch PvP.

## The multi-cell thesis: per-ruleset feel, one spine

V4 ships **six gameplay cells, each backed by a dedicated engine module**, and
each realizing a distinct inspirational family on its own terms:

| Cell module   | Game-style family                                  | Real domain code (sampled `Public/` surface)                                                       |
| ------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `V4Tactical`  | Tactical FPS (R6 / CoD)                            | `V4AimComponent`, `V4CoverComponent`, `V4GrenadeComponent`, `V4WeaponRecoilCurveAsset`             |
| `V4Stealth`   | Stealth (Splinter Cell)                            | `V4LightGaugeComponent`, `V4SoundFootprintComponent`, `V4BodyDragComponent`, `V4DisguiseComponent` |
| `V4Tactics`   | Real-time stealth tactics (Commandos / Desperados) | RTST party, command queue, vision cones, time-stop Showdown (module documented role)               |
| `V4ActionRPG` | Souls-like ARPG (Wukong)                           | `V4PostureComponent`, `V4ParryComponent`, `V4DodgeComponent`, `V4TransformationComponent`          |
| `V4RTS`       | Real-time strategy (StarCraft / AoE)               | `V4ResourceComponent`, `V4TechTreeComponent`, `V4AgeUpComponent`, `V4FogOfWarComponent`            |
| `V4Arcade`    | 2D run-and-gun (Contra)                            | `V4SideScrollComponent`, `V4WeaponPickupComponent`, `V4LivesComponent` (Paper2D)                   |

A useful nuance, surfaced honestly: the _promise text and high-level diagrams_
sometimes collapse these into **five** "game-style families" (folding stealth
into the tactical bucket), but the disk carries **six** distinct cell modules,
and the 2026-06-12 remediation canonicalized the launch-cell count to six across
the gate language (`V4/REMEDIATION_2026-06-12.md`, Stage 1 §1).

The cells are held together — not blended — by shared infrastructure. The
clearest example is perception: a Hitman guard, a Commandos patrol, a Splinter
Cell mercenary, and a Wukong yaoguai all read stimuli from the _same_
`UV4PerceptionComponent` (extending `UAIPerceptionComponent`) and the _same_
`UV4SuspicionStateMachine`, with `V4Crowd` (Mass-backed) layering Hitman-style
crowd density and panic on top. One shared roster (operators, heroes, units)
hangs cell-specific mesh/sprite overrides off a unified operator record, and
`UV4ModeSubsystem` + `V4GameFeatureAction_ActivateModeAssets` route which cell's
ruleset and HUD are live. Per-cell attribute sets being mutually exclusive at
runtime is what lets one character be a Tactical operator in one match and an
ARPG hero in the next without their stat blocks colliding.

## The shared engine

The runtime is a single UE5.5 project whose responsibilities stack from the
engine up, with cells inserted as the swappable top layer:

```text
┌──────────────────────────────────────────────────────────────────────┐
│  Cinematic · AI Director · Live Service · Esports                      │  Tier 4 — live & cinematic
├──────────────────────────────────────────────────────────────────────┤
│  GameFeature plugins (V4Mode_*) — Tactical · Stealth · RTST · ARPG ·   │  Tier 3 — cells
│  RTS · Arcade   (28 plugins, 343 .cpp; no GameFeatureData.uasset yet)  │
├──────────────────────────────────────────────────────────────────────┤
│  V4Tactical · V4Stealth · V4Tactics · V4ActionRPG · V4RTS · V4Arcade   │  Tier 2 — cell + cross-cell
│  V4Perception · V4Crowd · V4Schedules · V4Vehicles · V4Procgen         │
├──────────────────────────────────────────────────────────────────────┤
│  V4Gameplay (GAS) · V4Animation · V4Input · V4Netcode · V4UI · V4Audio │  Tier 1 — engine subsystems
│  V4VFX · V4Cinematics · V4Persistence · V4OnlineServices · V4Telemetry │
├──────────────────────────────────────────────────────────────────────┤
│  Unreal Engine 5.5 (Lumen · Nanite · MetaHuman · Niagara · Chaos · PCG)│  Tier 0 — engine
└──────────────────────────────────────────────────────────────────────┘
```

Module discipline keeps that stack maintainable: every module under
`V4/ue/Source/<Name>/` splits a `Public/` header tree from a `Private/`
implementation tree, cross-module includes follow only the public surface, and
the dependency graph is acyclic — a property the `V4Tools_AssetLinter` plugin is
built to enforce as a static check. Per-platform scope is `.Target.cs`-driven,
not `#ifdef`-scattered: memory-constrained targets strip the heaviest mode
plugins (battle royale, large-population RTS) rather than compiling around them.
Three build targets compile the same source for three roles — player client,
editor, and the headless tournament/dedicated server — and the online backbone
lives _outside_ the client as the Rust `apps/v4/` workspace, so matchmaking,
telemetry ingest, and the balance ledger scale independently of the game binary.
Cross-cutting surfaces — the marketing/wiki web app, the `apps/v4/spectator/`
portal, `apps/v4/companion/`, `V4/esports/`, `V4/balance/`, and `V4/legal/` —
all hang off this one spine rather than forking it, which is the structural form
of promise #9 ("live service from day one"). The full module-and-plugin
catalogue, including the cross-cell support modules (`V4Schedules`,
`V4Vehicles`, `V4Procgen`, `V4LevelOps`) and the per-cell deep-dives, is the
subject of [./glossary.md](./glossary.md) and
[./high-level-architecture.md](./high-level-architecture.md).

## How the promise is kept honest

Two mechanisms keep V4's prose from drifting ahead of its tree. First, the
target-artifact convention: a section that names a module or path either points
at a file that exists or declares a target the owning TODO must build with tests
— so the docs are a contract, not a wishlist. Second, the cross-reference
convention: a bare `§N` or `§N.M` resolves to a numbered task in `V4_TODOS.md`,
while `deps§N` → `V4_DEPENDENCIES.md`, `features§"anchor"` → `V4_features.md`,
and `arch§"anchor"` → the architecture hub. Because the verification backbone is
**UE automation** (`V4Tests` run through the editor by
`V4/.ci/run-ue-automation-all.sh`, plus Gauntlet feel-gates and golden-replay
regression) rather than a static checker army, the honest claim a reader can
make today is precise: the _systems_ compile and pass automation; the _content_
that dresses them — art, audio, MetaHumans, cinematics — is production-gated and
not yet in-tree.

## Related

- Hub: [../V4_ARCHITECTURE.md](../V4_ARCHITECTURE.md); feature map
  `V4/V4_features.md`; backlog `V4/V4_TODOS.md`; dependencies
  `V4/V4_DEPENDENCIES.md`; remediation log `V4/REMEDIATION_2026-06-12.md`
- [./glossary.md](./glossary.md) — the full 28-module / 34-plugin map and fixed
  subsystem vocabulary
- [./high-level-architecture.md](./high-level-architecture.md) — the runtime
  topology, module split, and per-cell deep-dives
- [../../platform/overview.html](../../platform/overview.html) — the shared
  Oshun platform foundations the V4 services and identity surfaces build on