# V4 — Architecture (Tactical Action Universe, Unreal Engine 5) Status: V4 launch architecture and full-vision extension architecture Source: derived from `V4/V4_features.md` (feature map) and `V4/V4_TODOS.md` (implementation backlog) Audience: engineering, online services, build/release, and platform leads scoping V4 Date: 2026-05-15 > **This architecture reference has been decomposed into focused pages under > [`architecture/`](./architecture/README.md).** This file remains the canonical > hub (every section heading is preserved, so existing `arch§"…"` anchors keep > resolving); the in-depth, code-grounded companion pages live under > [`architecture/`](./architecture/README.md). Start at the > [architecture page index](./architecture/README.md). The product feature map > is in [`V4_features.md`](./V4_features.md) / > [`features/`](./features/README.md). ## Purpose This document describes the runtime, package, and integration architecture that V4 must ship behind. It is grounded in the V4 feature map (`V4_features.md`) and the V4 backlog (`V4_TODOS.md`), and is anchored to the packages and modules that the V4 Unreal Engine project must contain. 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. Companion documents are [`V4/V4_features.md`](./V4_features.md), [`V4/V4_TODOS.md`](./V4_TODOS.md), and [`V4/V4_DEPENDENCIES.md`](./V4_DEPENDENCIES.md). V4 is a single coherent tactical-action game whose **per-ruleset feel** ambition spans tactical FPS, real-time stealth tactics, action RPG, real-time strategy, and 2D run-and-gun cells. The architecture mirrors that ambition: one shared roster, one shared creator suite, one shared online backbone, swappable per-cell gameplay layers as GameFeatures plugins. ## Cross-Reference Convention Throughout this document, **bare `§N` and `§N.M` references resolve to `V4_TODOS.md`** (the only V4 doc with section numbering used as hyperlinks). Explicit doc-prefixed references appear where ambiguity matters: - `§40` → `V4_TODOS.md` §40 — the default convention. - `deps§14` → `V4_DEPENDENCIES.md` §14. - `arch§""` → this document, by section anchor. - `features§""` → `V4_features.md` section by anchor (the features doc is not numbered). `V4_features.md` and this document use named anchors, not numbers, to avoid duplicating the TODOs numbering scheme. ## Table of Contents - [V4 Product Promise](#v4-product-promise) - [Subsystem Glossary](#subsystem-glossary) - [High-Level Architecture](#high-level-architecture) - [Project Layout](#project-layout) - [Module Split](#module-split) - [Gameplay Ability System (GAS) Layout](#gameplay-ability-system-gas-layout) - [Attribute Sets](#attribute-sets) - [Ability Classes](#ability-classes) - [GameplayTags](#gameplaytags) - [Effect Stacking](#effect-stacking) - [Animation Pipeline](#animation-pipeline) - [AnimBlueprint Layout](#animblueprint-layout) - [Motion Matching](#motion-matching) - [IK Retargeting](#ik-retargeting) - [MetaHuman Pipeline](#metahuman-pipeline) - [Input Pipeline](#input-pipeline) - [Input Actions](#input-actions) - [Motion Inputs (Fighting-game-like)](#motion-inputs-fighting-game-like) - [Cover-Stick](#cover-stick) - [Tac-Map Cursor](#tac-map-cursor) - [AI Perception, NPC Schedules, Crowd](#ai-perception-npc-schedules-crowd) - [V4Perception Module](#v4perception-module) - [V4Schedules Module](#v4schedules-module) - [V4Crowd Module](#v4crowd-module) - [Performance Budget](#performance-budget) - [Vision Cones, Suspicion, Stealth Gauges](#vision-cones-suspicion-stealth-gauges) - [Vision Cone Authoring](#vision-cone-authoring) - [Suspicion Gauge](#suspicion-gauge) - [Light/Shadow Gauge (Splinter Cell)](#lightshadow-gauge-splinter-cell) - [Sound Footprint](#sound-footprint) - [Per-Cell Architecture Deep-Dives](#per-cell-architecture-deep-dives) - [2D Engine (Contra Cell)](#2d-engine-contra-cell) - [Action RPG Combat Architecture](#action-rpg-combat-architecture) - [Disguise System Architecture](#disguise-system-architecture) - [Showdown Mode Architecture](#showdown-mode-architecture) - [Networking, Authority & Determinism](#networking-authority--determinism) - [Combat Authority & Determinism](#combat-authority--determinism) - [RTS Deterministic Lockstep](#rts-deterministic-lockstep) - [Client-Server Netcode (Tactical PvP, Battle Royale)](#client-server-netcode-tactical-pvp-battle-royale) - [Rollback-Emulated Prediction (Twitch PvP)](#rollback-emulated-prediction-twitch-pvp) - [Game Modes (GameFeatures Plugins)](#game-modes-gamefeatures-plugins) - [Mode-State Machine](#mode-state-machine) - [Sandbox Streaming (World Partition + Crowd)](#sandbox-streaming-world-partition--crowd) - [World Partition](#world-partition) - [Streaming + Crowd](#streaming--crowd) - [Asset Memory](#asset-memory) - [Procedural Generation Pipeline](#procedural-generation-pipeline) - [PCG Graphs](#pcg-graphs) - [Validation](#validation) - [Daily Mission](#daily-mission) - [Persistence & Profile](#persistence--profile) - [Save Game](#save-game) - [Currency Ledger](#currency-ledger) - [Cosmetic Inventory](#cosmetic-inventory) - [Online Services Backend](#online-services-backend) - [Service Inventory](#service-inventory) - [Inter-Service Communication](#inter-service-communication) - [Data Stores](#data-stores) - [Anti-Cheat](#anti-cheat) - [Cross-Play & Cross-Progression](#cross-play--cross-progression) - [Audio Pipeline](#audio-pipeline) - [MetaSounds Patches](#metasounds-patches) - [Audio Modulation](#audio-modulation) - [Spatial Audio](#spatial-audio) - [Voice / Dialogue](#voice--dialogue) - [Music Composers (per cell)](#music-composers-per-cell) - [VFX Pipeline](#vfx-pipeline) - [Particle Systems](#particle-systems) - [LOD Buckets](#lod-buckets) - [Cinematic Pipeline](#cinematic-pipeline) - [Cinematic Cameras](#cinematic-cameras) - [MetaHuman Integration](#metahuman-integration) - [Replay System](#replay-system) - [UI / HUD Architecture](#ui--hud-architecture) - [Front-End Shell](#front-end-shell) - [In-Match HUDs](#in-match-huds) - [ModelViewViewModel](#modelviewviewmodel) - [Telemetry & Analytics](#telemetry--analytics) - [Event Schema](#event-schema) - [Batched Sender](#batched-sender) - [Dashboards](#dashboards) - [Build, Cook, Patch](#build-cook-patch) - [Build System](#build-system) - [Cook](#cook) - [Patch](#patch) - [Data Architecture](#data-architecture) - [Data Tables](#data-tables) - [Localization](#localization) - [Live-Service & DLC](#live-service--dlc) - [GameFeatures Plugin Strategy](#gamefeatures-plugin-strategy) - [Season Cadence](#season-cadence) - [Accessibility](#accessibility) - [Security, Privacy, Compliance](#security-privacy-compliance) - [Identity](#identity) - [Compliance](#compliance) - [Audit](#audit) - [Observability, Evaluation, Release Gates](#observability-evaluation-release-gates) - [Observability](#observability) - [Release Gates](#release-gates) - [Performance Budgets](#performance-budgets) - [Frame Budget Breakdown (PS5 Tactical FPS, 60 fps = 16.6 ms)](#frame-budget-breakdown-ps5-tactical-fps-60-fps--166-ms) - [Memory Budget (PS5)](#memory-budget-ps5) - [Testing, QA, Cert](#testing-qa-cert) - [Automation](#automation) - [QA](#qa) - [Cert](#cert) - [Content Pipeline & Source Control](#content-pipeline--source-control) - [Source Control](#source-control) - [Asset Pipeline](#asset-pipeline) - [Creator Suite Architecture](#creator-suite-architecture) - [Mission Editor](#mission-editor) - [Contract Author](#contract-author) - [RTS Map Editor](#rts-map-editor) - [2D Stage Editor](#2d-stage-editor) - [Cross-Cell Persistence & Operator XP](#cross-cell-persistence--operator-xp) - [Unified Operator Record](#unified-operator-record) - [XP Sync](#xp-sync) - [Launch Readiness](#launch-readiness) - [Cross-References](#cross-references) --- ## V4 Product Promise V4 ships as one coherent tactical-action game that delivers per-ruleset feel matching each of its 11 inspirational sources on its own terms, held together by one shared roster, one shared creator suite, and one shared online backbone. The architecture supports five gameplay cells (Tactical FPS, RTST, Action RPG, RTS, 2D Run-and-Gun) by: - Implementing each ruleset as a `GameFeatures` plugin layered on shared engine modules so cells can be enabled / disabled per platform, per build target, and per DLC. - Choosing a netcode strategy per cell — dedicated-server authoritative for tactical PvP and Battle Royale, deterministic lockstep for RTS, rollback-emulated prediction for tight twitch shooter PvP (TDM, Spies-vs- Mercs), and offline-deterministic for single-player and co-op campaigns. - Sharing one **AI Perception model** (`V4Perception`) across every NPC in every cell so a Hitman guard, a Commandos Wehrmacht patrol, a Splinter Cell mercenary, and a Wukong yaoguai all read stimuli from the same state machine. - Sharing one **roster** (operators, heroes, units) across cells via a unified Operator data table; cell-specific overrides (third-person mesh for Wukong, chibi sprite for Contra) hang off the operator record. - Holding all six launch cells together with one online backbone (matchmaking, parties, friends, replays, leaderboards, anti-cheat) and one creator suite (Mission Editor, Contract Author, RTS Map Editor, 2D Stage Editor). See `V4_features.md` § "V4 Product Promise" for the full list. ## Subsystem Glossary The names below are fixed vocabulary for V4; module names, namespaces, and asset paths inherit from them. **Engine modules** | Module | Responsibility | | -------------------- | -------------------------------------------------------------------- | | **V4Core** | Engine subsystems, save game, tags registry, dev cheats | | **V4Gameplay** | GAS abilities, attributes, gameplay effects, match-state machine | | **V4Tactical** | FPS aim, ADS, recoil, stance, lean, cover, weapon attachments | | **V4Stealth** | Light/shadow gauge, sound footprint, body-drag, disguise | | **V4Tactics** | RTST party, command queue, vision cones, time-stop, group order | | **V4ActionRPG** | Souls-like combat: stamina, parry, dodge, posture, transformations | | **V4RTS** | Resource economy, build orders, unit production, fog of war, tech | | **V4Arcade** | 2D side-scroll engine: scrolling rooms, weapon pickups, jump arcs | | **V4Perception** | Unified NPC sight/sound/suspicion model across all six launch cells | | **V4Crowd** | Hitman-style NPC crowds: density, body language, panic propagation | | **V4Schedules** | NPC daily routines, patrol graphs, intersect-with-player triggers | | **V4Animation** | AnimBP, motion matching, MetaHuman bind, IK, retargets, root motion | | **V4Input** | Enhanced Input, cover-stick, aim-assist curves, tac-map cursor | | **V4Netcode** | Client-server (default), deterministic lockstep (RTS), rollback PvP | | **V4Modes** | Game-mode registry, per-cell ruleset gating, mode-specific HUD | | **V4UI** | UMG / CommonUI front-end, tac-map, RTS HUD, contract briefings | | **V4Audio** | MetaSounds pipeline, dynamic music, voice barks, callouts, foley | | **V4VFX** | Niagara muzzle flash, blood decals, debris, weather, fog | | **V4Cinematics** | Sequencer-driven CoD setpieces, Wukong boss intros, ARPG finishers | | **V4Persistence** | Save game, profile, currency ledger, contract progress, replays | | **V4OnlineServices** | Login, friends, parties, matchmaking, leaderboards, replays | | **V4Telemetry** | Event schema, batched sender, balance dashboards feed | | **V4Editor** | Mission editor, contract author, RTS map editor, 2D level editor | | **V4Vehicles** | Helo insert, light vehicles, RTS unit-vehicle bridge | | **V4Procgen** | Roguelike layout generator for procedural-tactics campaigns | | **V4LevelOps** | NPC schedule authoring, environmental-kill graph, story script glue | | **V4Tests** | Automation specs, gauntlet drivers, golden-replay regression harness | **Game-feature plugins (modular, hot-swap)** | Plugin | Owns | | ------------------------------------- | ---------------------------------------------------------- | | **V4Mode_Tactical_RavenShield** | Planning phase, branching breach-and-clear missions | | **V4Mode_Tactical_R6Modern** | 5v5 attack/defense, operator gadgets, destruction | | **V4Mode_Tactical_CoDCampaign** | Linear cinematic campaign with set-pieces | | **V4Mode_Tactical_CoDMultiplayer** | 6v6 modes: TDM, S&D, Hardpoint, Domination, Kill Confirmed | | **V4Mode_Tactical_CoDWarzone** | 100-player battle royale tactical | | **V4Mode_Stealth_SplinterCell** | Linear stealth ops, light/shadow gauge, gadget loadouts | | **V4Mode_Stealth_SpiesVsMercs** | 2v2 asymmetric spies (3rd-person stealth) vs mercs (FPS) | | **V4Mode_Stealth_Hitman** | Sandbox levels, disguise system, NPC schedules, contracts | | **V4Mode_Stealth_ContractsAuthor** | Player-authored contracts (target/method/disguise) | | **V4Mode_RTST_Commandos** | WW2 6-character squad, vision cones, time-stop fallback | | **V4Mode_RTST_Desperados** | Wild-west 6-character squad, Showdown Mode (time-stop) | | **V4Mode_ARPG_Wukong** | Action RPG souls-like with transformations and spell-craft | | **V4Mode_ARPG_BossRush** | Curated boss-rush ladder, leaderboard, ghost replays | | **V4Mode_RTS_Asymmetric** | Three asymmetric factions, build orders, ladder | | **V4Mode_RTS_Historical** | Age-up historical RTS, civs, wonders, large pop battles | | **V4Mode_RTS_TowerDefense** | Co-op tower-defense variant on RTS maps | | **V4Mode_Arcade_Contra** | 2D side-scrolling run-and-gun, weapon pickups, 2P co-op | | **V4Mode_Arcade_BossGauntlet** | Arcade boss-rush mode with weekly leaderboard | | **V4Mode_SpecOps_Coop** | 1-4-player co-op missions, cross-cell loadouts | | **V4Mode_Roguelike_TacticalCampaign** | Procedural tactical campaign with operator perma-build | | **V4Mode_HordeDefense** | Wave-based defense across all six launch cells | | **V4Mode_Editor_Mission** | Mission editor (tactical, stealth, RTS, ARPG) | | **V4Mode_Editor_Workshop** | Workshop publishing, ratings, moderation | | **V4Mode_Replay** | Replay viewer, takeover, sharing | | **V4Mode_Spectator** | Network spectator + esports broadcast tools | | **V4Mode_Training_Range** | Weapon training, AI dummies, vision-cone calibration | | **V4Mode_Lobby_BattleHub** | Persistent lobby world (Battle Hub-equivalent) | ## High-Level Architecture V4's runtime is a single UE5.5 LTS project (`V4/ue/V4.uproject`) with all five cells loaded as `GameFeatures` plugins. The architecture stack from ground up: ```text ┌────────────────────────────────────────────────────────────────────┐ │ Cinematic AI Director AI Commentary Live Service Esports │ Tier 4 — Live & cinematic ├────────────────────────────────────────────────────────────────────┤ │ GameFeatures plugins (V4Mode_*) │ Tier 3 — Cells │ Tactical FPS │ RTST │ Action RPG │ RTS │ 2D Run-and-Gun │ ├────────────────────────────────────────────────────────────────────┤ │ V4Perception │ V4Crowd │ V4Schedules │ V4Vehicles │ V4Procgen │ Tier 2 — Shared cross-cell │ V4Tactical │ V4Stealth │ V4Tactics │ V4ActionRPG │ V4RTS │ V4Arcade│ ├────────────────────────────────────────────────────────────────────┤ │ V4Gameplay (GAS) │ V4Animation │ V4Input │ V4Netcode │ V4UI │ Tier 1 — Engine subsystems │ V4Audio │ V4VFX │ V4Cinematics │ V4Persistence │ V4Telemetry │ ├────────────────────────────────────────────────────────────────────┤ │ Unreal Engine 5.5 LTS (Lumen, Nanite, MetaHuman, Niagara, Chaos) │ Tier 0 — Engine └────────────────────────────────────────────────────────────────────┘ ``` Cross-cutting services live outside the client: - **V4 Online Services Backend** (Rust + Axum on Fly.io / GCP): login, matchmaking, leaderboards, replay-store, anti-cheat router, telemetry ingest, balance-ledger publication, Designer's Tier List, matchup winrate matrices, and Wukong public frame data. - **V4 performance polish manifests** live under `V4/perf/`: `engineering-polish.json` owns §117 gates, `pso-delta-report.json` tracks per-patch PSO changes, `mission-preload-profile.json` records per-cell mission-select preload timing, and `UV4ShaderWarmupSubsystem::BuildAdaptiveMissionPreloadQueue` exposes the AI Director-prioritized runtime queue. - **V4 AI Director post-launch refinement** lives in `DA_AIDirectorPostLaunchRefinement`: launch-window Tactical FPS skill percentiles and Wukong parry-success percentiles calibrate PvE difficulty only, rubber-banding candidates are rejected before application, and a compile-time PvP hook assertion keeps ranked and unranked PvP modes fixed. - **V4 Anti-Cheat Service** (kernel-mode client + cloud telemetry). - **V4 Spectator Portal** (Next.js web app). - **V4 Companion App** (React Native, including iOS / Android flat-surface AR replay projection for key tactical-FPS sequences). ## Project Layout ```text V4/ ├── ue/ UE5.5 LTS project │ ├── V4.uproject │ ├── Config/ │ │ ├── DefaultEngine.ini │ │ ├── DefaultGame.ini │ │ ├── DefaultInput.ini │ │ ├── DefaultGameplayTags.ini │ │ └── ... per-platform configs │ ├── Content/ │ │ ├── V4Core/ │ │ ├── V4Tactical/ │ │ ├── V4Stealth/ │ │ ├── V4Tactics/ │ │ ├── V4ActionRPG/ │ │ ├── V4RTS/ │ │ ├── V4Arcade/ │ │ ├── Operators/ Shared roster assets │ │ ├── Vehicles/ │ │ ├── Audio/ │ │ ├── Cinematics/ │ │ ├── UI/ │ │ ├── Localization/V4/ │ │ └── Tests/ │ ├── Source/ │ │ ├── V4/ Primary game module │ │ ├── V4Core/ │ │ ├── V4Gameplay/ │ │ ├── ... One directory per runtime module │ │ ├── V4Editor/ │ │ ├── V4Tests/ │ │ └── V4Server/ │ ├── Plugins/ GameFeatures + 3rd-party plugins │ │ ├── V4Mode_Tactical_RavenShield/ │ │ ├── V4Mode_Tactical_R6Modern/ │ │ ├── ... (one per game-feature plugin) │ │ └── V4Tools_AssetLinter/ │ ├── Build/ │ │ ├── Win64/ │ │ ├── PS5/ │ │ ├── XSX/ │ │ ├── Switch2/ │ │ ├── Mac/ │ │ ├── Linux/ │ │ └── iOS/ │ └── Saved/ Runtime artifacts (gitignored) ├── web/ Marketing site (Next.js) ├── services/ Cloud backend (Rust) │ ├── login-service/ │ ├── matchmaking-service/ │ ├── replay-service/ │ ├── leaderboard-service/ │ ├── anti-cheat-service/ │ ├── telemetry-ingest/ │ ├── balance-ledger/ │ ├── workshop-service/ │ ├── moderation-service/ │ └── shared/ ├── tools/ │ ├── esports/ Tournament toolkit │ ├── missions/ Mission authoring CLI │ ├── rts-maps/ RTS map authoring CLI │ ├── arcade-art/ 2D pixel-art tooling │ ├── balance/ Balance authoring (spreadsheets, scripts) │ └── release/ Build + distribute tooling ├── loc/ Localization workspace ├── docs/ Decisions, ADRs, runbooks │ └── decisions/ │ ├── phase-cut-*.md │ └── ... ├── balance/ Balance authoring spreadsheets ├── content-network/ SSO, public API, wiki, roadmap, push policy ├── release/ Release gates, final polish, sunset plan ├── roadmap/ Public roadmap and JIRA / Linear delivery sync ├── wiki/ Wiki seed data, world-state feeds, Sophia summaries ├── esports/pro-circuit/ Published pro-circuit calendar and tier data ├── ops/studio/ StudioOperations launch production, wellness baseline, and post-launch operations ├── ui/launch-experience/ Loading, splash, What's New, toast, push manifest ├── companion/ Companion app (React Native) ├── spectator/ Spectator portal (Next.js) ├── V4_features.md ├── V4_ARCHITECTURE.md ├── V4_DEPENDENCIES.md └── V4_TODOS.md ``` StudioOperations owns `ops/studio` launch production scheduling across mocap, VO, and composer cadence. PeopleOps co-owns the wellness controls there, including crunch prevention, mental-health resources, sensitivity-reading scope, DEI metrics, and escalation policy. Post-launch wellness operations extend that ownership with a quarterly crunch audit by an external reviewer, an on-staff mental-health counsellor, a remote counselling stipend, quarterly sensitivity-reading refreshes, published DEI hire/retention metrics with annual external audit, and an on-call rotation with mandatory comp time after on-call week. ## Module Split Engine modules under `V4/ue/Source//` are partitioned to make per-cell work isolatable and per-platform cooking efficient. The primary game module is the only module that lives under `V4/ue/Source/V4/`. - **Public/Private split:** Every module has a `Public/` header tree (used by other modules) and a `Private/` implementation tree (internal only). Cross-module includes follow the public surface; never reach into another module's `Private/`. - **Module dependencies:** documented in each `*.Build.cs`. The dependency graph is acyclic; the asset linter enforces this with a static check. - **Stripping by platform:** Switch 2 builds strip `V4Mode_Tactical_CoDWarzone` and `V4Mode_Tactical_R6Modern` (memory); mobile builds additionally strip `V4Mode_Tactical_CoDWarzone` (no 100-player Battle Royale on those targets at launch). Stripping is `.Target.cs` driven, not `#ifdef`. | Module | Depends on | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | V4Core | Engine, CoreUObject, InputCore, Slate, SlateCore | | V4Gameplay | V4Core, GameplayAbilities, GameplayTags, GameplayTasks | | V4Tactical | V4Core, V4Gameplay, V4Animation, V4Input, EnhancedInput | | V4Stealth | V4Core, V4Gameplay, V4Perception | | V4Tactics | V4Core, V4Gameplay, V4Perception, V4Schedules | | V4ActionRPG | V4Core, V4Gameplay, V4Animation | | V4RTS | V4Core, V4Gameplay, V4Netcode | | V4Arcade | V4Core, V4Gameplay, V4Animation, Paper2D | | V4Perception | V4Core, AIModule, NavigationSystem | | V4Crowd | V4Core, V4Perception, MassEntity, MassNavigation, MassAIBehavior, MassMovement, MassReplication, MassSignals | | V4Schedules | V4Core, V4Crowd, V4Perception | | V4Animation | V4Core, AnimGraphRuntime, PoseSearch, Mover, Chooser | | V4Input | V4Core, EnhancedInput | | V4Netcode | V4Core, NetworkPrediction, Iris | | V4Modes | V4Core, V4Gameplay, ModularGameplay | | V4UI | V4Core, UMG, CommonUI, ModelViewViewModel | | V4Audio | V4Core, MetasoundEngine, AudioModulation, AudioGameplayVolume | | V4VFX | V4Core, Niagara | | V4Cinematics | V4Core, MovieScene, Sequencer, MovieRenderPipelineCore | | V4Persistence | V4Core, Serialization | | V4OnlineServices | V4Core, OnlineSubsystem, OnlineServicesInterface, OnlineServicesCommon, EOSShared | | V4Telemetry | V4Core, HTTP | | V4Vehicles | V4Core, V4Gameplay, ChaosVehicles | | V4Procgen | V4Core, PCG (UE Procedural Content Generation) | | V4LevelOps | V4Core, V4Schedules | | V4Tests | V4Core, Gauntlet, FunctionalTesting | | V4Editor | V4Core, UnrealEd, EditorSubsystem, EditorScriptingUtilities, ToolMenus | `V4Vehicles` also owns the P3 sports vehicle registry. `DA_SportsVehicleModes` links `DT_SportsVehicleMode` and arena sidecars, while `UV4SportsVehicleModeCatalog` exposes runtime validation for vehicle soccer, vehicle stunt, crash mode, and the Trackmania-style time-trial contract. ## Gameplay Ability System (GAS) Layout GAS is V4's spine for combat, abilities, attributes, and effects. The architecture pattern matches V2's: a single `UAbilitySystemComponent` (ASC) per character, attributes per cell-specific stat block, ability classes per verb. ### Attribute Sets Per-cell attribute sets (mutually exclusive at run-time — a character is either in a Tactical match or an ARPG fight, never both): - **V4Attr_Tactical** — Health, Armor, Suppression, StaminaSprint, AmmoCurrent, AmmoReserve. - **V4Attr_Stealth** — Health, Detection, DisguiseClass, Noise. - **V4Attr_Tactics** — Health, ActionPoints, Vision. - **V4Attr_ARPG** — Health, Stamina, Posture, Will, Mana. - **V4Attr_RTS** — UnitHealth, UnitArmor, UnitAttack, UnitRange, UnitMovementSpeed, UnitSightRange. - **V4Attr_Arcade** — Health (1 by default), Lives, ScoreMultiplier. ### Ability Classes GameplayAbility blueprints implement the verb library per cell: - **Tactical:** GA_Fire, GA_Reload, GA_ADS, GA_Lean, GA_ThrowGrenade, GA_BreachStack, GA_Revive, GA_Heal. - **Stealth:** GA_Crouch, GA_BodyDrag, GA_LightKill (lights-out shot), GA_StickyCam, GA_MarkAndExecute, GA_Disguise. - **Tactics:** GA_PlanQueueWaypoint, GA_FireQueued, GA_ShowdownToggle. - **ARPG:** GA_LightAttack, GA_HeavyAttack, GA_Dodge, GA_Parry, GA_Transform, GA_CastCharm. - **RTS:** GA_BuildStructure, GA_TrainUnit, GA_ResearchTech, GA_AttackMove. - **Arcade:** GA_Shoot, GA_Jump, GA_DropPlatform. ### GameplayTags Tags are registered in `Config/DefaultGameplayTags.ini` and split per cell: - `Tactical.*` — `Tactical.State.Stance.Stand`, `Tactical.Cover.Left`. - `Stealth.*` — `Stealth.Detection.Hidden`, `Stealth.Disguise.Waiter`. - `Tactics.*` — `Tactics.Order.Move`, `Tactics.Order.Attack`. - `ARPG.*` — `ARPG.Combat.Parry.Window`, `ARPG.Form.Tiger`. - `RTS.*` — `RTS.Faction.Vanguard`, `RTS.Tech.Tier2`. - `Arcade.*` — `Arcade.Weapon.Spread`, `Arcade.PowerUp.Active`. - `Operator.*` — `Operator.Name.Cobra`, `Operator.Faction.SpecOps`. ### Effect Stacking Stacking rules per attribute follow Unreal's GameplayEffect aggregation: - Health restore stacks additively to a max-clamp. - Damage is applied as an instant effect with mitigation by armor. - Suppression decays over 2 s without further hits. - ARPG Posture damage is non-mitigable but decays over 3 s without further hits. - RTS unit damage is instant and additive (no decay). ## Animation Pipeline V4 uses UE5's modern animation stack: AnimBlueprints, Motion Matching, Mover 2.0, IK retargeting via IKRig, and MetaHuman animation pipeline for principals. ### AnimBlueprint Layout - **ABP_Operator_Master** — base AnimBP for all bipedal humans. Sub-states per cell-specific verb (cover lean, ADS, crouch, prone, body drag). - **ABP_RTSUnit_Master** — RTS-unit AnimBP with per-faction overrides. - **ABP_RTST_Specialist_Master** — RTST specialist AnimBP with squad-pose layered slots. - **ABP_ARPGHero_Master** — Wukong-class AnimBP with combo state machine, parry/dodge slot, transformation morph. - **ABP_NPC_Civilian** — Hitman / Commandos civilian AnimBP with idle, panic, drop-and-cover, run. - **ABP_2DOperator** — Paper2D flipbook controller for Contra. ### Motion Matching - **Motion Matching dataset** per cell for traversal-heavy areas (Hitman sandbox, Wukong open areas). Tactical FPS and RTS use the standard root-motion AnimBP. - **Pose history buffer** depth: 8 frames. - **Trajectory length:** 600 ms. - **Distance field cost** factors: stance, velocity, acceleration, facing. ### IK Retargeting - **Single IKRig** per body archetype (Adult Male, Adult Female, Adolescent, Animal Quadruped, Animal Biped). - **Operators** retarget to/from MetaHuman skeleton via the IKRig system. - **No per-operator skeleton** — costume / cosmetic differences ride on top of one shared skeleton per body archetype. ### MetaHuman Pipeline - **MetaHuman Creator** for principal characters. - **MetaHuman Animator** for facial mocap. - **Live Link Face** for performance capture. - **Lip sync** via OVR Lip Sync or MetaSounds' lip-sync metadata. ## Input Pipeline `EnhancedInput` is the canonical input system. V4 abstracts input through Input Mapping Contexts (IMCs) per cell: - **IMC_Tactical** — FPS controls (mouse + WASD, gamepad twin-stick). - **IMC_Stealth** — adds body-drag, light-out, sticky-cam. - **IMC_Tactics** — top-down cursor + waypoint placement. - **IMC_ARPG** — third-person action with target-lock. - **IMC_RTS** — top-down cursor + box-select + hotkey grid. - **IMC_Arcade** — 8-direction stick + jump + shoot. - **IMC_UI** — menu navigation. Switching cells mid-session pushes/pops IMCs. The input router lives in `V4Input::FInputRouter`. ### Input Actions Per IMC, named input actions trigger GAS abilities via `GA.Activation.Tag`: - `IA_Fire` → `GA.Tactical.Fire` - `IA_PlanWaypoint` → `GA.Tactics.PlanQueueWaypoint` - `IA_Parry` → `GA.ARPG.Parry` ### Motion Inputs (Fighting-game-like) For the ARPG cell, advanced combos use motion inputs (DPad → Punch, etc.) parsed by `V4Input::FMotionParser`. The parser is reused from V2 (the fighting-game project's motion parser), generalized to read directional inputs over a 16-frame window with charge / partial-circle / half-circle / full-circle / motion-charge patterns. ### Cover-Stick In tactical FPS, left-stick scoots between cover anchors when in cover mode; this is implemented as an input-modifier on `IA_Move`. The cover anchor graph is authored per map. ### Tac-Map Cursor In the Raven Shield planning step, the mouse drives a cursor over the top-down floor plan. Cursor logic lives in `V4Tactics::FPlanCursor` and is shared by both the planning step and the RTST cone-authoring tool. ### Hardware Peripheral Deep Profiles `V4/peripherals/hardware-peripherals-deep.json` and `DA_HardwarePeripheralDeepProfiles` layer post-launch fidelity on top of the launch peripheral profile: - `DA_DualSenseWeaponTriggerCurves` generates one adaptive-trigger curve per `DT_Weapon` row from recoil-curve metadata and adds Stealth heartbeat, ARPG parry tick, and RTS distant-battle haptic patterns. - `DA_XboxImpulseWeaponPatterns` mirrors the per-weapon class data to Xbox impulse triggers so Series controllers stay aligned with DualSense tuning. - `DA_WheelCalibrationProfiles` stores Logitech, Thrustmaster, Fanatec, and Moza brand calibration profiles. `WBP_ForceFeedbackCurveEditor` and `DA_ForceFeedbackCurveEditor` expose editable strength curves from Settings. - `IMC_HOTAS_HeloDoorGunner` adds the helo door-gunner HOTAS profile on top of the launch aerial setpiece context. - `DA_AdaptiveControllerPresets` provides Xbox Adaptive Controller presets plus the `IMC_AdaptiveController_TacticalSingleStick` tactical-FPS variant. - `DA_EyeTrackingInputAssist` wires Tobii PC and PS5 Pro providers for camera-aim assist and gaze-based UI focus through `IMC_GazeFocus_UI`. ## AI Perception, NPC Schedules, Crowd The unified perception model is one of V4's defining cross-cell systems. This subsystem must serve a Hitman waiter, a Commandos patrol, a Splinter Cell merc, and a Wukong yaoguai with consistent semantics. ### V4Perception Module - **Senses:** Sight, Hearing, Damage, Touch, Faction-Stimulus (alarm triggers, body found), Disguise-Check. - **Sense data:** Each sense produces a `FStimulusEvent` with timestamp, source actor, location, magnitude. - **Perception component:** `UV4PerceptionComponent` (extends UE's AI Perception with V4-specific stimuli). Attached to every hostile NPC. - **Awareness state:** `FAwarenessState { Level (Calm/Curious/Alert/Hostile), TargetActor, LastSeenLocation, SuspicionGauge (0-1.0), TimeInStateSeconds }`. - **Stimuli pipeline:** Stimuli enter via `RegisterStimulus`; the `PerceptionEvaluator` ticks at 10 Hz (adjustable per AI density; background NPCs at 2 Hz) and updates the awareness state machine. - **Propagation:** When an NPC transitions to Alert or Hostile, it emits a `Faction-Stimulus.AlertPropagation` event to allies within a radius (configurable; default 4 m). - **Cooldowns:** Suspicion decay rate, alert decay rate, hostile decay rate all configurable per NPC class. ### V4Schedules Module - **Schedule asset:** `UV4ScheduleAsset` is a Sequencer-style timeline of schedule nodes (waypoint + task + duration), serialized as `.uasset` with editor authoring widget. - **Schedule runtime:** `UV4ScheduleComponent` ticks each NPC's schedule; computes next waypoint, time-to-next-step, current task verb. - **Task verbs:** WalkTo, StandIdle, SitOnBench, DrinkAtBar, TalkToNPC, UseToilet, PatrolLoop, SmokeCigarette, Pray, PoseForPhoto, etc. - **Hooks:** Schedule nodes can fire and respond to events; e.g., a schedule node can transition to a new branch when a player picks up a planted phone. - **Determinism:** Schedule clock is server-authoritative; clients lerp to server's schedule index every 1 s. ### V4Crowd Module - **Mass Entity** integration: V4Crowd uses UE5's Mass Entity framework for dense (200+) NPC populations in Hitman sandboxes and Commandos / Desperados maps. - **Tiers:** Background (LOD path-following only, no perception), Medium (LOD perception with cheap stimuli), Hero (full perception, full schedule). - **Tier transitions:** Distance from player + relevance heuristic; a Hero NPC reverts to Medium when player is >50 m away. - **Panic propagation:** A `Panic` stimulus spreads at 4 m/s through the crowd graph; affected NPCs run to nearest exfil node. - **Disguise check:** Crowd subsystem checks `Player.DisguiseClass` against each NPC's disguise class on `LineOfSight` events; if same, the NPC is flagged Enforcer and treated with reduced detection time. ### Performance Budget - **Crowd cost:** ≤ 8 ms/frame on PS5 / XSX for 400 NPC Hitman map. - **Perception cost:** ≤ 1.5 ms/frame for 20 Hero-tier perception NPCs (the full-perception tier). The remaining crowd runs on Medium / Background tiers, whose cheap stimuli are accounted for in the crowd cost. - **Schedule cost:** ≤ 0.6 ms/frame for 400 NPC Hitman map (cheap schedule ticks). ## Vision Cones, Suspicion, Stealth Gauges The cross-cell stealth vocabulary, shared by Splinter Cell, Hitman, Commandos, Desperados, Wukong (stealth-approach moments), and any tactical FPS NPC. ### Vision Cone Authoring - **Cone struct:** `FVisionCone { Forward, HalfAngle (rad), Range (m), Color, LowLightFalloff }`. - **Per-NPC default:** Forward = mesh forward, HalfAngle = 60°, Range = 12 m. Tunable per NPC class. - **Rendering:** - Top-down cells (RTST): cone rendered as floor decal (color-coded by alert level: green / yellow / red). - First-person cells (Tactical FPS, Hitman, Splinter Cell): cone is invisible (information comes from animation tells, NPC barks). - **Authoring tool:** `V4Editor::FConeAuthoringWidget` lets level designers preview cone over the map and per-NPC stance. ### Suspicion Gauge - **Range:** 0.0 (calm) to 1.0 (hostile). - **Inputs:** Sight (modulated by lux for stealth cells), Hearing, Damage, AlarmTrigger, BodyFound. - **Per-stimulus weight:** Configurable per NPC class. - **Decay:** Linear decay over 8 s if no further stimulus and no line of sight. ### Light/Shadow Gauge (Splinter Cell) - **Lux sample:** At player capsule center each frame, sample world lux via a small Volumetric Lightmap query. - **Bow-tie indicator:** HUD widget shows three states — Lit (red), Dim (yellow), Dark (green). - **Detection gating:** In Splinter Cell-cell missions, NPCs cannot detect player by sight unless player is Lit or within 1.5 m line of sight (regardless of dark). - **Light-out:** Shooting a light bulb (one shot, glass-break sound) transitions an area's bulb from on to off, which shifts the local lux query. ### Sound Footprint - **Sound emission radius:** Configurable per stance and surface; see `V4Stealth::FSoundFootprint`. - **Walk surface tags:** `Surface.Floor.Tile`, `Surface.Floor.Carpet`, `Surface.Floor.Gravel`, etc., authored on per-collision materials. - **Hearing range query:** NPC hearing check is a sphere query at the player's sound emission center with radius `SoundFootprintRadius`. ## Per-Cell Architecture Deep-Dives The cross-cell engine modules cover most of V4's runtime, but four cells each need a cell-specific subsystem with no cross-cell analogue. Those four deep-dives are collected here, adjacent to the shared gameplay cluster they extend. ### 2D Engine (Contra Cell) The Contra cell uses UE5's Paper2D + custom additions for the run-and-gun aesthetic. #### Paper2D - **Flipbook authoring** for character animations. - **TileMap** for stages. - **2D collision** with capsule shapes. #### Niagara for 2D - **2D projectiles** rendered as Niagara sprites with custom shader. - **Particle effects** for explosions, hit feedback. #### Side-Scroll Camera - **Camera follows player** with screen-edge clamping. - **Co-op tether:** When 2 players, camera follows midpoint with configurable separation cap. - **Parallax background** via custom material. ### Action RPG Combat Architecture The Wukong cell's combat system. #### Combat State Machine - **States:** Neutral, Attacking, Dodging, Parrying, Stunned, Transformed, Casting, Damaged. - **Transitions:** Frame-perfect via GAS ability cancels. #### Frame Data - **Per-attack frame data:** Startup, Active, Recovery, Cancellable Window. Public via Codex. - **Parry window:** 6 frames (parry-ready) on heavy attacks; some attacks are unparriable (super-armor frames). - **Dodge i-frames:** 9 frames on roll. #### Posture System - **Posture meter** per enemy, separate from health. - **Posture damage** from heavy attacks, parries, perfect-dodge punishes. - **Posture break:** Triggers cinematic counter (~80 HP critical hit). `DA_SpecialtyCombatModes` and `DT_SpecialtyCombatMode` extend this backbone into P3 duel rules. `UV4SpecialtyCombatModeCatalog` validates the UFC-style boxing simulator against stamina/posture/parry scorecards and the one-hit-kill sword duel against normalized weapons, lethal-hit confirmation, consent gating, and tight perfect-guard timing. #### Transformation System - **Form data table:** Per-form moveset, HP pool, duration, Will cost. - **Form-specific AnimBP:** Loaded on transform. - **Will charge:** Up to 3, refilled by parries and posture breaks. ### Disguise System Architecture Shared between Hitman and Commandos / Desperados (Spy class). #### Disguise Data - **DT_DisguiseClass:** Per-map disguise classes; each entry has class ID, allowed zones, suspicious actions, Enforcer NPCs. - **Player state:** `V4Stealth::FDisguiseState { ClassId, Stealthiness, Worn (bool) }`. #### Disguise Pickup - **Source:** Knocked-out / killed NPC, dragged into a "private" zone (closet, dumpster, etc.). - **Animation:** 2-second body swap. #### Enforcer Check - **NPC perception extension:** Each NPC has `DisguiseEnforcerClass` field; if `Player.DisguiseClass == NPC.DisguiseEnforcerClass`, the NPC's vision range to detect Player is reduced (closer detection, but faster). #### Zone Restriction - **Per-disguise allowed zones:** Configurable per map. Restricted zone + non-matching disguise triggers suspicion. ### Showdown Mode Architecture Defining the Desperados cell. #### Time-Dilation - **World time-scale:** 0.125× (1/8 speed). NPCs still move and observe but at heavily reduced rate — Showdown slows time, it does not stop it. - **UI time-scale:** 1.0×. Player UI runs at normal speed; planning is smooth. - **Audio:** Music + ambience pitch-shift; foley silenced; UI sounds normal. #### Action Queue - **Per-specialist queue:** Up to 2 actions per specialist; queued via click-target-while-Showdown. - **Queue UI:** Color-coded per specialist; ordering visible on map. - **Pre-fire validation:** Each queued action validates targetability (NPC in cone, line of sight, item in inventory). #### Synchronous Trigger - **Release Showdown:** All queued actions fire in dependency-resolved order. - **Resolution speed:** All queued actions resolve within 1 s of real time. - **Replay:** Showdown sequence recorded as a sub-replay. ## Networking, Authority & Determinism V4 chooses a netcode strategy per cell. The four sections below cover combat authority, the RTS deterministic-lockstep model, the client-server stack for tactical PvP and Battle Royale, and the rollback-emulated prediction layer for twitch PvP. ### Combat Authority & Determinism V4's combat authority is **server-authoritative** for all networked modes. Determinism is mode-specific: - **RTS:** Deterministic lockstep — all clients execute the same input stream in the same order; no game state replication, only inputs. - **Tactical FPS PvP:** Client-server with prediction and reconciliation; hit-validation is server-authoritative. - **Tight twitch shooter PvP (TDM, S&D, Spies-vs-Mercs):** Client-server with rollback-emulated prediction — clients predict locally with reversible state; server reconciles against authoritative hit-reg. - **Battle Royale:** Client-server with relevancy band replication; hit-reg authoritative. - **Single-player and co-op (PvE):** Local deterministic; saves and replays are seedable. - **ARPG, RTST, 2D:** Local deterministic (PvE only); replays serializable. #### Hit-Reg - **Per-shot trace:** Server-authoritative line/cone trace at shot frame. - **Client lag compensation:** Server rewinds opponent positions to client's observed frame (Source-engine-style); clamp at 300 ms. - **Anti-cheat hook:** Server validates trace direction is plausible given gun pose; impossible angles get flagged. #### RTS Lockstep Cross-Reference The deterministic lockstep model is detailed in the RTS Deterministic Lockstep section below. ### RTS Deterministic Lockstep The RTS cell uses deterministic lockstep networking, which is the proven model for high-unit-count RTS (200-pop AoE matches, 100-unit StarCraft matches). #### Lockstep Frame - **Tick rate:** 25 Hz (40 ms per simulation tick), with a 1-tick presentation interpolation buffer. - **Frame budget:** 5 ms server / 5 ms client per tick. - **Input collection:** Each client collects local player input, serializes to a compact diff (`FRTSInputDelta`), and sends to the server. - **Input broadcast:** Server collects all clients' input deltas for tick N, broadcasts the bundle. Clients hold simulation until the bundle is received. - **Simulation:** All clients run the same simulation deterministically given the input bundle. #### Determinism Guarantees - **Fixed-point math** for unit positions (32.32 fixed) — no floating-point. - **Deterministic RNG** seeded per match; consumed in canonical order. - **No floating-point pathfinding** — A\* with fixed-point heuristics. - **No hardware-dependent operations** in simulation (no GPU compute, no non-deterministic memory iteration). - **Hash check:** Every 100 ticks, each client hashes its full simulation state and compares to peers; mismatch triggers desync recovery. #### Desync Recovery - **Detection:** Mismatching state hash within 1 tick of detection. - **Recovery:** Late-joiner rebuild — desynced client pauses, requests authoritative snapshot from server, replays input bundles since snapshot, resumes. - **Pause threshold:** If any client desyncs, all clients pause for ≤ 3 s while recovery completes. If recovery exceeds 3 s, the match is flagged for replay-loss recovery. #### Replay - **Format:** Input bundle stream + initial random seed + match config. - **Playback:** Replay player runs the same lockstep simulation in fast-forward / pause / rewind mode. - **Size:** ~1 MB per 30-minute RTS match (input-only is compact). ### Local Multiplayer & LAN `UV4LocalMultiplayerPolicyLibrary` defines the launch local-play matrix used by mode routing and asset metadata: - **2P console split:** Tactical Co-op, Wukong Two-Tail, and Contra Co-op. - **4P console split:** RTS Team Skirmish and Spec Ops Co-op. - **Contra couch gate:** Contra's co-op model validates mandatory 2P local couch play with screen-edge tethering before launch. - **RTST hot-seat:** Shared-keyboard alternation assigns `Keyboard.Primary` exclusively to the active specialist turn. - **RTS LAN:** `RTS.LANSkirmish` advertises over LAN broadcast with no backend dependency and uses the same 25 Hz deterministic lockstep stream as online RTS. ### Spec Ops Online Co-op `UV4SpecOpsOnlineCoopModel` owns the Year-1 Spec Ops online variants while `UV4SessionSubsystem` enforces the host-authoritative session contract: - **Marathon:** A single continuous run of all 18 Spec Ops missions with a persistent timer, configurable difficulty floor, and `SpecOps.Marathon.CrossPlayer` team leaderboard. - **Endurance:** Endless Spec Ops waves with escalating enemy scalar and a diminishing ammo / heal-flask economy across waves. - **Weekly ops:** `DA_SpecOpsPostLaunchOps` is linked from `DA_SpecOpsOnlineCoop`; `BuildWeeklyFeaturedContractSlate`, `BuildModifierDeck`, and `SelectModifierStackAtMissionStart` provide the weekly featured contract slate, authored modifier deck, and deterministic mission-start modifier stack. - **Cross-cell crossover:** `SpecOps.Crossover.TempleBreach` pairs a tactical FPS player and a Wukong-cell player in the same Spec Ops room. - **Drop-in / drop-out:** Guests can leave and rejoin open Spec Ops sessions; the original host remains authoritative and host migration is disabled. `UV4HordeVariantCatalog` keeps six launch Horde Defense variants in `BuildLaunchVariants` and layers post-launch crossover content through `BuildPostLaunchVariants`. The first post-launch row, `Horde.TacticalRTSTBaseDefense`, uses Tactical as the playable fireteam cell and Tactics as the authored RTST-base cell, with `ValidatePostLaunchContent` guarding the cross-cell/base-defense flags. ### Client-Server Netcode (Tactical PvP, Battle Royale) For tactical FPS PvP and Battle Royale, V4 uses UE's standard client-server replication with custom relevancy bands. #### Server Topology - **Dedicated servers** in 10 regions: NA-East, NA-West, EU-West, EU-East, LATAM, APAC, AU/NZ, ME, Africa, India. - **Match capacity:** 10 players (R6 5v5), 12 players (CoD 6v6), 100 players (BR), 4 players (Spies vs Mercs). - **Host-migration:** Not used (dedicated only); fallback for private rooms only. #### Replication Graph For Battle Royale, UE5 `ReplicationGraph` partitions the 9 km² map into: - **Band A — local 200 m radius:** Full replication of all dynamic actors. - **Band B — 200–500 m:** Players only, no projectiles, no environmental effects. - **Band C — 500–1500 m:** Player position pings only. - **Band D — > 1500 m:** No replication. Year-1 Battle Royale tactical extensions stay inside the `V4Mode_Tactical_CoDWarzone` plugin. `UV4CoDWarzoneMapCatalog` owns the Delta Frontier second-biome map shift and seasonal map rotation, `UV4CoDWarzoneVehicleCatalog` adds boat, jet-ski, light tank, and 4x4 buggy drivable rows, and `UV4CoDWarzoneLootCatalog` enforces the one-per-match Mythic loot tier with guaranteed Legendary loot plus tracker buff. Operator-specific BR finisher animations are authored under the plugin animation root and indexed by `DT_BRFinisher_CoDWarzone`. P3 Battle Royale variant deep dives stay in the same plugin through `DA_CoDWarzoneVariantDeepDives`. `UV4CoDWarzoneMapCatalog` publishes the Resurgence-specific maps Resurgence Island, Signal Fortress, and Storm Pier with timer respawns, redeploy beacons, hot-drop POIs, and squad-wipe lockouts. `UV4CoDWarzonePlunderEconomyCatalog` owns `DT_PlunderEconomy_CoDWarzone`, including the $1M target, death-cash drop, deposit helipad / balloon / bank truck loops, contract payouts, cash bundles, and overtime multiplier. P3 Battle Royale Year-2+ stretch systems are linked through `DA_CoDWarzoneYear2Extensions`: `DT_LTM_CoDWarzone` owns the 14-day limited-time mode rotation, `DT_PermadeathSeason_CoDWarzone` gates opt-in account-persistent losses, and `DT_RTSBRHybrid_CoDWarzone` defines `BR.RTSHybrid.CommanderEconomy`, where one RTS commander spends the asymmetric RTS economy into loot drops for BR squads. #### Iris (UE5.5) UE5.5's Iris networking replaces the legacy net layer for V4's non-rollback channels. Iris's tagged-state replication reduces bandwidth ~30% compared to legacy. #### Bandwidth Budget - **Tactical 5v5:** 32 KB/s per client. - **CoD 6v6:** 38 KB/s per client. - **Battle Royale 100:** 72 KB/s per client (peak), 25 KB/s avg. - **Spies vs Mercs 2v2:** 28 KB/s per client. ### Rollback-Emulated Prediction (Twitch PvP) For TDM, S&D, and Spies-vs-Mercs, V4 applies rollback-emulated client prediction on top of the standard client-server stack. This is not full rollback like V2's fighting-game netcode; it's prediction-with-confirm. - **Prediction window:** 8 frames (133 ms at 60 Hz) for inputs that affect movement / firing. - **Reconciliation:** Server confirms inputs and any rewinds happen via state replay. - **Player visibility:** Other players are interpolated to lag-compensated server positions; local pawn is predicted. ## Game Modes (GameFeatures Plugins) Each cell's modes are packaged as GameFeatures plugins (see Subsystem Glossary table). The benefit: - **Per-platform stripping:** Switch 2 builds strip `V4Mode_Tactical_CoDWarzone` and `V4Mode_Tactical_R6Modern` (memory). - **DLC gating:** Post-launch operator DLC ships as a GameFeature plugin that depends on `V4Mode_Tactical_R6Modern`'s GameFeature plugin. - **Hot-load:** GameFeatures can be activated / deactivated at runtime (e.g., between matches in a quick-play playlist). Each plugin's `*.uplugin` declares: - Required engine modules. - Required other plugins (e.g., `V4Mode_Stealth_Hitman` requires `V4Mode_Stealth_ContractsAuthor`). - Asset roots (`Content/V4Mode_*/`). - Localization namespace. - Asset linter scope (per-plugin lint rules). ### Mode-State Machine The `UV4ModeSubsystem` owns the high-level state: ```text MainMenu → ModeSelect → LobbyJoin → MatchSetup → MatchPlay → MatchResult → MainMenu ↓ ↓ QuickJoin Resume / Forfeit / Disconnect ``` Per-mode plugins can override transitions (e.g., RTS adds Pause state; Hitman adds Mid-Mission-Save state). ## Sandbox Streaming (World Partition + Crowd) Hitman / Commandos / Desperados sandboxes are large maps with dense NPC populations and detailed interior detail. V4 uses **World Partition** to stream cells dynamically. ### World Partition - **Cell size:** 100 m × 100 m default; finer (50 m) for high-detail interior maps (Hitman). - **Streaming distance:** Always-loaded cells around player + neighbor cells (3 × 3 ring at 100 m, so 9 cells = 90,000 m² (300 m × 300 m) streamed). - **HLOD (Hierarchical LOD):** Pre-built for distant cells (>3 cells out). ### Streaming + Crowd - **NPC streaming:** Mass Entity hub keeps NPC population aware of player's cell; NPCs outside the streamed cells are demoted to Background tier (cheap state-only). - **Schedule streaming:** Schedules tick only for NPCs in Medium / Hero tier; Background tier interpolates schedule position. ### Asset Memory - **VRAM budget:** ≤ 6 GB on PS5, ≤ 4 GB on XSS, ≤ 8 GB on PC ultra. - **Streaming GB/s:** Target 1.5 GB/s (PS5 SSD compressed) read. ## Procedural Generation Pipeline `V4Procgen` powers roguelike-tactics campaigns and daily-mission seeds. Built on UE5's PCG framework. ### PCG Graphs - **Per-cell PCG graph:** `PCG_Tactical`, `PCG_Stealth`, `PCG_RTST`, `PCG_ARPG`, `PCG_2D`. - **Chunk-based:** Maps assemble from authored chunks (rooms, hallways, buildings, terrain tiles). - **Constraints:** Per-mission seed + per-archetype tag list; layout must satisfy reach-from-spawn-to-exfil constraint. ### Validation - **Playability test:** Bot path-finder validates spawn → all objectives → exfil; mission rejects if unreachable. - **NPC placement test:** Crowd / schedule placer validates that every named NPC has a valid spawn (not in a wall, has a schedule cycle). - **Determinism:** Seed → identical layout; community shares seeds. ### Daily Mission - **Server-generated seed** broadcast at 00:00 UTC. - **Client downloads** the recipe (chunk list + NPC list + objective list); the assembly runs locally. - **Leaderboard:** Per-day leaderboard. - **P3 roguelike adventure:** `DA_RoguelikeAdventureMode` links `DT_Roguelike_MetaProgression`, `DT_Roguelike_BossRoster`, and `DT_Roguelike_Boons`. Runtime state is carried by `FV4RoguelikeMetaProgressionState`; `UV4RoguelikeTacticalRunBuilder` banks Shadow Intel at run end, spends it on persistent tracks, validates the 12-boss roster, and grants boss-reward boons inside the current run. ## Persistence & Profile `V4Persistence` owns save-game, profile, currency ledger, contract progress, replay storage. ### Save Game - **Profile save:** Cosmetics, operator XP, account XP, settings, preferences. Stored locally + cloud sync. - **Campaign save:** Per-cell campaign progress; per-mission checkpoints. Cloud-synced via OnlineServices SaveGame. - **Quick save / load:** RTS skirmish, ARPG runs allow quick-save (PvE only). - **Auto-save:** Every 60 s in PvE, on chapter transition in cinematic campaigns. ### Currency Ledger - **Soft currency (Operator Tokens):** Earned in-game; cross-platform. - **Hard currency (Combat Points):** Purchased; per-platform per store rules. - **Premium currency (Elite Tokens):** Earned through ranked play; cosmetic only. - **Ledger entry:** Every transaction has a server-validated entry with source, amount, balance after, timestamp. ### Cosmetic Inventory - **Operator skins, weapon skins, charms, banner cards, calling cards, emotes, stickers, badges, sprays.** - **Cross-platform persistence** via account link. ### Persistent World Economy - **Seasonal state asset:** `DA_PersistentWorldEconomySeasonalState` extends the Hitman launch persistent world with all-map seasonal kill rollups, most-targeted NPC rankings, and read-only publication fields for the wiki. - **Schedule churn:** `DA_HitmanSeasonalScheduleRotations` keeps the same TargetA/TargetB/Handler/SecurityChief/Chef/Doctor/VIPGuest/Mechanic NPC ids across seasons while swapping quarterly routine ids, with public patch notes in `V4/stealth/hitman/schedule-rotation-patch-notes.md`. - **Cross-cell hooks:** `DA_WorldStateCrossoverHooks` maps authored Hitman assassination events to campaign branch flags such as `CoD.BlackoutLedger.AssassinationConfirmed`. Hooks are resolved before mission load so live telemetry never changes deterministic combat simulation. - **Wiki feed:** `V4/wiki/world-state-feed.json` and `/api/public/wiki/world-state` expose season id, total kills, top map, most-targeted NPC, active schedule variants, and unlocked narrative branches as read-only wiki data. - **Ripple manifest:** `DA_PersistentWorldEconomyDeep` extends the seasonal state with `DT_WorldStateRippleEvent`, `DT_PlayerDrivenWorldEvent`, and `DT_FactionBalanceArc`. The manifest at `V4/wiki/world-state-ripple.json` and `/api/public/wiki/world-state-ripple` publishes Hitman-to-CoD objective changes, RTS-to-Wukong lore lifts, companion app event state, and the multi-season faction-balance arc. - **World-boss community raid:** `DA_WorldBossCommunityRaid`, `DT_WorldBossRaidEvent`, and `DT_CommunityRaidProgressEvent` extend `UV4HitmanPersistentWorldSubsystem` with `BuildSeasonalWorldBossRaids`, `BuildCommunityRaidProgressEvents`, and `RecordCommunityRaidContribution`. The read-only wiki ripple feed publishes the Eclipse Leviathan seasonal raid and async community progress without player-scoped state. ## Online Services Backend Backend services live under `apps/v4/` and run on the cloud (default: GCP Cloud Run + Fly.io edge for low-latency). ### Service Inventory | Service | Lang | Purpose | | ----------------------------- | ----------- | ------------------------------------------------------ | | **login-service** | Rust + Axum | Account login, SSO, token issue, platform link | | **matchmaking-service** | Rust + Axum | Skill-based matchmaking, queue, ticket issue | | **session-service** | Rust + Axum | Match session creation, dedicated-server allocation | | **replay-service** | Rust + Axum | Replay storage, retrieval, public sharing | | **leaderboard-service** | Rust + Axum | Per-mode / per-cell / per-region leaderboards | | **anti-cheat-service** | Rust + Axum | Cheat report routing, ban issuance, appeal portal | | **telemetry-ingest** | Rust + Axum | Event ingest, batched write to ClickHouse | | **balance-ledger** | Rust + Axum | Public balance ledger and `balance-operations.json` | | **wiki-service** | Rust + Axum | Community wiki, moderation, high-traffic protection | | **workshop-service** | Rust + Axum | Mod upload, moderation queue, browse | | **moderation-service** | Rust + Axum | Report intake, ban management, appeal | | **contract-author-service** | Rust + Axum | Hitman contract upload + leaderboard + push | | **friends-service** | Rust + Axum | Cross-platform friend graph | | **party-service** | Rust + Axum | Party management, invites | | **chat-service** | Rust + Axum | Text chat with moderation | | **voice-sfu** | Rust | Voice SFU (WebRTC) for in-match voice | | **store-service** | Rust + Axum | In-game store, microtransactions | | **support-service** | Rust + Axum | Tickets, Sophia-grounded help bot, Tier-2 escalation | | **creator-relations-service** | Rust + Axum | Creator codes, drops, squad VOD windows | | **partnership-service** | Rust + Axum | Brand, venue, charity, NIL partner review | | **esports-service** | Rust + Axum | Tournament management, bracket sync | | **roadmap-service** | Rust + Axum | Public roadmap data, voting, JIRA/Linear delivery sync | | **public-api-service** | Rust + Axum | GraphQL public API and REST v1 compatibility shim | | **community-service** | Rust + Axum | Player spotlights, gallery, newsletter | | **patch-service** | Rust + Axum | Hotfix dispatch, data-table updates, patch push | **Backlog mapping (annotated 2026-06-12).** This 25-service table is wider than `V4_TODOS.md` §56's 18-subsection P1 inventory; the difference is planned, not accidental: - **P1 (§56.x):** login (§56.1), matchmaking (§56.2), session (§56.3), replay (§56.4), leaderboard (§56.5), anti-cheat (§56.6), telemetry-ingest (§56.7), balance-ledger (§56.8), workshop (§56.9), moderation (§56.10), contract-author (§56.11), friends / party / chat (§56.12), voice-sfu (§56.13), store (§56.14), support (§56.15), esports (§56.16), roadmap (§56.17), patch (§56.18). - **P1 elsewhere:** wiki-service (§84), creator-relations-service (§82), partnership-service (§88), roadmap surface (§85), support surface (§86). - **P2 expansions:** public-api-service (§98), community-service (§105), partnership-service curation (§112), support-service deep (§114), wiki + roadmap extensions (§98). - **Unplanned:** none — every service row above has at least one TODOS section. Implementation-status note (audit 2026-05-31 / remediation 2026-06-12): only the login router mounts real routes today; the other Rust service routers expose `/health` only while their tested service structs go unmounted — see the §56.x checkbox states in `V4_TODOS.md`. The support-service owns customer-support tickets, the Sophia-grounded help bot with wiki / FAQ citations, Tier-2 escalation, SLA p50/p95 reporting, refund policy routing, and regional support hours. The public-api-service publishes `/api/public/graphql` as the default public transport for roadmap and wiki reads while preserving REST v1 routes with `X-V4-Rest-Shim: public-api-rest-v1` for one major version. The roadmap-service reads `V4/roadmap/delivery-integrations.json` to project JIRA and Linear issue state into public roadmap status. In-flight items move to delivered automatically only when all linked provider work is done and the release gate is green; each transition carries an audit id. Final P3 signoff is owned by `V4/release/final-polish-readiness.json` and validated by `v4-final-polish-check`. The manifest reviews every P3 stretch section, records zero deferred polish items, and defines the year-5 service sunset plan ending on `2031-10-01T16:00:00Z`. The esports-service owns the Hall of Fame induction policy, community veto process, lifetime achievement categories, and one-of-a-kind banner art commission metadata that the Battle Hub renders as permanent Hall of Fame banners. The esports stack reads `V4/esports/pro-circuit/pro-circuit-2026.json` as the published 12-month Major / Minor / Open calendar (launch-aligned year-1 season, 2026-10-01 → 2027-09-30: 2 Majors, 4 Minors, 6 Opens). The public month-by-month view `V4/esports/calendar/first-12-months.json` mirrors the same 12 events. `V4/tools/esports` owns the `broadcastExtras` contract for picture-in-picture, replay rewind, observer-cam presets, and sponsor lower-thirds, while `DA_WildcardRouletteRules` is the server-seeded Wildcard / Roulette rule pool exposed to referees and spectators. `CommunityService` owns the §105 community loop: Player of the Week nominations advance through explicit curation states, featured creator squad VODs require approved creator accounts and HTTPS video URLs, gallery submissions reuse the moderation-service nudity/violence/rights scan before publication, and newsletter subscriptions are double-opt-in. `partnership-service` extends the §88 launch templates with `V4/legal/partnerships/partnership-curation-program.json`. Runtime submissions flow through `PartnershipService::review_partnership_submission`, which rejects off-limits categories, reactive paid placement, missing creative approval, missing disclosure, and venue proposals without cultural-representation review. Material disclosures are mirrored into `DA_PartnershipDisclosureCodex` for the in-game Codex and the public `legal.v4.game/partnerships` policy route. The §138 P3 extension lives in `V4/legal/partnerships/brand-partnerships-extended.json` and `DA_BrandPartnershipsExtended`. `UV4LiveServiceSubsystem` exposes the in-game queries and `PartnershipService` validates `negotiate_cross_ip_guest_operator`, `wire_annual_real_world_event_tie_in`, and `register_cause_led_cosmetic_collaboration` so cross-IP guests stay optional and time-boxed, annual real-event support blocks sponsor placement, and cause-led cosmetics route 100% of proceeds through the store ledger. `replay-service` owns the §113 per-account vault: default replay blobs expire after 14 days, starred replays move into lifetime storage, and the service enforces 500 starred replays per account with explicit star/unstar transitions and account-scoped archive listing. The shared speedrun ghost archive accepts only server-verified replay submissions with replay, input-stream, and checkpoint hashes; faster ghosts replace the active route ghost while preserving supersession lineage for audits and player-facing history. ### Inter-Service Communication - **gRPC** for service-to-service. - **Public REST** for client-to-service via API gateway. - **Public content API** under `/api/public/*`, with 60 req/min free and 600 req/min creator tiers enforced from the content-network manifest. - **WebSocket** for chat, party, presence. - **WebRTC** for voice. ### Data Stores - **PostgreSQL** (Cloud SQL) for relational data (accounts, inventory, ledger, leaderboards). - **Redis** for ephemeral (matchmaking queues, sessions, presence). - **ClickHouse** for telemetry (analytics queries). - **S3 / GCS** for blob (replays, mods, screenshots). - **MinIO** in dev. ## Anti-Cheat - **Kernel-mode anti-cheat:** Easy Anti-Cheat (EAC) default. Optional BattlEye for some regions where EAC isn't certified. - **Server-side validation:** Hit-reg sanity check, replay validation for ladder leaderboards. - **Behavioral detection:** AI-driven anomaly detection — statistical models flag inhuman aim signatures (superhuman snap aim, impossible recoil control, wallhack-shaped visibility patterns) for review. - **Trust score:** Each account has a trust score (0-100); low-trust accounts get matched together. - **Ban tiers** as described in features doc. - **Audit pipeline:** Every ban must have replay evidence + telemetry evidence + manual review for permanent bans. ## Cross-Play & Cross-Progression - **OnlineServices abstraction** with platform-specific implementations (EOSShared, PlayStation Network, Xbox Live, Nintendo Network, Apple Game Center, Google Play Games). - **Account link:** First-party account is the primary; platform accounts can link/unlink at any time. - **Currency rules** (the three-tier currency set is defined in `arch§"Persistence & Profile"`): - Soft currency (Operator Tokens): cross-platform. - Hard currency (Combat Points): per-platform per platform-holder rules. - Premium currency (Elite Tokens): cross-platform, earned through ranked play. - Cosmetics earned/purchased: cross-platform owned. - **Platform store features:** `DA_PlatformStoreFeatures` mirrors `V4/store/platform-store-features.json`. Store-service exposes `PlatformAchievementProvider` records for PSN trophies, Xbox, Steam, Nintendo, Apple Game Center, and Google Play Games, and `RegionalPrice` rows for PPP-adjusted launch pricing. `pricing_transparency_route()` resolves the public marketing page at `/store/pricing`. ## Map Lore Runtime - **Map lore source:** `V4/maps/map-lore.json` is the authored source for 200-300 word map Codex cards, the five faction signature maps, day/night schedule shifts, weather modifiers, and per-map crowd-density policy. `DA_MapLoreRuntime` mirrors that manifest for in-engine consumption. - **In-match Codex:** `WBP_InMatchCodexAccess` and `DA_FocusGraph_InMatchCodexAccess` bind the current map's lore card, gallery assets, related entries, search, and return-to-match focus path without routing through the front-end Codex map. - **Signature ambience:** `DA_SignatureMapAmbientTracks` provides one `SignatureMapAmbience` MetaSound per faction flagship and is referenced by the audio pipeline alongside the existing stage ambience beds. - **Day/night and weather:** `DA_MapWeatherAndTimeOfDay` covers Hitman, Commandos, and Desperados sandbox maps with dawn/day/night schedule shifts, rain/fog/snow VFX cues, RTST heavy-fog cone multiplier `0.9`, Wukong wet-stone slip additive `0.05`, and rain sound-footprint dampening. - **Density:** `DA_MapCrowdDensityScaling` generates one crowd-density profile per launch map row, preserving the high-density Hitman floor while keeping PvP, RTST, Arcade, and RTS defaults explicit for perf-budget validation. ## Audio Pipeline `V4Audio` uses MetaSounds as canonical audio runtime. ### MetaSounds Patches - **Weapon foley:** Per-weapon firing/reload/handling patches. - **Voice barks:** Per-operator bark patches with random selection. - **Music stacks:** Per-cell music with dynamic layering. - **Karaoke rhythm:** `DA_KaraokeRhythmMode` and `DT_KaraokeRhythmCharts` are owned by `UV4AudioBootstrapSubsystem`, which builds three original stream-cleared charts, judges Perfect/Good/Miss timing windows, and publishes `BattleHub.BeatMatching` session metadata. - **Stage ambience:** Per-map ambient beds. - **UI SFX:** Menu hover/click. ### Audio Modulation - **Mix snapshots:** Per-game-mode mix snapshots (combat vs ambient). - **Ducking:** Music ducks under VO; SFX ducks under critical callouts. ### Spatial Audio - **Steam Audio** integration for SC stealth missions (high-precision reverb, occlusion). - **Resonance Audio** for VR variants. ### Extended XR Launch XR stays scoped to the curated variants in `DA_XRLaunchVariants`. P3 expansion content is isolated in `DA_XRExtendedVariants` and validated by `v4-xr-extended-check`: - `XR.VR.SplinterCell.FullCampaign` maps all 10 `DT_Mission_SC` rows into the VR comfort contract. - `XR.VR.Wukong.FullBossRoster` exposes the complete 30-boss Wukong roster and all 8 chapter-end bosses with boss-scale comfort rules. - `XR.AR.VisionPro.TacticalPlanningTable` is a room-anchored Raven Shield planning table backed by `WBP_TacticalAROverlay` and `IMC_XR_ARTactical`. ### Voice / Dialogue - **Sequencer audio tracks** for cinematic dialogue. - **Random pool** for bark dialogue, per-operator pool. - **RivalryVoiceLineLibrary** overlays exact-pair banter intro and post-match winner lines on top of the per-operator bark pool. - **Lip sync** via OVR Lip Sync or MetaSounds metadata. ### Music Composers (per cell) - Tactical FPS (Raven Shield + R6 Modern): Composer A (cinematic orchestral). - Tactical FPS (CoD): Composer B (bombastic action). - Stealth (Splinter Cell, Hitman): Composer C (ambient electronic). - RTST (Commandos, Desperados): Composer D (cinematic strings + diegetic). - Action RPG (Wukong): Composer E (orchestral + erhu fusion). - RTS (StarCraft variant): Composer F (modular sci-fi). - RTS (AoE variant): Composer G (period-appropriate per civ). - 2D (Contra): Composer H (synth-rock). ## VFX Pipeline `V4VFX` uses Niagara for all real-time VFX. ### Particle Systems - **Muzzle flash** per weapon class. - **Blood decals** per damage type (gunshot, blade, fall). - **Debris** for destruction (Chaos Destruction → Niagara debris spawn). - **Weather** (rain, snow, fog). - **Environmental effects** (volumetric fog, sandstorm, smoke). ### LOD Buckets - **Hero VFX** (player POV, near camera): full-fidelity Niagara. - **Medium VFX** (ambient): reduced particle count. - **Background VFX** (distant): impostor or sprite-only. ## Cinematic Pipeline `V4Cinematics` uses Sequencer for all linear cinematics. ### Cinematic Cameras - **Sequencer-driven** cinematic cameras for openers, mid-mission setpieces, endings. - **RivalryPostMatchCinematics** are short, skippable Sequencer clips selected by `OperatorRivalries` when opposing-side rivals resolve at match end. - **Movie Render Queue** for pre-rendered cinematics (CoD campaign opener, Wukong boss intros). ### MetaHuman Integration - **MetaHuman Animator** for facial mocap of principals. - **Live Link Face** for performance capture. ### Replay System - **Demo recording** via UE's `Replays` plugin. - **Replay format:** UE-native demos; export to MP4 via Movie Render Queue. - **Mission commentary:** `DA_MissionDesignerCommentaryTracks` is consumed by `UV4ReplayViewerController`; `WBP_MissionReplayCommentaryToggle` and `DA_FocusGraph_MissionReplayCommentaryToggle` expose a fixed-size per-replay commentary toggle without shifting the replay timeline. - **Composer and mocap commentary:** `DA_ComposerCommentaryInterviews` is owned by the audio bootstrap path and unlocks on Operator XP plus per-cell completion. `DA_MocapActorCommentaryReflections` is owned by the operator roster and surfaces through `DA_OperatorBriefingDossier`. - **Experimental commentary formats:** `DA_DeveloperStreamArchive` is resolved by `UV4CinematicSubsystem` and surfaced in `WBP_CodexShell` through the Codex media archive. `DA_OperatorNilInterviews` is owned by `UV4OperatorRosterCatalog` and adds all-operator NIL interview playback to the operator dossier. `DA_ComposerLivePerformanceBroadcast` is owned by `UV4AudioBootstrapSubsystem`; `DA_BattleHubComposerLivePerformance` and `UV4BattleHubLiveEventService` anchor the one-off concert to `Lobby.BattleHub.Zone.Concert`. - **Battle Hub music station:** `DA_BattleHubBeatMatchingMode` and `UV4BattleHubMusicStationService` expose the karaoke charts as a queueable beat-matching station anchored to `Lobby.BattleHub.Zone.Music`, with `WBP_BattleHub` reserving compact music, prompt, queue, and score surfaces. - **Battle Hub arcade mini-games:** `DA_ArcadeMiniGameSuite` and `DT_ArcadeMiniGames` are owned by `UV4ArcadeMiniGameCatalog`. `DA_BattleHubArcadeMiniGameSuite` and `UV4BattleHubArcadeMiniGameService` place the pinball, air hockey, mini-golf, darts, pool, and cooking cabinets in `Lobby.BattleHub.Zone.Arcade` with compact list, pinball, and score surfaces in `WBP_BattleHub`. - **Live AI commentary:** spectator-mode broadcasts consume `DA_LiveAICommentaryBroadcast` through `UV4LiveAICommentaryBroadcastService`. The service resolves distinct play-by-play and color Calliope personas, emits localized live commentary for the 12 launch VO languages, and requires `BiasReview.AICommentary.Live` review before generated lines are marked ready for broadcast. - **AI commentary extended:** `DA_AIGeneratedCommentaryExtended` extends `UV4AIGeneratedCommentaryPipeline` with `BuildPersonalVoiceCloneConsentPolicy`, `BuildPersonalVoiceCloneCommentaryProfile`, `BuildPostSeasonAIPodcastRecaps`, and `BuildCommentaryLocalizationNuanceReviewPlan`. The runtime requires `VoiceCloneConsent.PersonalFriends`, two consenting accounts, revocation-ledger checks, watermarked/provenance-embedded generated audio, 10-minute per-cell podcast recaps, and native-speaker nuance review queues. ## UI / HUD Architecture `V4UI` uses UMG + CommonUI + ModelViewViewModel. ### Front-End Shell - **CommonUI** front-end with input-style routing (gamepad vs M+KB). - **Focus graph** authored per screen. - **Localization** namespace per cell. - **Community gallery:** `DA_CommunityGallery` configures screenshot/replay moderation and published slots; `WBP_GalleryShowcase`, `L_UI_Gallery`, and `DA_FocusGraph_Gallery` expose the in-game Gallery screen. - **Launch experience:** `ui/launch-experience` is the canonical manifest for loading screens, What's New, in-game notifications, and companion push. `DA_LoadingScreenLibrary` owns per-cell art and tip rotation, the splash data selects video by renderer budget, and `DA_InGameToastQueue` owns toast stacking, motion, and accessibility behavior. ### In-Match HUDs - **Tactical FPS HUD:** Crosshair, health, ammo, mini-map, killfeed. - **Stealth HUD:** Light-gauge bow-tie, suspicion radius, disguise icon. - **Tactics HUD:** Top-down floor plan, party portraits, command queue. - **ARPG HUD:** Health/stamina/will/posture bars, charm slots, lock-on marker. - **RTS HUD:** Resource ticker, build menu, mini-map, group hotkeys. - **2D HUD:** Score, lives, weapon icon. ### ModelViewViewModel - All HUD bindings via MVVM; no direct attribute access from UMG. ## Telemetry & Analytics `V4Telemetry` event schema + batched sender. ### Event Schema | Event | Fields | | -------------------- | --------------------------------------------------------- | | `match_start` | match_id, cell, mode, players[], map, ts | | `match_end` | match_id, duration, result, players[], ts | | `player_move` | match_id, player_id, position, velocity, ts | | `player_fire` | match_id, player_id, weapon, hit_actor, ts | | `player_death` | match_id, player_id, killer, weapon, ts | | `objective_complete` | match_id, player_id, objective_id, ts | | `mode_specific.*` | Per-mode events (e.g., `rts.build`, `arpg.parry_success`) | | `monetization.*` | Cosmetic purchase, ledger entry | ### Batched Sender - **Client-side queue** with 256 KB buffer. - **Flush:** Every 30 s or on buffer-full. - **Offline:** Queue persists to disk; retry on reconnect. ### Dashboards - **Grafana** dashboards per cell, per region, per mode. - **ClickHouse** as analytics store. - **Balance dashboards** feed automated alerts. ## Build, Cook, Patch ### Build System - **UnrealBuildTool** with custom `V4.Target.cs` and `V4Server.Target.cs`. - **Distributed compile** via FASTBuild + SN-DBS (PS5 dev). - **Build pipelines:** Jenkins (PC), GitHub Actions for tools. ### Cook - **Per-platform cook** with platform-specific asset stripping. - **Cook time budget:** ≤ 8 hours per platform on the build farm. ### Patch - **Day-One patch budget:** ≤ 6 GB. - **Hotfix system:** Data-table updates pushed via patch-service without binary update. - **Differential patches** for incremental releases. ## Data Architecture ### Data Tables - **DT_Operator:** Roster of named operators. - **OperatorRivalries:** Runtime registry derived from `DT_Operator` that resolves reciprocal rival pairs, banter intro cue ids, exclusive VO ids, and RivalryPostMatchCinematics for match end. - **DT_Weapon:** Weapon attributes. - **DT_Attachment:** Weapon attachment modifiers. - **DT_Gadget:** Operator gadget attributes. - **DT_RTSUnit:** RTS unit attributes. - **DT_RTSTech:** RTS tech tree. - **DT_RTSCiv:** AoE civilization roster. - **DT_RTSTPersonality:** RTST specialist attributes. - **DT_ARPGBoss:** Wukong boss attributes. - **DT_ARPGForm:** Transformation attributes. - **DT_Map:** Map metadata. - **DT_Mission:** Mission metadata, objectives, NPC count. - **DT_Schedule:** Schedule templates per Hitman map. - **DT_DisguiseClass:** Disguise classes per map. ### Localization - **Single localization namespace** per cell. - **String tables** per asset category. - **Translator workflow:** Glossary + style guide per language; CAT-tool integration (Crowdin — selected, configured in `V4/loc/crowdin.yml`). ## Live-Service & DLC ### GameFeatures Plugin Strategy - **Operator DLC:** Each new operator ships as a small GameFeature plugin. - **Map DLC:** Each new map ships as a GameFeature plugin. - **Cell DLC:** New rulesets (post-launch) ship as full GameFeature plugins. ### Season Cadence - **90-day seasons.** - **Battle pass authoring:** Sequencer-driven cosmetics reveal. - **Server-side patch dispatch:** Data-table-only patches push within 30 minutes of approval. - **Ranked operations:** `DA_RankedSeasonArchitecture` defines the five year-1 ladders (`Ranked.Tactical.R6Modern`, `Ranked.Stealth.SpiesVsMercs`, `Ranked.RTS.Asymmetric`, `Ranked.RTS.Historical`, `Ranked.ARPG.BossRush`), Diamond+ 14-day rank decay, peak-rank reward bundles, top-100 regional championship frames, top-1000 consolation rewards, public `/ranked` MMR histograms, and the `WBP_RankedMatchmakingDiagnostic` explanation panel. - **Live-service calendar:** `DA_LiveServiceCalendar` mirrors `V4/liveops/live-service-calendar.json` and exposes `ResolveLiveServiceThemeForMonth`, `IsAnniversaryLoginBonusActive`, `BuildAnnualCharityDrives`, and `BuildPlatformCosmeticTieIns`. The manifest covers Winter Operation, Lunar New Year, Spring, Summer Heat, and Harvest month windows; a launch-anniversary free login grant tied to the Raven Shield 2003-style mission; one fully disclosed 100% proceeds charity drive per year; and platform-holder-approved cosmetic-only tie-ins for every launch platform family. - **Signature Event Modes:** `DA_SignatureEventModes` is consumed by `UV4LiveServiceSubsystem` for Year-1 event-only modes. It validates Halloween Night Shift tactical PvE horror with reskinned NPCs, Holiday Hometown Skirmish festive reskins across all six launch cells plus the `L_Event_Hometown_RTS_Skirmish` map, Pride Signal Colors cosmetics with a creator-pick partner charity, and the Esports All-Stars mid-season exhibition ruleset variant. ## Accessibility Implementation lives in `V4UI::FAccessibilitySubsystem` and per-cell HUD code. - **Subtitles:** Size, color, background opacity, speaker indicator. - **Colorblind modes:** Per-color-channel adjustments for HUD. - **Aim assist:** Tunable per cell, per mode. - **High-contrast mode:** All HUDs. - **Audio cues:** Per-event toggle. - **One-handed controls:** Per cell. - **Cognitive options:** UI declutter, slow-mo ARPG. ## Security, Privacy, Compliance ### Identity - **OAuth 2.0** with platform identity providers. - **Refresh tokens** rotated; access tokens short-lived. - **Cross-surface SSO** uses the `v4-account` realm for companion, wiki, roadmap, spectator, and developer OAuth app surfaces, each with its own idle and absolute timeout. - **Sophia wiki summaries** are resolved through `V4/wiki/ai-summary-policy.json` and `resolveWikiAiSummary`; summaries are cited, Sophia-grounded, and withheld unless the request includes `x-v4-ai-summary-opt-in: true`. - **PII at-rest** encrypted with KMS-managed keys. ### Compliance - **GDPR:** DSAR portal at `support.v4.game/dsar`; 30-day turnaround. - **CCPA:** Right-to-delete; 45-day purge. - **DSA:** Statement-of-reasons logging for every moderation action. - **COPPA:** Under-13 verified accounts; restricted experience build. - **Privacy-by-Design:** Year-1 privacy runtime extends launch compliance with annual DPIA summary cards, contract-change sub-processor notices, published per-jurisdiction notes, and region-aware feature defaults. - **Region feature-flag matrix:** `UV4ComplianceSubsystem` resolves regional privacy defaults for EU, UK, US, BR, JP, KR, IN, and CN/PRC. China defaults voice chat off; CN, KR, and IN resolve to cosmetic-only economy. - **Replay scrubber:** `UV4ReplayCloudArchive.ScrubDeletedAccountFromReplay` and the Rust `ReplayService::scrub_deleted_account_from_replay` remove a deleted account's identifiers and show the anonymous deleted-account skin in preserved replay playback. ### Audit - **All moderation actions** logged with actor, target, reason, evidence. - **Sub-processor registry** at `legal.v4.game/processors`. - **DPIA documents** for AI features. - **DPIA summary cards** at `legal.v4.game/dpia`, refreshed annually for AI commentary, behavior detection, and auto-mod. ## Observability, Evaluation, Release Gates ### Observability - **Grafana** dashboards. - **Prometheus** metrics. - **OpenTelemetry** traces. - **Sentry** for client and server error reporting. ### Release Gates - **PR-gate CI:** Lint, unit tests, smoke automation, asset linter, dep check. - **Nightly:** Gauntlet feel-tests for all six launch cells. - **Pre-merge:** Golden-replay regression suite. - **Pre-release:** Full automation suite + manual smoke. ## Performance Budgets Per-platform per-cell budgets: | Platform | Tactical FPS | RTST | ARPG | RTS | 2D | | ------------------- | ------------------------- | ------ | ------ | ------ | ------ | | PC Ultra (4K) | 60 fps | 60 fps | 60 fps | 60 fps | 60 fps | | PS5 Performance | 60 fps (4K dynamic) | 60 fps | 60 fps | 60 fps | 60 fps | | PS5 Quality | 30 fps (4K) | 60 fps | 30 fps | 60 fps | 60 fps | | PS5 Pro | 60 fps (4K) Quality | 60 fps | 60 fps | 60 fps | 60 fps | | XSS | 60 fps (1080p) | 60 fps | 30 fps | 30 fps | 60 fps | | Switch 2 | 30 fps (1080p docked) | 30 fps | 30 fps | 30 fps | 60 fps | | macOS Apple Silicon | 60 fps (1440p) | 60 fps | 60 fps | 60 fps | 60 fps | | Steam Deck | 60 fps (800p) Performance | 60 fps | 30 fps | 60 fps | 60 fps | | iPad Pro M2+ | 60 fps (1080p) | 60 fps | 30 fps | 30 fps | 60 fps | | Android High-End | 30 fps (1080p) | 30 fps | 30 fps | 30 fps | 60 fps | ### Frame Budget Breakdown (PS5 Tactical FPS, 60 fps = 16.6 ms) - **CPU:** 12 ms (game thread + render thread parallel). - **GPU:** 13 ms (frame + post + UI). - **Audio:** 0.6 ms. - **Networking:** 0.4 ms (async, non-blocking). - **Headroom:** 2 ms. ### Memory Budget (PS5) - **System RAM:** 14 GB available; 6 GB game, 5 GB streaming, 3 GB OS. - **GPU memory:** Shared with system (PS5 unified); 8 GB target for active gameplay. ## Testing, QA, Cert ### Automation - **Unit tests:** Per-module under `V4/ue/Source/V4Tests/Private/Tests/`. - **Feel tests:** Per-cell/per-mode specs under `V4/ue/Source/V4Tests/Private/V4Mode*Tests/*Spec.cpp`. - **Functional tests:** Per-system specs alongside the unit specs under `V4/ue/Source/V4Tests/Private/`. - **Gauntlet end-to-end:** Per-mode automation driven from the same V4Tests module specs. - **Golden replay regression:** Per-cell replay corpus under `V4Tests/GoldenReplays/`. ### QA - **In-house QA team:** Per-cell QA leads. - **External QA:** Per-platform certification partners. - **Beta QA:** Player feedback via in-game bug-report and forum. ### Cert - **Per-platform cert:** Sony TRC, Microsoft XR, Nintendo Lotcheck, Steam Deck Verified. - **Cert checklist:** Each platform's cert checklist mapped to V4- specific TODOs. ## Content Pipeline & Source Control ### Source Control - **Perforce** for binary content (animations, audio, MetaHumans). - **Git** for source code, configuration, scripts (`apps/`, `services/`, `tools/`, `V4/ue/Source/`, `V4/ue/Config/`). - **Git LFS** for shared text-y binary (small icons, FBX). ### Asset Pipeline - **Importers:** FBX (animations, meshes), WAV (audio), PNG (sprites). - **Asset linter:** Naming conventions, missing dependencies, broken references, missing localization keys. - **Cook validation:** Per-platform cook test fails on missing assets or oversized assets. **`.v4asset.json` stand-in convention (documented 2026-06-12).** Because this repository is text-only (no Perforce binary depot is attached), every Unreal content asset referenced by the docs and check gates exists as a JSON stand-in: `.uasset.v4asset.json` for data assets / widgets / data tables and `.umap.v4asset.json` for maps — 770 such files under `V4/ue/` today (529 `.uasset` + 241 `.umap` stand-ins). A stand-in carries the asset's authored intent (typed fields, row data, references to C++ symbols and other stand-ins) and is what the `v4-*-check` gates and `V4_TODOS.md` marks attest to. Stand-ins are **not** cooked `.uasset`/`.umap` binaries: they cannot be loaded by the engine, cooked, profiled, or played. Any claim that requires cooked content — PSO caches, Chaos geometry collections, profiled frame rates, playable maps — remains open until the binary content exists (see the audit notes in `V4_TODOS.md`). ## Creator Suite Architecture `V4Editor` extends UE Editor with per-cell authoring widgets. ### Mission Editor - **Per-cell mission template:** Tactical mission template loads the V4Tactical module's spawn/objective patterns. - **Schedule authoring widget:** Drag-and-drop NPC schedule nodes. - **Vision-cone preview:** Visualize cone over the level. - **Validation:** Editor-side validation runs before publish. ### Contract Author - **Hitman-specific UI:** Target NPC picker, kill method dropdown, disguise dropdown, bonus objectives. - **Author play-through:** Mandatory live completion to publish. ### RTS Map Editor - **Terrain sculpting** brushes. - **Resource patches** placement. - **Start positions** drag-and-drop. - **Triggers** for campaign-style scripted RTS. ### 2D Stage Editor - **Grid-snap pixel art import.** - **Hazard placement.** - **Enemy spawn schedule.** - **Boss arena designer.** ## Cross-Cell Persistence & Operator XP ### Unified Operator Record - **DT_Operator row** carries: - Roster ID - Display name - Faction - Per-cell mesh references (Tactical 1P/3P, Stealth 3P, Tactics top-down, ARPG 3P, RTS unit, 2D sprite). - Voice line library reference. - Gadget / spell / ability reference. - Backstory text. - 1-3 reciprocal rival ids linked through `OperatorRivalries`. - **Operator XP** scaled per cell: - Tactical FPS PvP: 100 XP / win, 50 XP / loss. - RTST mission: 200 XP / completion. - ARPG boss kill: 250 XP / unique boss, 50 XP / repeat. - RTS ladder win: 80 XP / win. - 2D stage clear: 30 XP / stage. ### XP Sync - **Server-authoritative XP:** Client reports match result; server validates against telemetry; XP applied via ledger entry. - **Anti-grind:** Daily XP cap per operator (5000 XP / day) to prevent bot farming. - **Level bounds:** `DA_ProgressionModel` defines a linear 1000 XP-per-level model. Operator XP derives levels 1-100 and clamps at 99,000 XP; Account XP derives levels 1-1000 and clamps at 999,000 XP. `UV4ProfileSubsystem` exposes `GetOperatorLevel`, `GetAccountLevel`, threshold helpers, and `ClampOperatorDailyXPGrant`. - **Codex progression:** Profile state stores `UnlockedCodexEntryIds`, synced by cross-progression. `DA_CodexEntryLibrary` maps launch data sources into unlockable Operator, Weapon, Gadget, Map, Faction, Civilization, Ruleset, and Vehicle entries, each requiring lore text, asset gallery ids, and design commentary. The front-end Codex route instantiates `WBP_CodexShell` with the Codex entry library and focus graph; its media archive pane also hosts `DA_DeveloperStreamArchive` entries and archived live-performance broadcasts. ## Launch Readiness The architecture work that must complete before launch is documented in `V4_TODOS.md` §94 (Launch Readiness section). The authoritative, complete launch gate list is `V4_features.md` § "V4 Exit Criteria" (12 criteria); the gates below are the architecture-owned subset of that list: - All six launch cells deliver feel tests green on the merge commit. - All 9 platforms ship day-1. - Crash dedup dashboard < 0.1%. - Matchmaking p99 ≤ 35 s under 5× expected launch concurrency. - Anti-cheat live with verified ban roster. - All compliance gates green. - Esports calendar published. ## Cross-References - **Features:** `V4_features.md` § "V4 Product Promise", § "Ruleset Cells Overview", § "Shared Cross-Cell Systems". - **Dependencies:** `V4_DEPENDENCIES.md` §1 (Engine Version), §2 (First-Party UE Plugins), §3 (Third-Party UE Plugins), §8 (Networking & Lockstep), §9 (Online Services Provider). - **Backlog:** `V4_TODOS.md` §1 (Bootstrap), §2 (Subsystem Glossary), §3 (Module Split), §10 (RTS Lockstep), §94 (Launch Readiness).