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/. This file remains the canonical hub (every section heading is preserved, so existingarch§"…"anchors keep resolving); the in-depth, code-grounded companion pages live underarchitecture/. Start at the architecture page index. The product feature map is inV4_features.md/features/.
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/V4_TODOS.md, and
V4/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§"<anchor>"→ this document, by section anchor.features§"<anchor>"→V4_features.mdsection 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
- Subsystem Glossary
- High-Level Architecture
- Project Layout
- Module Split
- Gameplay Ability System (GAS) Layout
- Animation Pipeline
- Input Pipeline
- AI Perception, NPC Schedules, Crowd
- Vision Cones, Suspicion, Stealth Gauges
- Per-Cell Architecture Deep-Dives
- Networking, Authority & Determinism
- Game Modes (GameFeatures Plugins)
- Sandbox Streaming (World Partition + Crowd)
- Procedural Generation Pipeline
- Persistence & Profile
- Online Services Backend
- Anti-Cheat
- Cross-Play & Cross-Progression
- Audio Pipeline
- VFX Pipeline
- Cinematic Pipeline
- UI / HUD Architecture
- Telemetry & Analytics
- Build, Cook, Patch
- Data Architecture
- Live-Service & DLC
- Accessibility
- Security, Privacy, Compliance
- Observability, Evaluation, Release Gates
- Performance Budgets
- Testing, QA, Cert
- Content Pipeline & Source Control
- Creator Suite Architecture
- Cross-Cell Persistence & Operator XP
- Launch Readiness
- 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
GameFeaturesplugin 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:
┌────────────────────────────────────────────────────────────────────┐
│ 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.jsonowns §117 gates,pso-delta-report.jsontracks per-patch PSO changes,mission-preload-profile.jsonrecords per-cell mission-select preload timing, andUV4ShaderWarmupSubsystem::BuildAdaptiveMissionPreloadQueueexposes 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#
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/<ModuleName>/ 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 aPrivate/implementation tree (internal only). Cross-module includes follow the public surface; never reach into another module'sPrivate/. - 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_CoDWarzoneandV4Mode_Tactical_R6Modern(memory); mobile builds additionally stripV4Mode_Tactical_CoDWarzone(no 100-player Battle Royale on those targets at launch). Stripping is.Target.csdriven, 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.FireIA_PlanWaypoint→GA.Tactics.PlanQueueWaypointIA_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_DualSenseWeaponTriggerCurvesgenerates one adaptive-trigger curve perDT_Weaponrow from recoil-curve metadata and adds Stealth heartbeat, ARPG parry tick, and RTS distant-battle haptic patterns.DA_XboxImpulseWeaponPatternsmirrors the per-weapon class data to Xbox impulse triggers so Series controllers stay aligned with DualSense tuning.DA_WheelCalibrationProfilesstores Logitech, Thrustmaster, Fanatec, and Moza brand calibration profiles.WBP_ForceFeedbackCurveEditorandDA_ForceFeedbackCurveEditorexpose editable strength curves from Settings.IMC_HOTAS_HeloDoorGunneradds the helo door-gunner HOTAS profile on top of the launch aerial setpiece context.DA_AdaptiveControllerPresetsprovides Xbox Adaptive Controller presets plus theIMC_AdaptiveController_TacticalSingleSticktactical-FPS variant.DA_EyeTrackingInputAssistwires Tobii PC and PS5 Pro providers for camera-aim assist and gaze-based UI focus throughIMC_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
FStimulusEventwith 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; thePerceptionEvaluatorticks 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.AlertPropagationevent 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:
UV4ScheduleAssetis a Sequencer-style timeline of schedule nodes (waypoint + task + duration), serialized as.uassetwith editor authoring widget. - Schedule runtime:
UV4ScheduleComponentticks 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
Panicstimulus spreads at 4 m/s through the crowd graph; affected NPCs run to nearest exfil node. - Disguise check: Crowd subsystem checks
Player.DisguiseClassagainst each NPC's disguise class onLineOfSightevents; 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::FConeAuthoringWidgetlets 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
DisguiseEnforcerClassfield; ifPlayer.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.Primaryexclusively to the active specialist turn. - RTS LAN:
RTS.LANSkirmishadvertises 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.CrossPlayerteam leaderboard. - Endurance: Endless Spec Ops waves with escalating enemy scalar and a diminishing ammo / heal-flask economy across waves.
- Weekly ops:
DA_SpecOpsPostLaunchOpsis linked fromDA_SpecOpsOnlineCoop;BuildWeeklyFeaturedContractSlate,BuildModifierDeck, andSelectModifierStackAtMissionStartprovide the weekly featured contract slate, authored modifier deck, and deterministic mission-start modifier stack. - Cross-cell crossover:
SpecOps.Crossover.TempleBreachpairs 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_CoDWarzoneandV4Mode_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_HitmanrequiresV4Mode_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:
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_RoguelikeAdventureModelinksDT_Roguelike_MetaProgression,DT_Roguelike_BossRoster, andDT_Roguelike_Boons. Runtime state is carried byFV4RoguelikeMetaProgressionState;UV4RoguelikeTacticalRunBuilderbanks 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_PersistentWorldEconomySeasonalStateextends 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_HitmanSeasonalScheduleRotationskeeps the same TargetA/TargetB/Handler/SecurityChief/Chef/Doctor/VIPGuest/Mechanic NPC ids across seasons while swapping quarterly routine ids, with public patch notes inV4/stealth/hitman/schedule-rotation-patch-notes.md. - Cross-cell hooks:
DA_WorldStateCrossoverHooksmaps authored Hitman assassination events to campaign branch flags such asCoD.BlackoutLedger.AssassinationConfirmed. Hooks are resolved before mission load so live telemetry never changes deterministic combat simulation. - Wiki feed:
V4/wiki/world-state-feed.jsonand/api/public/wiki/world-stateexpose season id, total kills, top map, most-targeted NPC, active schedule variants, and unlocked narrative branches as read-only wiki data. - Ripple manifest:
DA_PersistentWorldEconomyDeepextends the seasonal state withDT_WorldStateRippleEvent,DT_PlayerDrivenWorldEvent, andDT_FactionBalanceArc. The manifest atV4/wiki/world-state-ripple.jsonand/api/public/wiki/world-state-ripplepublishes 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, andDT_CommunityRaidProgressEventextendUV4HitmanPersistentWorldSubsystemwithBuildSeasonalWorldBossRaids,BuildCommunityRaidProgressEvents, andRecordCommunityRaidContribution. 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_PlatformStoreFeaturesmirrorsV4/store/platform-store-features.json. Store-service exposesPlatformAchievementProviderrecords for PSN trophies, Xbox, Steam, Nintendo, Apple Game Center, and Google Play Games, andRegionalPricerows 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.jsonis 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_MapLoreRuntimemirrors that manifest for in-engine consumption. - In-match Codex:
WBP_InMatchCodexAccessandDA_FocusGraph_InMatchCodexAccessbind 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_SignatureMapAmbientTracksprovides oneSignatureMapAmbienceMetaSound per faction flagship and is referenced by the audio pipeline alongside the existing stage ambience beds. - Day/night and weather:
DA_MapWeatherAndTimeOfDaycovers Hitman, Commandos, and Desperados sandbox maps with dawn/day/night schedule shifts, rain/fog/snow VFX cues, RTST heavy-fog cone multiplier0.9, Wukong wet-stone slip additive0.05, and rain sound-footprint dampening. - Density:
DA_MapCrowdDensityScalinggenerates 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_KaraokeRhythmModeandDT_KaraokeRhythmChartsare owned byUV4AudioBootstrapSubsystem, which builds three original stream-cleared charts, judges Perfect/Good/Miss timing windows, and publishesBattleHub.BeatMatchingsession 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.FullCampaignmaps all 10DT_Mission_SCrows into the VR comfort contract.XR.VR.Wukong.FullBossRosterexposes the complete 30-boss Wukong roster and all 8 chapter-end bosses with boss-scale comfort rules.XR.AR.VisionPro.TacticalPlanningTableis a room-anchored Raven Shield planning table backed byWBP_TacticalAROverlayandIMC_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
OperatorRivalrieswhen 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
Replaysplugin. - Replay format: UE-native demos; export to MP4 via Movie Render Queue.
- Mission commentary:
DA_MissionDesignerCommentaryTracksis consumed byUV4ReplayViewerController;WBP_MissionReplayCommentaryToggleandDA_FocusGraph_MissionReplayCommentaryToggleexpose a fixed-size per-replay commentary toggle without shifting the replay timeline. - Composer and mocap commentary:
DA_ComposerCommentaryInterviewsis owned by the audio bootstrap path and unlocks on Operator XP plus per-cell completion.DA_MocapActorCommentaryReflectionsis owned by the operator roster and surfaces throughDA_OperatorBriefingDossier. - Experimental commentary formats:
DA_DeveloperStreamArchiveis resolved byUV4CinematicSubsystemand surfaced inWBP_CodexShellthrough the Codex media archive.DA_OperatorNilInterviewsis owned byUV4OperatorRosterCatalogand adds all-operator NIL interview playback to the operator dossier.DA_ComposerLivePerformanceBroadcastis owned byUV4AudioBootstrapSubsystem;DA_BattleHubComposerLivePerformanceandUV4BattleHubLiveEventServiceanchor the one-off concert toLobby.BattleHub.Zone.Concert. - Battle Hub music station:
DA_BattleHubBeatMatchingModeandUV4BattleHubMusicStationServiceexpose the karaoke charts as a queueable beat-matching station anchored toLobby.BattleHub.Zone.Music, withWBP_BattleHubreserving compact music, prompt, queue, and score surfaces. - Battle Hub arcade mini-games:
DA_ArcadeMiniGameSuiteandDT_ArcadeMiniGamesare owned byUV4ArcadeMiniGameCatalog.DA_BattleHubArcadeMiniGameSuiteandUV4BattleHubArcadeMiniGameServiceplace the pinball, air hockey, mini-golf, darts, pool, and cooking cabinets inLobby.BattleHub.Zone.Arcadewith compact list, pinball, and score surfaces inWBP_BattleHub. - Live AI commentary: spectator-mode broadcasts consume
DA_LiveAICommentaryBroadcastthroughUV4LiveAICommentaryBroadcastService. The service resolves distinct play-by-play and color Calliope personas, emits localized live commentary for the 12 launch VO languages, and requiresBiasReview.AICommentary.Livereview before generated lines are marked ready for broadcast. - AI commentary extended:
DA_AIGeneratedCommentaryExtendedextendsUV4AIGeneratedCommentaryPipelinewithBuildPersonalVoiceCloneConsentPolicy,BuildPersonalVoiceCloneCommentaryProfile,BuildPostSeasonAIPodcastRecaps, andBuildCommentaryLocalizationNuanceReviewPlan. The runtime requiresVoiceCloneConsent.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_CommunityGalleryconfigures screenshot/replay moderation and published slots;WBP_GalleryShowcase,L_UI_Gallery, andDA_FocusGraph_Galleryexpose the in-game Gallery screen. - Launch experience:
ui/launch-experienceis the canonical manifest for loading screens, What's New, in-game notifications, and companion push.DA_LoadingScreenLibraryowns per-cell art and tip rotation, the splash data selects video by renderer budget, andDA_InGameToastQueueowns 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.csandV4Server.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_Operatorthat 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_RankedSeasonArchitecturedefines 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/rankedMMR histograms, and theWBP_RankedMatchmakingDiagnosticexplanation panel. - Live-service calendar:
DA_LiveServiceCalendarmirrorsV4/liveops/live-service-calendar.jsonand exposesResolveLiveServiceThemeForMonth,IsAnniversaryLoginBonusActive,BuildAnnualCharityDrives, andBuildPlatformCosmeticTieIns. 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_SignatureEventModesis consumed byUV4LiveServiceSubsystemfor 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 theL_Event_Hometown_RTS_Skirmishmap, 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-accountrealm 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.jsonandresolveWikiAiSummary; summaries are cited, Sophia-grounded, and withheld unless the request includesx-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:
UV4ComplianceSubsystemresolves 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.ScrubDeletedAccountFromReplayand the RustReplayService::scrub_deleted_account_from_replayremove 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/<Module>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:
<AssetName>.uasset.v4asset.json for data assets / widgets / data tables and
<MapName>.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_ProgressionModeldefines 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.UV4ProfileSubsystemexposesGetOperatorLevel,GetAccountLevel, threshold helpers, andClampOperatorDailyXPGrant. - Codex progression: Profile state stores
UnlockedCodexEntryIds, synced by cross-progression.DA_CodexEntryLibrarymaps 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 instantiatesWBP_CodexShellwith the Codex entry library and focus graph; its media archive pane also hostsDA_DeveloperStreamArchiveentries 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).