Tactical Action · Architecture

V4 — Architecture (Tactical Action Universe, Unreal Engine 5)

The runtime, package, and integration architecture behind Tactical Action — an unreal engine 5 tactical action universe. How the systems fit together, communicate, and scale.

41sections49 minread6tables

On this page

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 existing arch§"…" anchors keep resolving); the in-depth, code-grounded companion pages live under architecture/. Start at the architecture page index. The product feature map is in V4_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:

  • §40V4_TODOS.md §40 — the default convention.
  • deps§14V4_DEPENDENCIES.md §14.
  • arch§"<anchor>" → this document, by section anchor.
  • features§"<anchor>"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 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/<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 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_FireGA.Tactical.Fire
  • IA_PlanWaypointGA.Tactics.PlanQueueWaypoint
  • IA_ParryGA.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/<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_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).