# V5 — Architecture (Open-World Narrative Universe, Unreal Engine 5)

Status: V5 launch architecture and full-vision extension architecture  
Source: derived from `V5/V5_features.md` (feature map) and `V5/V5_TODOS.md`
(implementation backlog)  
Audience: engineering, architecture, AI, online services, build, and platform
leads scoping V5.  
Date: 2026-05-15

> **This architecture reference has been decomposed into focused pages under
> [`architecture/`](./architecture/README.md).** This file remains the canonical
> hub (every section heading is preserved, so existing `arch§"…"` anchors keep
> resolving); the in-depth, code-grounded companion pages live under
> [`architecture/`](./architecture/README.md). Start at the
> [architecture page index](./architecture/README.md). The product feature map
> is in [`V5_features.md`](./V5_features.md) /
> [`features/`](./features/README.md).

## Purpose

This document describes the runtime, package, and integration architecture that
V5 must ship behind. It is grounded in the V5 feature map (`V5_features.md`) and
the V5 backlog (`V5_TODOS.md`), and is anchored to the packages and modules that
the V5 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 docs: [`V5/V5_features.md`](./V5_features.md),
[`V5/V5_TODOS.md`](./V5_TODOS.md), and
[`V5/V5_DEPENDENCIES.md`](./V5_DEPENDENCIES.md).

V5 is a single coherent open-world narrative-action game whose **per-genre
feel** ambition spans Urban Crime, Period Drama, Frontier, Monster Hunter, and
Sci-Fi launch cells, with DLC cells such as Brave New World Steampunk Detective
and a cross-cell Mind Palace deduction layer (Sherlock Holmes-style). The
architecture mirrors that ambition: one shared roster, one shared deduction
layer, 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
`V5_TODOS.md`** (the only V5 doc with section numbering used as hyperlinks).
Explicit doc-prefixed references appear where ambiguity matters:

- `§40` → `V5_TODOS.md` §40 — the default convention.
- `§52` → `V5_TODOS.md` §52.
- `deps§14` → `V5_DEPENDENCIES.md` §14.
- `features§"<anchor>"` → `V5_features.md` section by anchor (the features doc
  is not numbered).
- `arch§"<anchor>"` → this document, by section anchor.

`V5_features.md` and this document use named anchors, not numbers, to avoid
duplicating the TODOs numbering scheme.

## Table of Contents

- [V5 Product Promise](#v5-product-promise)
- [Subsystem Glossary](#subsystem-glossary)
  - [Engine Modules](#engine-modules)
  - [Game-Feature Plugins (one per mode-variant)](#game-feature-plugins-one-per-mode-variant)
- [High-Level Architecture](#high-level-architecture)
- [Project Layout](#project-layout)
- [Module Split](#module-split)
- [Gameplay Ability System (GAS) Layout](#gameplay-ability-system-gas-layout)
  - [Attribute Sets](#attribute-sets)
  - [Ability Categories](#ability-categories)
  - [Gameplay Effects](#gameplay-effects)
  - [Gameplay Tags](#gameplay-tags)
- [Animation Pipeline](#animation-pipeline)
- [Input Pipeline](#input-pipeline)
- [AI Perception, NPC Schedules, Crowd](#ai-perception-npc-schedules-crowd)
  - [Perception State Machine](#perception-state-machine)
  - [Stimuli Sources](#stimuli-sources)
  - [Cell-Specific NPC Behaviors](#cell-specific-npc-behaviors)
  - [NPC Schedule Architecture](#npc-schedule-architecture)
- [Honor / Karma / Paragon Bridge](#honor--karma--paragon-bridge)
  - [Per-Cell Local Axis](#per-cell-local-axis)
  - [Cross-Cell Meta-Axis](#cross-cell-meta-axis)
  - [Use of the Moral Compass](#use-of-the-moral-compass)
- [Combat Authority & Determinism](#combat-authority--determinism)
- [Client-Server Netcode (Open-World, PvP)](#client-server-netcode-open-world-pvp)
- [Rollback-Emulated Prediction (Spaceship PvP)](#rollback-emulated-prediction-spaceship-pvp)
- [Game Modes (GameFeatures Plugins)](#game-modes-gamefeatures-plugins)
- [Open-World Streaming (World Partition + Crowd)](#open-world-streaming-world-partition--crowd)
- [Procedural Generation Pipeline](#procedural-generation-pipeline)
- [Persistence & Profile](#persistence--profile)
  - [Save Categories](#save-categories)
  - [Save Format](#save-format)
  - [Cross-Device Save Sync](#cross-device-save-sync)
  - [Save Corruption Recovery](#save-corruption-recovery)
- [Online Services Backend](#online-services-backend)
- [Anti-Cheat](#anti-cheat)
- [Cross-Play & Cross-Progression](#cross-play--cross-progression)
- [Audio Pipeline](#audio-pipeline)
  - [Audio Plumbing](#audio-plumbing)
- [VFX Pipeline](#vfx-pipeline)
- [Cinematic Pipeline](#cinematic-pipeline)
- [UI / HUD Architecture](#ui--hud-architecture)
- [Telemetry & Analytics](#telemetry--analytics)
  - [Critical Events](#critical-events)
- [Build, Cook, Patch](#build-cook-patch)
- [Data Architecture](#data-architecture)
- [Live-Service & DLC](#live-service--dlc)
- [Accessibility](#accessibility)
- [Security, Privacy, Compliance](#security-privacy-compliance)
- [Observability, Evaluation, Release Gates](#observability-evaluation-release-gates)
- [Performance Budgets](#performance-budgets)
- [Testing, QA, Cert](#testing-qa-cert)
- [Content Pipeline & Source Control](#content-pipeline--source-control)
- [Creator Suite Architecture](#creator-suite-architecture)
- [Mind Palace Deduction Architecture](#mind-palace-deduction-architecture)
  - [Data Model](#data-model)
  - [Graph Operations](#graph-operations)
  - [Cross-Cell Linkage](#cross-cell-linkage)
  - [Cloud Sync](#cloud-sync)
  - [Mind Palace UI](#mind-palace-ui)
- [MotionScan Interrogation Architecture](#motionscan-interrogation-architecture)
  - [Capture Pipeline](#capture-pipeline)
  - [Interrogation Runtime](#interrogation-runtime)
  - [Interrogation Scoring](#interrogation-scoring)
- [Dialogue Wheel Architecture](#dialogue-wheel-architecture)
  - [Dialogue Authoring](#dialogue-authoring)
  - [Dialogue Runtime](#dialogue-runtime)
  - [State Integration](#state-integration)
- [Heist Planner Architecture](#heist-planner-architecture)
  - [Pre-Mission Planning](#pre-mission-planning)
  - [Execution Runtime](#execution-runtime)
  - [Three-Ending Logic](#three-ending-logic)
- [Spaceship Physics Architecture](#spaceship-physics-architecture)
  - [Newtonian Simulation](#newtonian-simulation)
  - [Gravity Zones](#gravity-zones)
  - [Ship Weapons](#ship-weapons)
  - [Ship Damage Model](#ship-damage-model)
- [Vehicle Library Architecture](#vehicle-library-architecture)
  - [Per-Class Tuning](#per-class-tuning)
  - [Vehicle Damage Model](#vehicle-damage-model)
- [Horse AI Architecture](#horse-ai-architecture)
  - [Per-Horse State](#per-horse-state)
  - [Gait Library](#gait-library)
  - [Saddlebag Inventory](#saddlebag-inventory)
- [Alchemy & Signs Architecture](#alchemy--signs-architecture)
  - [Alchemy Data](#alchemy-data)
  - [Signs Data](#signs-data)
- [Bestiary & Witcher-Sense Architecture](#bestiary--witcher-sense-architecture)
  - [Bestiary Data](#bestiary-data)
  - [Witcher-Sense Runtime](#witcher-sense-runtime)
- [Period-Authenticity Pipeline](#period-authenticity-pipeline)
  - [Bundle Data](#bundle-data)
  - [Runtime Swap](#runtime-swap)
  - [Bundle Authoring](#bundle-authoring)
- [Cross-Cell Persistence & Bureau XP](#cross-cell-persistence--bureau-xp)
  - [Bureau XP Ledger](#bureau-xp-ledger)
  - [Cross-Cell Unlocks](#cross-cell-unlocks)
  - [Bureau XP Persistence](#bureau-xp-persistence)
- [Launch Readiness](#launch-readiness)
- [Cross-References](#cross-references)

## V5 Product Promise

V5 ships as one coherent open-world narrative-action game that delivers
per-genre feel matching each of its 9 inspirational sources on its own terms,
held together by one shared roster ("Cross-Continuum Bureau"), one shared Mind
Palace deduction layer, one shared creator suite, and one shared online
backbone. The 9 inspirational franchises are enumerated in `V5_features.md`
features§"Purpose"; this document does not restate them. The architecture
supports five launch gameplay cells (Urban Crime, Period Drama, Frontier,
Monster Hunter, Sci-Fi), DLC cell expansion such as Brave New World Steampunk
Detective, and a cross-cell deduction layer 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
  open-world MP, co-op heists, and frontier posse; rollback-emulated prediction
  for tight twitch PvP (Sci-Fi ship duel, Urban deathmatch);
  offline-deterministic for single-player and co-op campaigns.
- Sharing one **AI Perception model** (`V5Perception`) across every NPC in every
  cell so a Hong Kong triad goon, a 1947 LA detective witness, a frontier
  outlaw, a hunter-cell drowner, and a sci-fi station guard all read stimuli
  from the same state machine.
- Sharing one **roster** (Bureau members, companions, NPCs) across cells via a
  unified Character data table; cell-specific overrides (period-correct face
  mesh; witcher-mutation eyes; sci-fi alien morphology) hang off the character
  record.
- Sharing one **Mind Palace deduction graph** across cells so evidence picked up
  in any cell can pair with evidence from any other to form cross-era
  deductions.
- Holding all five cells together with one online backbone (matchmaking,
  parties, friends, replays, leaderboards, anti-cheat) and one creator suite
  (Mission Editor, Heist Author, Case Author, Contract Author, Ship Loadout
  Author, Bestiary Author).

See `V5_features.md` features§"V5 Product Promise" for the full list.

## Subsystem Glossary

The names below are fixed vocabulary for V5; module names, namespaces, and asset
paths inherit from them.

Cell-count note: V5 ships **5 launch ruleset cells** (Urban, Period, Frontier,
Hunter, Sci-Fi), but the code's `EV5Cell` enum
(`V5/ue/Source/V5Core/Public/V5Types.h`) carries **7** values — the 5 launch
cells plus the Brave New World Steampunk Detective DLC cell (`Steampunk`, [P3]
`V5_TODOS.md` §139) and the cross-cell `MindPalace` meta-layer; per-cell
datasets and tests must size against `GetAllV5Cells()` (7), not a literal 5 or 6
(the 2026-05-31 audit traced 4 automation failures to exactly this mismatch).

### Engine Modules

| Module                   | Responsibility                                                                  |
| ------------------------ | ------------------------------------------------------------------------------- |
| **V5Core**               | Engine subsystems, save game, tags registry, dev cheats                         |
| **V5Gameplay**           | GAS abilities, attributes, gameplay effects, narrative-state machine            |
| **V5Open**               | Open-world streaming, traffic spawning, pedestrian density, weather             |
| **V5Vehicles**           | Cars, bikes, boats, planes, helos, period autos, wagons, horses                 |
| **V5Combat**             | Third-person gunplay, cover, ADS, ranged-power abilities                        |
| **V5Melee**              | Martial-arts melee, environmental finishers, blade parry, brawler               |
| **V5Investigation**      | Crime-scene examination, evidence pickup, photograph, recording                 |
| **V5Interrogation**      | Truth/doubt/lie facial-tell parser, dialogue branch under pressure              |
| **V5MindPalace**         | Cross-cell deduction graph, evidence chain, accusation system                   |
| **V5Dialogue**           | Dialogue-wheel, paragon/renegade morality, branching narrative state            |
| **V5Squad**              | Companion squad, loyalty missions, ship-hub interactions                        |
| **V5StarMap**            | Galaxy / system map navigation, FTL plotting, mission scattering                |
| **V5Spaceship**          | Newtonian flight, RCS, gravity zones, PDC/railgun/torpedo, damage               |
| **V5Alchemy**            | Potions, oils, bombs, decoctions, ingredient gather, brewing UI                 |
| **V5Signs**              | Five-sign elemental casting (rename), stamina cost, charge variants             |
| **V5MonsterHunt**        | Monster-sense, blood-trail tracking, bestiary, contract boards                  |
| **V5DeadEye**            | Slow-mo painted-shot system, target painting, charge meter                      |
| **V5Honor**              | Open-world reputation/honor/bounty rating, persistent NPC reactions             |
| **V5Hunting**            | Animal AI, tracking, perfect-pelt skinning economy, butchery                    |
| **V5Crowd**              | Civilian density, panic propagation, witness reporting, era body lang           |
| **V5Wanted**             | Star-rated police response, era-scaled (1899 marshal, 1947 LAPD…)               |
| **V5Heist**              | Heist planner: targets, crew, vehicles, escape routes, post-game cut            |
| **V5PeriodAuth**         | Per-era authenticity bundles (vehicles, fonts, props, signage, slang)           |
| **V5FaceCapture**        | MotionScan-equivalent facial capture pipeline + interrogation rig               |
| **V5Karaoke**            | Rhythm-game minigame (Sleeping Dogs lineage)                                    |
| **V5CardGame**           | Collectible-card minigame (gwent-style; rules re-derived)                       |
| **V5RadioTV**            | In-world radio, TV, podcasts, jukeboxes, in-game phone                          |
| **V5HorseAI**            | Horse bonding, gait library, saddlebag inventory, horse-care loop               |
| **V5Parkour**            | Free-running traversal (SD lineage) — ledge grab, vault, wall-run               |
| **V5LockpickHack**       | Lockpicking, safecracking, period telephone tap, sci-fi hacking                 |
| **V5Schedules**          | NPC daily routines, period workday rhythms, gang-camp chores                    |
| **V5Animation**          | AnimBP, motion matching, MetaHuman bind, IK, retargets, root motion             |
| **V5Input**              | Enhanced Input, drive/ride/fly/walk modes, dialogue-wheel cursor                |
| **V5Netcode**            | Client-server, AOI streaming, rollback for vehicle PvP, deterministic           |
| **V5Modes**              | Mode registry, per-cell ruleset gating, mode-specific HUD                       |
| **V5UI**                 | UMG / CommonUI front-end, mind palace view, dialogue wheel, hud                 |
| **V5Audio**              | MetaSounds pipeline, dynamic music, voice barks, period radio mix               |
| **V5VFX**                | Niagara muzzle/blood/debris, weather, signs FX, sci-fi powers FX                |
| **V5Cinematics**         | Sequencer-driven story beats, ME-style cinematic conversations                  |
| **V5Persistence**        | Save game, profile, currency ledger, mind-palace state, replays                 |
| **V5OnlineServices**     | Login, friends, parties, matchmaking, leaderboards, replays                     |
| **V5Telemetry**          | Event schema, batched sender, balance dashboards feed                           |
| **V5SteampunkDetective** | Brave New World Steampunk Detective DLC cell catalog, gadgets, cases            |
| **V5Editor**             | Mission editor, contract author, heist editor, ship-loadout editor              |
| **V5Procgen**            | Procedural side-quest generator, random encounters, monster-contract generation |
| **V5Hub**                | Ship/safehouse/camp hub: companion banter, upgrades, save points                |
| **V5Perception**         | Unified sight/hearing/suspicion model used by every NPC across cells            |
| **V5Tests**              | Automation specs, gauntlet drivers, golden-replay regression harness            |

### Game-Feature Plugins (one per mode-variant)

Each cell's mode set is a `GameFeatures` plugin so it can be enabled per build
target and DLC-gated post-launch. The plugin list is in `V5_features.md`
features§"Game-Feature Plugins (modular, hot-swap)". Plugins own their content
roots, asset-linter rules, and per-mode test coverage.

## High-Level Architecture

V5 is one shippable executable per target platform. The runtime stack:

```text
┌───────────────────────────────────────────────────────────────────┐
│                       V5 Game Executable                          │
│  ┌────────────────────────────────────────────────────────────┐   │
│  │  Front-end Shell (V5UI / CommonUI)                         │   │
│  │   • Main menu  • Cell select  • Companion app bridge       │   │
│  │   • Settings   • Mind Palace view (cross-cell)             │   │
│  └────────────────────────────────────────────────────────────┘   │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐      │
│  │  Urban  │ │  Period │ │ Frontier│ │  Hunter │ │  SciFi  │      │
│  │   GFP   │ │   GFP   │ │   GFP   │ │   GFP   │ │   GFPs  │      │
│  │ (heist +│ │ (Mafia +│ │  (RDR)  │ │(Witcher)│ │ (squad +│      │
│  │   SD)   │ │  Noire) │ │         │ │         │ │  ship)  │      │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘      │
│       │           │           │           │           │           │
│       └───────────┴───────────┴─┬─────────┴───────────┘           │
│                                 │                                 │
│  ┌──────────────────────────────▼─────────────────────────────┐   │
│  │  Shared Engine Modules                                     │   │
│  │  V5Core / V5Gameplay / V5Open / V5Vehicles / V5Combat /    │   │
│  │  V5Melee / V5Investigation / V5Interrogation /             │   │
│  │  V5MindPalace / V5Dialogue / V5Squad / V5StarMap /         │   │
│  │  V5Spaceship / V5Alchemy / V5Signs / V5MonsterHunt /       │   │
│  │  V5DeadEye / V5Honor / V5Hunting / V5Crowd / V5Wanted /    │   │
│  │  V5Heist / V5PeriodAuth / V5FaceCapture / V5Karaoke /      │   │
│  │  V5CardGame / V5RadioTV / V5HorseAI / V5Parkour /          │   │
│  │  V5LockpickHack / V5Schedules / V5Animation / V5Input /    │   │
│  │  V5Netcode / V5Modes / V5UI / V5Audio / V5VFX /            │   │
│  │  V5Cinematics / V5Persistence / V5OnlineServices /         │   │
│  │  V5Telemetry / V5Editor / V5Procgen / V5Hub /              │   │
│  │  V5Perception / V5Tests                                    │   │
│  └──────────────────────────────┬─────────────────────────────┘   │
│  ┌──────────────────────────────▼─────────────────────────────┐   │
│  │  Unreal Engine 5.5 LTS Runtime                             │   │
│  │  Lumen GI • Nanite • MetaHuman • Niagara • MetaSounds •    │   │
│  │  ChaosVehicles • ChaosDestruction • World Partition •      │   │
│  │  Mass Entity • PCG • Motion Matching • Sequencer •         │   │
│  │  GAS • Enhanced Input • CommonUI • ModelViewViewModel      │   │
│  └────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────┘
              │
              │  (network)
              │
┌──────────────▼────────────────────────────────────────────────────┐
│ V5 Online Services Backend                                        │
│ Auth • Friends • Parties • Matchmaking • Leaderboards •           │
│ Replays • Telemetry • Anti-Cheat • Crash Reporting •              │
│ Companion App bridge • Mind Palace cloud-sync •                   │
│ DSAR (compliance) • Workshop publishing                           │
└───────────────────────────────────────────────────────────────────┘
```

The Mind Palace is conceptually a **side-car module** to all five cells: each
cell pushes evidence events into V5MindPalace; the Mind Palace UI overlays the
cell-of-the-moment but operates on its own data graph.

## Project Layout

```text
V5/
├── V5_features.md                       (this companion)
├── V5_TODOS.md                          (backlog)
├── V5_ARCHITECTURE.md                   (this doc)
├── V5_DEPENDENCIES.md                   (dep registry)
├── ue/                                  (Unreal Engine project)
│   ├── V5.uproject
│   ├── Source/
│   │   ├── V5/                          (primary game module)
│   │   ├── V5Core/
│   │   ├── V5Gameplay/
│   │   ├── V5Open/
│   │   ├── V5Vehicles/
│   │   ├── V5Combat/
│   │   ├── V5Melee/
│   │   ├── V5Investigation/
│   │   ├── V5Interrogation/
│   │   ├── V5MindPalace/
│   │   ├── V5Dialogue/
│   │   ├── V5Squad/
│   │   ├── V5StarMap/
│   │   ├── V5Spaceship/
│   │   ├── V5Alchemy/
│   │   ├── V5Signs/
│   │   ├── V5MonsterHunt/
│   │   ├── V5DeadEye/
│   │   ├── V5Honor/
│   │   ├── V5Hunting/
│   │   ├── V5Crowd/
│   │   ├── V5Wanted/
│   │   ├── V5Heist/
│   │   ├── V5PeriodAuth/
│   │   ├── V5FaceCapture/
│   │   ├── V5Karaoke/
│   │   ├── V5CardGame/
│   │   ├── V5RadioTV/
│   │   ├── V5HorseAI/
│   │   ├── V5Parkour/
│   │   ├── V5LockpickHack/
│   │   ├── V5Schedules/
│   │   ├── V5Animation/
│   │   ├── V5Input/
│   │   ├── V5Netcode/
│   │   ├── V5Modes/
│   │   ├── V5UI/
│   │   ├── V5Audio/
│   │   ├── V5VFX/
│   │   ├── V5Cinematics/
│   │   ├── V5Persistence/
│   │   ├── V5OnlineServices/
│   │   ├── V5Telemetry/
│   │   ├── V5Editor/
│   │   ├── V5Procgen/
│   │   ├── V5Hub/
│   │   ├── V5Perception/
│   │   └── V5Tests/
│   ├── Plugins/                         (GameFeatures + 3rd-party)
│   │   ├── V5Mode_Urban_HeistCity/
│   │   ├── V5Mode_Urban_StreetTriad/
│   │   ├── V5Mode_Urban_Online/
│   │   ├── V5Mode_Period_MadeMan/
│   │   ├── V5Mode_Period_ViceSquad/
│   │   ├── V5Mode_Period_InterrogationKit/
│   │   ├── V5Mode_Frontier_OutlawTrail/
│   │   ├── V5Mode_Frontier_Online/
│   │   ├── V5Mode_Hunter_WitchersPath/
│   │   ├── V5Mode_Hunter_ContractBoard/
│   │   ├── V5Mode_Hunter_CardGame/
│   │   ├── V5Mode_SciFi_GalacticSquad/
│   │   ├── V5Mode_SciFi_HardVacuum/
│   │   ├── V5Mode_SciFi_FleetCoop/
│   │   ├── V5Mode_Detective_MindPalace/
│   │   ├── V5Mode_Detective_ColdCases/
│   │   ├── V5Mode_SpecOps_Coop/
│   │   ├── V5Mode_HordeDefense_PerCell/
│   │   ├── V5Mode_Roguelike_HunterRun/
│   │   ├── V5Mode_Editor_Mission/
│   │   ├── V5Mode_Editor_HeistAuthor/
│   │   ├── V5Mode_Editor_CaseAuthor/
│   │   ├── V5Mode_Editor_Workshop/
│   │   ├── V5Mode_Replay/
│   │   ├── V5Mode_Spectator/
│   │   ├── V5Mode_Training_Range/
│   │   ├── V5Mode_Lobby_BureauHQ/
│   │   └── V5Mode_PhotoMode/
│   ├── Config/
│   │   ├── DefaultEngine.ini
│   │   ├── DefaultGame.ini
│   │   ├── DefaultInput.ini
│   │   ├── DefaultGameplayTags.ini
│   │   └── DefaultEditor.ini
│   ├── Content/                         (asset packages, per-cell roots)
│   │   ├── V5Core/
│   │   ├── V5Urban/
│   │   ├── V5Period/
│   │   ├── V5Frontier/
│   │   ├── V5Hunter/
│   │   ├── V5SciFi/
│   │   ├── V5MindPalace/
│   │   ├── V5Shared/
│   │   ├── V5UI/
│   │   ├── V5Cinematics/
│   │   ├── V5Audio/
│   │   ├── V5VFX/
│   │   └── Localization/V5/             (LOC packs per language)
│   └── Platforms/                       (per-platform overrides)
│       ├── Windows/
│       ├── PS5/
│       ├── PS5Pro/
│       ├── XSX/
│       ├── XSS/
│       ├── Switch2/
│       ├── Mac/
│       ├── Linux/
│       └── iOS/
├── balance/                             (per-cell balance spreadsheets)
│   ├── urban/
│   ├── period/
│   ├── frontier/
│   ├── hunter/
│   ├── scifi/
│   ├── shared/
│   ├── period-auth/                     (era bundles 1930s/47/68)
│   └── schema/
├── docs/
│   ├── README.md
│   ├── agent-execution.md
│   ├── ai/
│   ├── ci/
│   ├── decisions/                       (ADRs — see V5_TODOS.md §1.2)
│   ├── integration/
│   └── perforce-migration.md
├── legal/
│   ├── platform-cert-bans.json
│   └── rating-boards.json
├── services/                            (online services backend)
│   ├── auth/
│   ├── friends/
│   ├── parties/
│   ├── matchmaking/
│   ├── leaderboards/
│   ├── replays/
│   ├── telemetry/
│   ├── anti-cheat/
│   ├── crash-reporting/
│   ├── companion-app-bridge/
│   ├── mindpalace-cloud-sync/
│   ├── workshop/
│   ├── compliance-dsar/
│   ├── live-service-calendar/
│   ├── balance-ledger/
│   └── faction-rep/
├── tools/
│   ├── missions/                        (mission authoring + linter)
│   ├── bestiary/                        (bestiary authoring)
│   ├── period-auth/                     (era bundle authoring)
│   ├── starmap/                         (galaxy authoring)
│   ├── broadcast/                       (spectator + broadcast)
│   ├── release/                         (cooker, packager, signer)
│   └── validate-v5-docs.py              (doc linter)
├── web/                                 (marketing site)
│   ├── app/
│   ├── components/
│   └── public/
└── loc/                                 (localization source-of-truth)
    ├── en-US/
    ├── en-UK/
    ├── fr/
    ├── de/
    ├── es-LATAM/
    ├── es-ES/
    ├── it/
    ├── pt-br/
    ├── ja/
    ├── ko/
    ├── zh-Hans/
    ├── zh-Hant/
    ├── ru/
    ├── ar/
    ├── pl/
    └── tr/
```

Per-cell content roots are independent so a "no-frontier" build (e.g., Switch 2
SKU that omits the frontier cell) can ship without dragging the frontier asset
budget.

## Module Split

The engine modules are split along three axes:

- **Cross-cell shared** — V5Core, V5Gameplay, V5UI, V5Audio, V5VFX, V5Animation,
  V5Input, V5Netcode, V5Modes, V5Persistence, V5OnlineServices, V5Telemetry,
  V5Editor, V5Perception, V5Crowd, V5Schedules, V5Cinematics, V5Tests.
- **Per-cell engine** — V5Open (urban + frontier + hunter + scifi), V5Vehicles
  (all cells), V5Combat (all cells), V5Melee (urban + frontier + hunter),
  V5DeadEye (frontier; reused as Reflex in urban + Tactical Time in scifi),
  V5Honor (frontier; bridges to urban Cop/Triad + scifi Paragon/Renegade),
  V5Hunting (frontier + hunter), V5Wanted (urban + period + frontier), V5Heist
  (urban), V5HorseAI (frontier + hunter), V5Parkour (urban; reused in hunter),
  V5Alchemy + V5Signs + V5MonsterHunt (hunter), V5Spaceship + V5StarMap +
  V5Squad (scifi), V5FaceCapture + V5Interrogation (period; reusable in any
  cell), V5PeriodAuth (period; era-bundle abstraction), V5Karaoke (urban),
  V5CardGame (hunter), V5RadioTV (urban + period + frontier).
- **Cross-cell layer** — V5MindPalace (sherlock; pushes from all cells),
  V5Dialogue (used in scifi primarily; reusable everywhere), V5Investigation
  (period + hunter; pushes to MindPalace), V5LockpickHack (urban + scifi +
  period; mode-specific UI variants).

The module `.Build.cs` files declare these inter-module dependencies explicitly.
The cross-cell shared modules forbid any per-cell module dependency (one-way
enforcement).

## Gameplay Ability System (GAS) Layout

All combat / power abilities go through GAS.

### Attribute Sets

- `V5_AttributeSet_Combat` — Health, MaxHealth, Stamina, MaxStamina,
  ArmorPhysical, ArmorEnergy, MovementSpeed, AttackSpeed, CritChance,
  CritMultiplier, ToxicityCurrent, ToxicityMax, ManaCurrent, ManaMax.
- `V5_AttributeSet_Honor` — HonorScore, Bounty, ParagonScore, RenegadeScore,
  CopRep, TriadRep, FamilyRep, OutsiderRep, WitcherHumanity.
- `V5_AttributeSet_Ship` — Hull, HullMax, Reactor, ReactorMax, ReactionMass,
  ReactionMassMax, ThrustForward, ThrustLateral, TorpedoCount, RailgunSlugCount,
  PDCAmmo.
- `V5_AttributeSet_Vehicle` — Fuel, FuelMax, Damage, DurabilityFront,
  DurabilityRear, TireCondition[4], EngineCondition.

### Ability Categories

- `V5_Ability_Sign_*` (5 signs × upgrade tiers) — hunter cell.
- `V5_Ability_DeadEye` — frontier cell; tier 1/2/3 in feature doc.
- `V5_Ability_Biotic_*` — scifi cell.
- `V5_Ability_Tech_*` — scifi cell.
- `V5_Ability_Melee_*` — urban + frontier + hunter.
- `V5_Ability_Heist_RolePower_*` — urban heist crew-role specifics.
- `V5_Ability_InterruptDialogue_*` — scifi paragon / renegade interrupts.

### Gameplay Effects

- Damage instant (`V5_GE_Damage_Physical`, `V5_GE_Damage_Energy`,
  `V5_GE_Damage_Bleed`, etc.).
- Duration buffs (`V5_GE_Buff_Stamina_Regen`, `V5_GE_Buff_SignPower`,
  `V5_GE_Buff_Toxicity_Resist`).
- Period (`V5_GE_Period_OilDamage_Specter`).
- Persistent (`V5_GE_Persistent_HonorMod`).

### Gameplay Tags

- Cell tag — `Cell.Urban`, `Cell.Period`, etc.
- Mode tag — `Mode.Urban.HeistCity`, etc.
- State tag — `State.Combat`, `State.Investigation`, `State.Dialogue`,
  `State.Spaceship.Burn`, `State.Spaceship.Coast`, etc.
- Threat tag — `Threat.Civilian`, `Threat.Hostile`, `Threat.Bounty`,
  `Threat.Monster.Specter`, etc.

## Animation Pipeline

V5 animation is **motion-matched** for traversal modes (walk, run, crouch,
horse-ride, climb, parkour, zero-G locomotion) and **AnimBP-driven** for combat
moves, dialogue cinematics, and signature actions.

- **AnimBP per cell** — base shared AnimBP with per-cell traits.
- **Motion-matching trajectory:** the 1-second future intent (from input) plus
  the 0.5 s past trajectory feeds the matcher's pose-blender.
- **MetaHuman bind:** the 28 **principals** are bespoke MetaHuman builds, each
  driven by an individually-scanned actor. A "principal" is a campaign-carrying
  character: the 11 playable protagonists plus the 17 most story-central
  companions (those who anchor a critical-path arc and receive full
  cinematic-grade facial capture). The remaining named companions and the ~1180
  major NPCs use per-character composed MetaHuman pieces (parametric assembly
  from the MetaHuman parts library, not a bespoke scan); ambient crowd NPCs
  (~3000) use generic composed MetaHuman crowds.
- **IK chains:** foot-IK on uneven terrain; hand-IK for ladder / cover /
  weapon-grip; head-IK for look-at; full-body IK for horse-mount / sit-in-
  cockpit / boarding-airlock alignment.
- **Retargets:** MetaHuman → Quadruped (horse, wildlife) skeleton retargets;
  alien-morphology retargets in sci-fi cell.
- **Root motion** for cinematic-quality finishers (env-finisher in urban cell,
  witcher-finisher in hunter cell, dead-eye finisher in frontier cell); root
  motion is server-authoritative.

The motion-matching pose-database is per-cell to keep memory predictable on
Switch 2.

## Input Pipeline

V5 uses **Enhanced Input** with cell-specific Input Mapping Contexts (IMCs).
Switching cells swaps the IMC stack:

- `IMC_Shared_Menu`
- `IMC_Shared_Dialogue` (wheel)
- `IMC_Urban_Walk` / `IMC_Urban_Vehicle` / `IMC_Urban_Combat` /
  `IMC_Urban_Parkour` / `IMC_Urban_Melee`
- `IMC_Period_Walk` / `IMC_Period_Investigate` / `IMC_Period_Interrogate`
- `IMC_Frontier_Walk` / `IMC_Frontier_Mount` / `IMC_Frontier_DeadEye` /
  `IMC_Frontier_Hunt`
- `IMC_Hunter_Walk` / `IMC_Hunter_Mount` / `IMC_Hunter_Sign` /
  `IMC_Hunter_Alchemy`
- `IMC_SciFi_Walk` / `IMC_SciFi_Combat_Squad` / `IMC_SciFi_Pilot` /
  `IMC_SciFi_RCS` / `IMC_SciFi_ZeroG`
- `IMC_MindPalace`

Cross-platform input:

- Mouse + keyboard (Windows, macOS, Linux).
- Controller (DualSense, Xbox, Switch 2 Joy-Cons).
- Adaptive Controller (PS5 / Xbox).
- HOTAS / Joystick (Hard Vacuum cockpit; Windows + Mac).
- Racing wheel (urban + frontier driving).
- Touch (iPad — Mind Palace primary; in-cell touch via on-screen-stick).
- VR controllers (PSVR2 cockpit; Quest 3 spectator; Vision Pro; Hunter VR
  Full-Cell).

Dialogue-wheel cursor is the same wheel input across all five cells.

## AI Perception, NPC Schedules, Crowd

A **single** `V5Perception` module powers all NPC perception across all cells.
Cell-specific data drives behavior; the state machine and stimulus plumbing are
shared.

### Perception State Machine

```text
[Idle] ──sight/sound──> [Curious] ──confirm──> [Alert] ──visual contact──> [Hostile]
   ▲                       │                       │
   │                       │ time-out              │ resolution
   └───────────────────────┴───────────────────────┘
```

### Stimuli Sources

- Sight cones (per-NPC vector + half-angle + range + per-cell tuning).
- Hearing radii (per-NPC range, with sound-absorption by walls).
- Witness reports (NPC tells another NPC at <12 m range).
- Player-attributed events (gunshot, vehicle horn, alarm trigger).

### Cell-Specific NPC Behaviors

- Urban civilians: 200-NPC streaming radius; flee-on-gunshot; report to nearest
  cop within 90 s; record on phone (turning them into a "wanted-visual"
  trigger).
- Urban triads (Sleeping Dogs): 8-NPC fight squad; engage if face/triad
  threshold crossed; environmental finisher response.
- Period civilians (1947): 120-NPC streaming radius; period-correct panic
  body-language; period-correct yelling vocab.
- Period detectives (Vice Squad): partner banter triggers on Mind-Palace state
  changes.
- Frontier civilians: 40-NPC streaming radius (towns); 6-NPC roaming
  (wilderness); honor-dependent greetings.
- Frontier law enforcement: marshal + posse spawn at bounty threshold;
  star-rating analog to GTA's, scaled to 1899 response.
- Hunter NPCs: village watch + lord's guard + monster-class enemies;
  bestiary-driven combat AI.
- Sci-Fi NPCs: companion AI (in-squad); AI-persona companion that learns player
  choices for Kade Roe in the sci-fi cell only; station-civilian crowd;
  faction-patrol ship AI; boarding-marine combat AI.

### NPC Schedule Architecture

- Per-NPC `V5_NPC_Schedule` data table row: home location, work location, shift
  start/end, lunch location, evening venue, sleep location.
- Time-of-day driver: 48-minute in-game day; schedules tick every 5 in-game
  minutes.
- Distance-of-detail: NPCs > 200 m away simulated as schedule-position-only (no
  per-frame tick); NPCs > 600 m only re-located on day-boundary.
- Period authenticity: 1899 schedules use sunrise-to-sundown work cycles (no
  electric light); 1947 schedules use 8-hour shifts; modern urban uses 24-hour
  cycle (some NPCs are night-shift).

## Honor / Karma / Paragon Bridge

A meta-axis system mapping each cell's local morality axis to a unified "moral
compass" used for cross-cell Mind-Palace gating and Bureau XP.

### Per-Cell Local Axis

- Urban: Cop / Triad axis (-100 to +100). Cop +1 per civilian helped; Triad +1
  per gang favor.
- Urban (heist city): Lawful / Outlaw axis with bounty escalation.
- Period (Mafia): Family / Outsider axis (-100 to +100). Family +1 per gang
  loyalty action; Outsider +1 per gang-betraying choice.
- Period (Noire): Brilliant / Average / Poor case rating (no axis; rating per
  case).
- Frontier: Honor / Bounty axis (Honor -100 to +100, Bounty $-amount).
- Hunter: Witcher Humanity (a single 0-100 score; rises with empathetic choices,
  falls with monstrous behavior).
- Sci-Fi: Paragon / Renegade (independent meters 0-100).

### Cross-Cell Meta-Axis

The cross-cell meta-axis is computed at session join and is never persisted as
canonical state — it is always derived from the per-cell axes:

```text
LightScore = max(0, CopRep)/100 * w_urban
           + max(0, FamilyRep)/100 * w_period_made
           + caseRating_avg / 4 * w_period_vice
           + max(0, HonorScore)/100 * w_frontier
           + WitcherHumanity/100 * w_hunter
           + ParagonScore/100 * w_scifi
DarkScore  = max(0, -CopRep + TriadRep)/100 * w_urban
           + max(0, -FamilyRep + OutsiderRep)/100 * w_period_made
           + (4 - caseRating_avg) / 4 * w_period_vice
           + max(0, -HonorScore)/100 * w_frontier
           + (100 - WitcherHumanity)/100 * w_hunter
           + RenegadeScore/100 * w_scifi
MoralCompass = LightScore - DarkScore         // range ~[-1, +1]
```

Default weights are 1.0; per-mission-arc weight overrides allowed for
narrative-anchor missions.

### Use of the Moral Compass

- Cross-cell Mind-Palace gating: certain deductions require Light > 0.4 or
  Dark > 0.4.
- Bureau XP: high-magnitude compass (either direction) earns Bureau XP faster
  than zero-magnitude.
- Companion dialogue: companions react to compass over time. Galactic Squad's
  Full-Vision AI-persona companion keeps Kade Roe's learned player-choice state
  in the Sci-Fi local profile only and blocks cross-cell training.

## Combat Authority & Determinism

Combat authority is per-cell:

- Open-world cells (Urban, Frontier, Sci-Fi-Squad, Hunter): server-
  authoritative for damage, gameplay-effects, position; client-predicted for
  movement, input, animation montage.
- Period cell: single-player only; fully client-authoritative.
- Sci-Fi Hard Vacuum: 8-frame rollback prediction for ship-to-ship combat (60 Hz
  tick); torpedo/PDC simulation deterministic across rollback window.
- Mind Palace: client-authoritative; cloud-sync periodically for cross-device.

Determinism rules:

- All gameplay random numbers go through a seeded `V5_PRNG` (xoshiro 256+); seed
  is part of game-state.
- Floating-point arithmetic is constrained to fp-strict in deterministic paths
  (deterministic-lockstep was considered for Urban heist but abandoned —
  client-server + lag-comp was chosen).
- Save game replay determinism is opt-in; matches that opt in have a replay-file
  with full input stream + initial RNG seed.
- Replay packets use exact binary canonicalization, SHA-256, HMAC-SHA256,
  bounded lifetime, and a single-use base64url nonce. Runtime acceptance fails
  closed unless external key custody and a durable atomic nonce consumer both
  return receipt IDs; transient key copies are cleared after verification.

## Client-Server Netcode (Open-World, PvP)

V5 uses Epic's **Iris replication** (NetDriver V2) for open-world multiplayer.

- Server tick: 30 Hz (Urban, Frontier); 60 Hz (Sci-Fi capital raid).
- Client send: 60 Hz inputs.
- Area-of-Interest (AOI) streaming: per-cell AOI radii (Urban: 300 m; Frontier:
  500 m; Sci-Fi: 12 km).
- Per-actor replication priority: critical (player + nearby NPC), important
  (heist target, vehicle in encounter), background (distant schedule-only NPC).
- Bandwidth budget: 64 kbps avg / 256 kbps burst per client.
- Lag compensation: 200 ms history window; server rewinds for hit validation.
- Host migration: 2-second cap; mid-mission player elected new host.
- Server providers: ALL three first-party (PSN, XBL, Steam Datagram Relay) + AWS
  GameLift for cross-platform.

## Rollback-Emulated Prediction (Spaceship PvP)

For tight twitch PvP (Sci-Fi ship duel; Urban deathmatch), V5 uses an 8-frame
rollback prediction model.

- Each client predicts forward 8 frames assuming "no new input from remote."
- On packet arrival from remote, if prediction mismatches actual input, rollback
  occurs.
- Rollback rebuilds simulation from the last confirmed frame using authoritative
  inputs.
- Visuals "snap" to rolled-back state for 1 frame; physics-particles and audio
  cues do NOT replay (they're cosmetic).

Specific rules:

- PDC tracking is rollback-aware; rolled-back PDC misses are visualized as "PDC
  miss" particles to reduce visual confusion.
- Torpedo trajectories are deterministic given initial conditions; no rollback
  needed.
- Boarding-marine fights use the same 8-frame rollback as Urban deathmatch.

## Game Modes (GameFeatures Plugins)

Each game mode is a GameFeatures plugin. See `V5_features.md`
features§"Game-Feature Plugins (modular, hot-swap)" for the catalog.

The active plugin set per session is driven by:

- The selected campaign + cell (one cell-specific plugin enabled).
- The selected sub-mode (e.g., online vs. offline).
- The selected ruleset (e.g., default vs. modded).

Plugin enable order is deterministic; plugins declare dependencies on shared
modules (V5Core, V5Gameplay, ...) explicitly.

## Open-World Streaming (World Partition + Crowd)

V5 uses **World Partition** for all open-world cells.

- Cell size: 256 m × 256 m per partition cell.
- HLOD: 4 levels (HLOD0 = full, HLOD3 = silhouette at 2 km).
- Streaming source: player + companions + active mission markers.
- Data-layers: time-of-day variants, weather variants, era-bundle swaps (period
  cell), faction-state variants (sci-fi cell).
- Pre-warm: critical 3×3 partition area pre-loaded at mission start.

Crowd streaming (V5Crowd + Mass Entity):

- Mass Entity for population density; each NPC is a lightweight entity until
  promoted to full character pawn within interaction radius.
- Promotion threshold: 18 m for "named" NPCs; 30 m for generic; 60 m for
  ambient.
- Cell-specific population: Urban ~250 within 100 m radius; Period 120; Frontier
  40 (towns), 6 (wilds); Hunter 60 (towns), 10 (wilds); Sci-Fi 80 (stations), 30
  (ship interior).

## Procedural Generation Pipeline

V5 uses **PCG (Procedural Content Generation)** for:

- **Procedural side-quests** — V5Procgen seeds quests from a per-cell pattern
  library (talk-to-NPC, escort, hunt, scavenge, race).
- **Random encounters** (Frontier cell) — 320 encounter templates feed the
  encounter director.
- **Monster contracts** (Hunter cell) — alderman posts a procedurally seeded
  contract every 36 in-game hours.
- **Loot tables** — weighted random with biome / faction modifiers.
- **Galaxy generation** (Sci-Fi cell) — authored 32 systems, but per-system
  planetary detail (mineral hotspots, anomaly placement) is PCG.
- **City decoration** (all open-world cells) — PCG places ambient props (trash,
  posters, period-correct signage) per partition cell.

PCG outputs are deterministic given seed; persisted as part of save state.

### Bounded gameplay AI Director

`V5Gameplay` owns `UV5AIDirectorSubsystem`, an always-available
`UGameInstanceSubsystem` whose portable decision core is `V5AIDirectorCore.h`.
Encounter systems submit complete, monotonically sequenced performance windows
through `EvaluateAndApply`; the subsystem returns one policy-bound pressure
scalar and retains the exact decision as bounded telemetry.

The director is deliberately constrained:

- adaptation is allowed only in PvE outside scripted boss phases and is forced
  to its neutral scalar in PvP, Trials, Speedrun, or player-disabled sessions;
- invalid, incomplete, non-finite, or replayed observations fail closed;
- scalar floors, ceilings, maximum step size, a pressure deadband, and a minimum
  adjustment interval are policy inputs and are revalidated on every decision;
- signed operator receipts are mandatory for pause, fixed override, rollback,
  and release, with a separate control audit retained in memory; and
- no director decision changes achievement rules, PvP balance, authored facts,
  quest truth, rights, clearance, or release authority.

The core is deterministic and provider-independent. It is an executable baseline
and safety boundary, not evidence of a live model/provider decision. Release
evidence must still come from the exact UE runtime/cook and human control
exercises required by the V5 authored-world gate.

## Persistence & Profile

Save data per cell is namespaced; cross-cell shared state lives in a separate
slot.

### Save Categories

- `Profile_<accountId>.json` — account-level meta: Bureau XP, completed cells,
  unlocked cosmetics.
- `Slot_<slotId>_Urban.sav` — Urban cell state.
- `Slot_<slotId>_Period.sav` — Period state (Made Man + Vice Squad in one slot).
- `Slot_<slotId>_Frontier.sav` — Frontier state.
- `Slot_<slotId>_Hunter.sav` — Hunter state.
- `Slot_<slotId>_SciFi.sav` — Sci-Fi state.
- `Slot_<slotId>_MindPalace.sav` — Mind Palace deduction graph state.
- `Slot_<slotId>_Manifest.json` — points to active cell saves.

### Save Format

- USTRUCT-based with archive versioning.
- Compressed with Oodle Kraken (high compression ratio).
- Encrypted with per-account key derived from platform auth token.
- Cloud-synced via platform cloud-save APIs.

### Cross-Device Save Sync

- Companion app reads Mind Palace + cosmetics and, in Year 1, queues append-only
  Mind Palace `add-clue` / `annotate-clue` drafts through the companion bridge;
  drafts reconcile through Mind Palace graph sync rather than direct save
  mutation.
- Cloud-sync via V5OnlineServices.

### Save Corruption Recovery

- Triple-redundant saves: current, previous, fallback (3 generations).
- On corrupt save detection, fall back to previous generation automatically with
  user notification.

## Online Services Backend

The V5OnlineServices microservices live under `apps/v5/`.

| Service               | Owns                                                   |
| --------------------- | ------------------------------------------------------ |
| auth                  | Single sign-on, OAuth, JWT issuance, refresh           |
| friends               | Friend graph, cross-platform                           |
| parties               | Group management, invite, ready-check                  |
| matchmaking           | Per-cell MM with skill rating + region + ping          |
| leaderboards          | Per-cell, per-mode leaderboards with anti-cheat checks |
| replays               | Replay upload, download, share, retention, AI reels    |
| telemetry             | Event ingestion, schema validation, batched delivery   |
| anti-cheat            | EAC integration, ML classifier signals, ban triage     |
| crash-reporting       | Crash dump ingestion, symbolication, dedup, alerting   |
| companion-app-bridge  | API for companion app; reads from canonical services   |
| mindpalace-cloud-sync | Cross-device Mind Palace state sync                    |
| workshop              | Mod upload, version, rating, moderation                |
| compliance-dsar       | GDPR / CCPA data-portability flows                     |
| live-service-calendar | Seasonal events, contract rotation, balance updates    |
| balance-ledger        | Public audit log of balance changes                    |
| faction-rep           | Sci-Fi faction reputation persistence                  |

Each service is implemented in TypeScript / NestJS, deployed via the Oshun
monorepo standard (the same `apps/` and `libs/` layout the other Oshun domains
follow); per-service Docker images; multi-region via Kubernetes; database per
service (Postgres for relational; Redis for sessions; ClickHouse for telemetry).

## Anti-Cheat

V5 ships **Easy Anti-Cheat (EAC)** + custom signal layer.

- EAC kernel module on Windows (signed driver).
- EAC userland on Mac / Linux / consoles.
- Custom signal layer:
  - Server-side aim plausibility (impossible-angle detection).
  - Aimbot pattern detection (sub-tick aim snap).
  - Wall-hack via line-of-sight history mismatch.
  - Speed-hack via position-delta vs. max-speed.
  - Auto-fire pattern detection.
- ML classifier (`V5_AntiCheat_ML`) running on telemetry stream; flags candidate
  cheaters; human review.
- Three-strike appeal flow:
  - 1st flag: 24-hour shadow-mute (matched only with other flagged players).
  - 2nd flag: 7-day MP ban.
  - 3rd flag: 30-day MP ban + manual review for permaban.
- Appeals via companion app; SLA 7 days.

## Cross-Play & Cross-Progression

All 9 platforms crossplay on launch.

- Single account ID; per-platform linked credentials.
- Cross-progression: profile, cosmetics, Bureau XP, Mind Palace state.
- Per-cell crossplay opt-out (Sci-Fi spaceship PvP is opt-in for console due to
  APM differential vs. K&M).

## Audio Pipeline

V5 audio is fully MetaSounds-based.

- Music: dynamic music graph per-cell with adaptive transitions (combat →
  exploration → cinematic).
- Voice: 4 SKUs get full principal-grade lipsync (en-US, fr, de, es-LATAM); 8
  SKUs get lipsync-light (en-UK, es-ES, it, pt-br, ja, ko, zh-Hans, zh-Hant); 4
  SKUs are text-only (ru, ar, pl, tr). 16 launch language packs total.
- VO recording pipeline: in-house at LA + London + Tokyo studios + 4 outsourced
  country-specific.
- Period radio (Urban + Period cells): full original-IP music library (no
  licensed tracks unless specifically cleared per §82).
- Frontier music: 3 composers contributing 90 minutes each of frontier-
  authentic period score.
- Hunter music: medieval-Slavic-influenced original score.
- Sci-Fi music: electronic + orchestral hybrid.
- Spatial audio: Dolby Atmos / Sony 360 / Steam Audio.
- DualSense haptic audio for weapons + horse-trot + gravity transition.

### Audio Plumbing

- `V5Audio_RouterSubsystem` routes 3D-positioned voices through MetaSounds
  graphs per platform.
- `V5Audio_DialogueDirector` ducks music + radio during dialogue + barks.
- `V5Audio_PeriodRadio` is a per-cell MetaSound that drives the in-vehicle radio
  mix.

## VFX Pipeline

V5 VFX is Niagara-based.

- Muzzle flash, blood spurt, debris — shared base systems with per-era tinting
  and shape variants.
- Witcher sign FX: 5 distinct Niagara systems with charge-tier variants.
- Mass Effect biotic / tech FX: per-power Niagara systems.
- Weather: rain, snow, dust storm, fog, solar-flare (sci-fi).
- Vehicle damage: ChaosDestruction for vehicle deformation; Niagara particle on
  hit.
- Cinematic FX: bespoke Niagara per cinematic.

## Cinematic Pipeline

V5 cinematics use Sequencer.

- 4 cinematic styles, one per cell-cluster:
  - Urban + Period: noir cinematography style (high-contrast lighting, Dutch
    angles).
  - Frontier + Hunter: epic-vista cinematography (wide lens, slow push).
  - Sci-Fi: handheld documentary + cinematic widescreen alternation (Expanse
    style).
- Pre-rendered cinematics: 4K master in DPX / OpenEXR; encoded to AV1
  - H.265 fallback per platform.
- In-engine cinematics: Sequencer + ChooserTable for cinematic-finisher variant.
- Per-companion dialogue camera library (~200 camera setups per companion).
- Cinematic Director Mode: `V5Cinematics` owns a director-mode video-authoring
  tool with five timeline tracks, twelve source clips, eleven cuts, a cut
  inspector, Replay Theater import, Sequencer round-trip, and Movie Render Queue
  export presets in `cinematic-director-mode-manifest.json`.
- Cross-Cell Replay Editor: `V5Mode_Replay` surfaces the replay-editor manifest
  while `V5Cinematics` owns typed clip, splice, and export contracts. The editor
  can splice clips from any cell into a single merged export with source replay
  hashes, timeline JSON, privacy-scrubbed metadata, and
  `fullvision_cross_cell_replay_editor_manifest.json`.
- Period Documentary Year-1 uses `V5Cinematics` for a 42-minute
  behind-the-scenes documentary cinematic and an in-game documentary viewer with
  chapter select, still gallery, captions, and director-commentary toggles,
  declared in `year1_period_documentary_manifest.json`.

## UI / HUD Architecture

V5 UI uses **CommonUI** + **ModelViewViewModel** for data binding.

- Main menu shell shared across cells.
- Per-cell HUD vocabularies (urban: wanted-stars; period: investigation
  notebook; frontier: honor + bounty + horse-stamina; hunter: signs + toxicity +
  alchemy quickslots; sci-fi: ship-stats + crew status + dialogue wheel).
- Mind Palace UI: 3D volumetric "memory room"; CommonUI shell with Niagara
  particle for evidence orbs.
- Dialogue wheel UI: shared across all cells; per-cell flavor for spoke colors
  and icons.
- Photo Mode UI: shared across cells, with Year-1 Photo Mode Tier 2 adding a
  utilitarian export/status surface for 15s MP4 with audio and a
  shooting-locations editor that uses a list plus selected-location inspector
  instead of decorative gallery cards.
- Companion app bridge: webview within main menu showing companion-app state,
  with the Year-1 Companion-App Mind Palace Editor exposing add/annotate clue
  draft controls for eligible signed-in accounts. The Full-Vision Companion-App
  AR Mode lets a paired phone point phone at TV and see a read-only Mind Palace
  overlay through `/v5/companion-app-bridge/ar/session` without raw camera
  upload. The Full-Vision Real-World Crime-Scene Integration adds foreground
  geofenced case check-ins at
  `/v5/companion-app-bridge/real-world/events/trigger`; it uploads only HMAC
  geofence tokens and blocks raw coordinates, address history, background
  tracking, private residences, active crime scenes, emergency sites, and
  restricted sites. The Full-Vision VTuber Companion Stream Mode starts local
  browser-source streamer overlays at
  `/v5/companion-app-bridge/vtuber/overlay/session`; `V5UI` exposes the
  companion bridge state, `V5OnlineServices` builds the session request, and the
  runtime enforces no stream key storage, no raw voice upload, no player PII,
  and no chat logs in the payload while spoiler-safe moderation controls remain
  streamer-controlled.

## Telemetry & Analytics

V5 telemetry is event-batched.

- Events validated against TypeBox schemas at the client edge.
- Events batched (max 2 KB / 5 seconds / 500 events per batch).
- Anonymization: per-account opaque ID + region; no PII without consent.
- Privacy compliance: opt-out via in-game settings; DSAR export via companion
  app.
- Telemetry consumer: ClickHouse on V5 services; per-cell dashboards in Grafana.

### Critical Events

- session_start / session_end
- mission_start / mission_complete / mission_fail
- combat_kill / combat_death / combat_damage_dealt / combat_damage_taken
- mindpalace_deduction_made / mindpalace_accusation
- dialogue_choice / dialogue_paragon_renegade
- vehicle_drive_start / vehicle_drive_end
- horse_bond_change
- ship_burn_start / ship_flip_burn / ship_dock
- alchemy_brew / sign_cast
- workshop_publish / workshop_subscribe
- privacy_consent_change

## Build, Cook, Patch

V5 build infrastructure mirrors V4's pattern.

- Build orchestrator: UnrealBuildTool + Horde Build for distributed compile.
- Cook: per-platform parallel cook; iterative cook for dev iteration.
- Patch: chunked patch via UnrealPak Iterative; per-cell chunk sizes for
  partial-download installs.
- Day-one patch policy: single binary update; out-of-band data hot-fix.
- Signed packages per platform; code signing via per-platform PKI.

## Data Architecture

V5 data is split across:

- **Data tables** (UDataTable) — characters, weapons, vehicles, NPCs,
  ingredients, bestiary, factions, missions.
- **Curve tables** (UCurveTable) — damage curves, XP curves, dialogue-wheel
  reaction curves, recoil curves.
- **Asset registries** — Niagara, audio, mesh.
- **Localization** — UE Localization Dashboard, per-language packs.
- **Telemetry schema** — TypeBox / JSON Schema in `apps/v5/telemetry/schema/`.

Cross-table validation: a CI job (`tools/validate-v5-docs.py`) checks
referential integrity (e.g., every mission's required NPC exists; every
vehicle's required mesh exists).

## Live-Service & DLC

V5 live-service architecture supports out-of-band content drops.

- Season pass: 90 days; theme rotation per cell; new contracts / cosmetics /
  missions.
- DLC packs: 10-hour content drops; cell-specific (e.g., a new Mafia-equivalent
  1953 chapter; a new Witcher's Path expansion).
- Cold Cases Year-1: `V5Mode_Detective_ColdCases` owns 20 weekly Mind Palace
  packs and publishes them through
  `V5/live-service/year-1-cold-cases-calendar.json`; the expansion carries 480
  minutes of additional VO.
- Frontier Bounty Year-1: `V5Mode_Frontier_OutlawTrail` owns 30 named bounties,
  the legendary-hunt clue trail runtime, and 8 legendary trapper outfits in
  `year1_frontier_bounty_manifest.json`.
- Frontier Naturalist Year-1: `V5Mode_Frontier_OutlawTrail` owns 30 new wildlife
  species, 12 new trapper outfits, and naturalist progression for cataloging
  wildlife in the journal through `year1_frontier_naturalist_manifest.json`.
- Polynesian Frontier Full-Vision: `V5Mode_Frontier_OutlawTrail` owns a 15-hour
  Pacific-Islander frontier sub-cell with five Pacific islands, eight voyage
  routes, six companion arcs, and consultation-gated mission metadata in
  `fullvision_polynesian_frontier_manifest.json`.
- Pirate Frontier Full-Vision: `V5Mode_Frontier_OutlawTrail` owns a
  Caribbean-pirate (1720s) sub-cell with a 16-hour campaign, five Caribbean
  ports, seven sea lanes, six crew leads, ten ship upgrades, and naval boarding
  mission metadata in `fullvision_pirate_frontier_manifest.json`.
- Egyptian Detective Full-Vision: `V5Mode_Period_ViceSquad` owns a 1920s
  Egyptology-equivalent detective sub-cell within the Period cell with 14
  provenance cases, five Egypt districts, twelve artifacts, seven suspects,
  period evidence retrieval, and Mind Palace tomb reconstructions in
  `fullvision_egyptian_detective_manifest.json`.
- Brave New World Steampunk Detective Full-Vision: `V5Mode_Steampunk_Detective`
  and `V5SteampunkDetective` own a new entire Steampunk Detective cell with an
  18-hour campaign, six brass-and-fog districts, twelve clockwork gadgets, nine
  suspects, Bureau HQ portal routing, a pressure-aware detective HUD, and Mind
  Palace evidence reconstruction in
  `fullvision_steampunk_detective_cell_manifest.json`.
- Cyberpunk 2087 Full-Vision: `V5Mode_Urban_HeistCity` owns an 2087-equivalent
  cyberpunk sub-cell inside the Urban cell with an 18-hour future-city campaign,
  six vertical districts, seven fixers, twelve cyberware items, and
  network-breach mission metadata in `fullvision_cyberpunk_2087_manifest.json`.
- Cosmic Horror Hunter Full-Vision: `V5Mode_Hunter_WitchersPath` owns a
  cosmic-horror-equivalent monster-hunter sub-cell with a 15-hour hunt campaign,
  five cursed regions, ten Witcher Sense investigation sites, twelve eldritch
  monsters, eight contained relics, dread-pressure gates, and ritual-seal hunt
  metadata in `fullvision_cosmic_horror_hunter_manifest.json`.
- Hunter VR Full-Cell: `V5Mode_Hunter_WitchersPath` owns a VR-native full-cell
  mode for the Hunter cell with all 130 Witcher's Path missions, 70 main quests,
  60 monster contracts, four comfort profiles, fourteen motion-controller
  bindings, five sign-casting gestures, flat-save compatibility, and headset
  targets in `fullvision_hunter_vr_full_cell_manifest.json`.
- Hunter Trial Year-1: `V5Mode_Hunter_WitchersPath` owns 4 ritual missions, a
  new witcher school cell variant, and 15 new monsters in
  `year1_hunter_trial_manifest.json`.
- Witcher School Trials Year-1: `V5Mode_Hunter_WitchersPath` owns 4 trial
  monsters at challenge tier and 4 mutation-equivalent power unlocks in
  `year1_hunter_school_trials_manifest.json`.
- Hunter Run Modifiers Year-1: `V5Mode_Roguelike_HunterRun` owns 20
  run-modifiers, modifier-normalized scoring, and a per-run leaderboard in
  `year1_hunter_run_modifiers_manifest.json`.
- Sci-Fi Pirate Coast Year-1: `V5Mode_SciFi_GalacticSquad` owns 12 missions in
  the Nereid Reach system, a new companion arc, and a privateer corvette variant
  in `year1_scifi_pirate_coast_manifest.json`.
- Sci-Fi New Galaxy Sector Year-1: `V5Mode_SciFi_GalacticSquad` owns the Helio
  Verge sector with 6 new systems, 15 new bodies, and 1 new faction in
  `year1_scifi_new_galaxy_sector_manifest.json`.
- Sci-Fi Long Tomorrow Full-Vision: `V5Mode_SciFi_GalacticSquad` owns the Long
  Tomorrow sector with 4 new systems, 20 new bodies, a Maia Shoal Star Map
  anchor, six FTL routes, DLC gating, and scan-overlay release gates in
  `fullvision_scifi_long_tomorrow_sector_manifest.json`.
- Sci-Fi AI-Persona Companion Full-Vision: `V5Mode_SciFi_GalacticSquad` owns an
  AI-persona companion that learns player choices for Kade Roe in the sci-fi
  cell only, persists local-profile memory, and rejects cross-cell training in
  `fullvision_scifi_ai_persona_companion_manifest.json`.
- Real-Time Translation Voice Chat Full-Vision: `V5Localization` owns real-time
  voice-chat translation across launch languages with 240 ordered language-pair
  routes, speaker/listener opt-in, no raw-audio retention, no voice-chat model
  training, synthetic voice indicators, and text-only language caption fallback
  in `fullvision_realtime_voice_chat_translation_manifest.json`.
- Hard Vacuum Capital Cruiser Year-1: `V5Mode_SciFi_HardVacuum` owns 1 new
  capital-class ship, 6 Capital Raid PvP maps, and 5v5 ranked Capital Raid
  matchmaking plus leaderboard score submissions in
  `year1_hard_vacuum_capital_cruiser_manifest.json`.
- Esports Pro Circuit Season 2 Year-1: `V5Mode_Spectator` and `V5SciFiPvP` own
  the official Capital Raid Season 2 pro-circuit bracket in
  `year1_esports_pro_circuit_season2_manifest.json`, including a 30-slot
  double-elimination bracket, 16 seeded teams, eight esports-only Capital Raid
  maps, and public esports-surface data for the bracket and map rotation.
- Pro Stadium Tour Esports Full-Vision: `V5Mode_Spectator` owns the real-stadium
  tour in `fullvision_pro_stadium_tour_manifest.json`, including six physical
  stadium stops, venue-license calendar metadata, per-stop broadcast routes,
  ticketing geofences, accessibility gates, SRT/NDI/HLS/DASH relay requirements,
  and the `/v5/live-service-calendar/pro-stadium-tour` schedule endpoint.
- Cross-Cell Co-op Stretch Year-1: `V5Mode_SpecOps_Coop` owns 12 cross-cell
  co-op missions in `year1_cross_cell_coop_stretch_manifest.json`, including
  "Detective in the Hunter Cell" style guest-cell scenarios, Bureau Tier 5
  gates, 1-4P drop-in/out support, and shared cross-cell loadout validation.
- Urban Speedrun League Year-1: `V5Mode_Urban_Online` owns 60 timed
  urban-driving routes, leaderboards using the shared score-write contract, and
  8 cosmetic event vehicles in `year1_urban_speedrun_league_manifest.json`.
- Urban New District Year-1: `V5Mode_Urban_HeistCity` owns the South Bay 15 km2
  addition, World Partition map metadata, and 12 new side missions in
  `year1_urban_new_district_manifest.json`.
- Heist Author Top 50 Year-1: `V5Mode_Editor_Workshop` owns the Community Heist
  Hub, top-50 community heists, and Player Created content category in
  `year1_heist_author_top50_manifest.json`.
- Workshop Curated Showcase Year-1: `V5Mode_Editor_Workshop` owns the
  curated-showcase carousel in the main menu, six curator-approved Workshop
  slides, and a community-spotlight per month in
  `year1_workshop_curated_showcase_manifest.json`.
- Workshop Moderator Tools Year-1: `V5Mode_Editor_Workshop` owns the
  community-moderator dashboard, ML-powered content pre-screen, moderation queue
  KPIs, and Workshop moderation service endpoints in
  `year1_workshop_moderator_tools_manifest.json`.
- Modder Marketplace [P3] Full-Vision Stretch (post-Year-1; phased per
  `V5_TODOS.md` §138, the phase source of truth): `V5Mode_Editor_Workshop` and
  `V5OnlineServices` own the paid-mod marketplace, six paid data-only mod
  listings, purchase entitlement flow, refunds, creator payouts, and 70 percent
  creator revenue share in `year1_modder_marketplace_manifest.json` (historical
  filename retained).
- Live-Service Calendar Year-1: `apps/v5/live-service-calendar` owns four 90-day
  seasonal-theme rotations, the Bureau Founding Day anniversary event, Shelter
  Signal charity event, and Platform Circuit console tie-in event in
  `V5/live-service/year-1-live-service-calendar.json`; the shared
  `live-service-calendar` contract exposes the `/v5/live-service-calendar/year1`
  feed with ETag and ordered-window guarantees.
- Persistent Online World Events Year-1: `apps/v5/live-service-calendar` also
  owns the settlement-backed live-event subsystem and 12 one-week world-event
  scripts in `V5/live-service/year-1-persistent-world-events.json`; the
  `/v5/live-service-calendar/world-events/year1` feed publishes Gang War Week
  and the remaining scripts with persistent world-state mutations, telemetry
  requirements, 30-day settlement snapshots, and no exclusive gameplay rewards.
- Live-Service Year-3 Pipeline: `apps/v5/live-service-calendar` owns the Year-3
  planning feed for 4 new sub-cells, 8 cross-cell co-op missions, and 1 new
  console SKU in `V5/live-service/year-3-live-service-pipeline.json`; the
  `/v5/live-service-calendar/year3-pipeline` feed publishes the four seasonal
  sub-cell roadmap, 240 minutes of 1-4P co-op mission planning, and the
  `V5Switch2Year3` native SKU cert track with reduced-install budgets and no
  platform-exclusive gameplay.
- Cross-Cell Online Persistent World: `V5OnlineServices` owns the cross-cell
  shared online world in `fullvision_cross_cell_persistent_world_manifest.json`,
  using Bureau HQ as multiplayer hub with six shared zones, 64-player
  dedicated-server sessions, `/v5/parties/cross-cell-world/session`, and one
  shared progression layer for profile, cosmetics, Bureau XP, Mind Palace,
  codex, and live-event settlement state. The hub blocks per-cell campaign
  branch writes so shared presence and progression cannot leak local story state
  across cells.
- Faction Reputation Decay Year-1: `apps/v5/faction-rep` owns the weekly
  inactivity decay job, neutral-tier floor, ledger/rival-lock reconciliation,
  and five restoration mission arcs in
  `V5/live-service/year-1-faction-reputation-decay.json`;
  `/v5/faction-rep/decay/year1` runs the decay policy and
  `/v5/faction-rep/restoration-arcs/year1` publishes the cell-specific recovery
  arcs.
- AI-Generated Highlight Reel Year-1: `apps/v5/replays` owns the optional Coqui
  TTS AI commentator track, replay-ranked top-10 highlight reel, and
  match-history recap in `V5/live-service/year-1-ai-highlight-reel.json`; the
  `/v5/replays/commentary/tts/year1`, `/v5/replays/highlights/year1/top10`, and
  `/v5/replays/recap/year1` routes all require synthetic-content indicators and
  source replay verification.
- New Game+ Year-1: `V5Persistence` owns the tier-20 NG+ plan in
  `V5/ue/Content/V5Persistence/Data/year1_new_game_plus_manifest.json`, covering
  Urban, Period, Frontier, Hunter, and Sci-Fi with two NG+-only story branches
  and three difficulty modifiers per cell while carrying account-level meta and
  reseeding campaign state.
- Save Slot Archaeology Year-1: `V5Persistence` owns the old-save import flow in
  `V5/ue/Content/V5Persistence/Data/year1_save_slot_archaeology_manifest.json`;
  `UV5_SaveGame::ImportFromJsonString` migrates supported v1/v2 save JSON into a
  tier-20 NG+ target slot while `UV5_Persist_SaveSlotArchaeology` evaluates ten
  imported ending-state signals into NG+-only scenario flags.
- Vehicle Customization Tier 2 Year-1: `V5Vehicles` owns 200 Tier 2
  customization parts for modern and period body-shop domains in
  `V5/ue/Content/V5Vehicles/Data/year1_vehicle_customization_tier2_manifest.json`;
  `V5WorkshopEditor` and the `workshop` service publish data-only
  vehicle-blueprint share payloads through
  `/v5/workshop/vehicle-blueprints/share`.
- Photo Mode Tier 2 Year-1: `V5Mode_PhotoMode` owns 15s MP4 with audio export
  and the shooting-locations editor in
  `V5/ue/Plugins/V5Mode_PhotoMode/Content/Data/year1_photo_mode_tier2_manifest.json`;
  `V5UI` exposes the location list, selected-location inspector actions, and
  privacy-scrubbed AAC submix capture state.
- Companion-App Mind Palace Editor Year-1: `V5MindPalace`, `V5UI`, and
  `V5OnlineServices` expose companion `add-clue` and `annotate-clue` draft
  workflows in `V5/companion/shared/year1_mind_palace_editor_manifest.json`; the
  companion bridge service accepts drafts at
  `/v5/companion-app-bridge/mindpalace/edit` and queues them for Mind Palace
  graph-diff reconciliation.
- Companion-App AR Mode Full-Vision: iOS, Android, web, `V5UI`, and
  `V5OnlineServices` expose the point phone at TV pairing flow in
  `V5/companion/shared/fullvision_companion_ar_mode_manifest.json`; the
  companion bridge starts sessions at `/v5/companion-app-bridge/ar/session`,
  renders a read-only Mind Palace overlay, requires four TV-corner alignment,
  and blocks raw camera upload.
- Real-World Crime-Scene Integration Full-Vision: iOS, Android, web,
  `V5Investigation`, and `V5OnlineServices` expose foreground geofenced
  investigation events in
  `V5/companion/shared/fullvision_real_world_crime_scene_manifest.json`; the
  companion bridge accepts check-ins at
  `/v5/companion-app-bridge/real-world/events/trigger`, uploads only HMAC
  geofence tokens plus coarse dwell/accuracy evidence, never uploads raw
  coordinates or address history, and blocks unsafe private, emergency,
  restricted, or active-crime-scene venues before fictional scene unlock.
- VTuber Companion Stream Mode Full-Vision: iOS, Android, web, `V5UI`, and
  `V5OnlineServices` expose streamer overlay setup in
  `V5/companion/shared/fullvision_vtuber_companion_stream_mode_manifest.json`;
  the companion bridge starts local browser-source sessions at
  `/v5/companion-app-bridge/vtuber/overlay/session`, maps game events to
  spoiler-safe avatar states, enforces no stream key storage, no raw voice
  upload, no player PII, and no chat message storage, and keeps chat safety,
  mature gates, streamer blocklists, and panic hide overlay explicit in
  moderation controls.
- Mind Palace Daily Year-1: `V5Mode_Detective_MindPalace` owns 365 daily Mind
  Palace puzzles, UTC daily rotation, and daily leaderboard score submissions in
  `year1_mind_palace_daily_manifest.json`.
- Mind Palace Crossover Pack Year-1: `V5Mode_Detective_MindPalace` owns the
  Black Archive 6-hour cross-cell mystery arc, 12 new cross-era deductions, and
  Bureau Tier 5 cross-era gates in
  `year1_mind_palace_crossover_pack_manifest.json`.
- Posse War Tournament Year-1: `V5Mode_Frontier_Online` owns the 4v4
  ranked-tournament season, 4 tournament-only maps, Frontier matchmaking queue
  contract, and ranked leaderboard score submissions in
  `year1_posse_war_tournament_manifest.json`.
- Made Man Chapter 4 Year-1: `V5Mode_Period_MadeMan` owns 22 1980s-equivalent
  missions, the 1980s period-authenticity bundle, and 8 new companions in
  `year1_made_man_chapter4_manifest.json`.
- Period Documentary Year-1: `V5Mode_Period_MadeMan` owns a 42-minute
  behind-the-scenes documentary cinematic plus an in-game documentary viewer
  with chapter/still navigation, captions, and commentary in
  `year1_period_documentary_manifest.json`.
- Vice Squad Cold Case Year-1: `V5Mode_Period_ViceSquad` owns 8 unsolved 1947
  cold cases and period-correct evidence retrieval in
  `year1_vice_squad_cold_cases_manifest.json`.
- Hot-fix: balance + UI strings via CDN-served data files; no binary patch.
- Live-service calendar: `apps/v5/live-service-calendar/` publishes the
  rotation; in-game UI fetches.

## Accessibility

V5 ships AAA accessibility on launch. See `V5_features.md`
features§"Accessibility" for the feature list. Architecture-wise:

- **Subtitle system** — base implementation supports per-speaker color coding,
  font size, background opacity, font weight, character border.
- **Color-blind mode** — color-corrected UI palette; gameplay color cues (protan
  / deutan / tritan / monochrome) re-mapped.
- **Audio cue system** — `V5_Accessibility_AudioCue` routes combat events to
  spatial audio markers for hearing-impaired players.
- **Difficulty per-cell** — gameplay difficulty stored per-cell; switching cells
  respects per-cell preference.
- **Aim-assist** — per-axis sensitivity, per-cell tuning, target-acquisition
  with priority pyramid (enemy > breakable > civilian).
- **Camera-shake reduction** — global slider 0-100%; per-cell defaults.
- **Photosensitivity mode** — clamps flash count (max N per 5 s), removes
  strobe, dims screen-burst overlays.
- **TTS for menus** — Coqui TTS-based; lazy-loaded per language.
- **STT for voice chat** — Whisper-based; opt-in per session.
- **Real-time voice-chat translation** — `V5Localization` builds the
  all-launch-language route matrix, routes party/team voice through Whisper STT,
  `V5RealtimeMT`, and Coqui TTS, and falls back to translated captions for
  text-only language packs.
- **Input remapping** — per-context full remap via Enhanced Input.
- **One-handed schemes** — preset profiles for PS5 Adaptive + Xbox Adaptive.

## Security, Privacy, Compliance

V5 security architecture:

- All client-server traffic TLS 1.3.
- Save-game encryption with per-account key.
- Anti-piracy via signed-execution checks; no Denuvo (per V5_TODOS.md §1.2 ADR
  0006).
- Privacy-by-design: telemetry opt-out; per-region data residency.
- GDPR DSAR: 30-day SLA via companion app.
- CCPA do-not-sell flag.
- DSA-compliant content moderation in EU.
- COPPA-compliant under-13 path.

## Observability, Evaluation, Release Gates

V5 release gates require:

- Nightly Gauntlet automation pass.
- Each cell's feel-test suite pass.
- Adversarial stub-scan zero hits.
- Crash-free session rate > 99.5% on PS5 in regression-test cohort.
- Memory budget < per-platform target on Gauntlet 10-hour run.
- Network packet-loss tolerance pass at 5% / 20%.
- Localization QA pass per language.
- Accessibility audit pass.
- Compliance review (legal, privacy, ratings).

## Performance Budgets

Per-platform performance budgets:

Frame Budget, GPU Budget, and CPU Budget are in milliseconds; the GPU and CPU
figures are the per-frame slices of the total frame budget. Where two values are
given (`a / b`), they correspond to the two frame-rate targets in the Frame
column.

| Platform        | Frame    | Frame Budget (ms) | GPU Budget (ms) | CPU Budget (ms) | Memory Budget |
| --------------- | -------- | ----------------- | --------------- | --------------- | ------------- |
| PS5             | 30 / 60  | 33.3 / 16.6       | 22 / 11         | 10 / 5          | 12 GB         |
| PS5 Pro         | 60 / 120 | 16.6 / 8.3        | 12 / 6          | 4 / 2           | 13 GB         |
| XSX             | 30 / 60  | 33.3 / 16.6       | 22 / 11         | 10 / 5          | 12 GB         |
| XSS             | 30 / 60  | 33.3 / 16.6       | 22 / 11         | 10 / 5          | 8 GB          |
| Switch 2        | 30 / 60  | 33.3 / 16.6       | 28 / 14         | 5 / 2.5         | 8 GB          |
| Windows (low)   | 60       | 16.6              | 12              | 4               | 8 GB          |
| Windows (rec)   | 60       | 16.6              | 10              | 3               | 16 GB         |
| Windows (ultra) | 120      | 8.3               | 6               | 2               | 32 GB         |
| macOS M3+       | 60       | 16.6              | 10              | 4               | 16 GB         |
| Linux Deck      | 30       | 33.3              | 26              | 8               | 16 GB         |
| Arcade cabinet  | 60       | 16.6              | 10              | 4               | 16 GB         |
| iPad M3+        | 60       | 16.6              | 12              | 4               | 16 GB         |

This table is the engineering frame-time budget. The player-facing frame-rate
and resolution targets per platform are in `V5_features.md` features§"Display
Tech, Performance, and Cert"; the two tables are complementary, not duplicates.
The launch-locked profile catalog at
`V5/ue/Content/V5Performance/Data/performance_platform_profiles.json` binds
these budgets to platform config sections and the release-blocking performance
regression suite.

Per-cell performance tuning:

- Urban (high streaming churn): pedestrian density throttle on consoles.
- Sci-Fi Hard Vacuum (gravity-zone transitions): conservative LOD on Switch 2.
- Hunter (forest density): aggressive Nanite cluster cull on Switch 2.

### Arcade Cabinet Build Target

`V5ArcadeCabinet` is a game target for the location-based four-player cabinet
SKU. It uses `V5/ue/Source/V5ArcadeCabinet.Target.cs`, sets the project-scope
`V5_ARCADE_CABINET`, `V5_LOCAL_COOP_CABINET`, `V5_CABINET_ONLINE_SERVICES=0`,
and `V5_CABINET_COIN_OP_ECONOMY=0` compile definitions, and packages through
`V5/ue/Platforms/ArcadeCabinet/Config/ArcadeCabinetEngine.ini`. The target cooks
only the curated local co-op roster: Spec Ops Co-op, Horde Defense, Fleet Co-op,
Hunter Card Game, and Training Range.

The cabinet profile is authored in
`V5/ue/Content/V5Input/Data/arcade_cabinet_build_manifest.json`. It binds
four-player `ArcadePanel` Enhanced Input contexts, 4K60 output, offline boot,
LAN discovery, attract mode, protected service-menu diagnostics, watchdog
heartbeat, and the no-coin-op-economy gate. Runtime mode gating maps this target
to `EV5ModeBuildTarget::ArcadeCabinet`, hiding open online/PvP rulesets while
allowing cabinet-safe local service shims for bounded co-op.

## Testing, QA, Cert

V5 testing tiers:

- Unit tests (per-module): C++ test target + Python automation.
- Automation tests (per-feature): Gauntlet driver + scripted runs.
- Feel tests (per-cell): manual + automated playback of canonical scenarios.
- Smoke tests (nightly): full-game-launch + first-mission-of-each-cell.
- Regression tests: golden-replay (recorded inputs + expected outputs).
- Localization QA: per-language proofread + lipsync check.
- Accessibility QA: per-feature audit + user-tester sessions.
- Cert: per-platform first-party submission readiness; bug-budget per platform.

## Content Pipeline & Source Control

V5 source control architecture:

- Primary repo: this Oshun monorepo (Git).
- Asset repo: Perforce (sub-repo at `V5/ue/Content/` outside Git's scope; pulled
  via Helix Core).
- Asset locking: per-asset checkout to avoid binary merge conflicts.
- Branching: trunk-based with short-lived feature branches.
- CI: Buildkite for tests + Horde for cook + Perforce for asset CI.

## Creator Suite Architecture

V5 creator suite tools:

- **Mission Editor**: based on UE Editor + custom Slate panels; per-cell mission
  templates; live preview.
- **Heist Author**: dedicated Slate UI on top of Mission Editor; role / vehicle
  / route authoring.
- **Case Author**: Vice-Squad-style case authoring; clue placement +
  interrogation tree.
- **Contract Author**: monster-contract authoring with bestiary picker.
- **Ship Loadout Author**: ship-config tool for Hard Vacuum.
- **Bestiary Author**: stat-block + Niagara FX + behavior tree.
- **Cinematic Director Mode**: director-mode video-authoring tool with timeline
  tracks, cuts, cut-inspector validation, Replay Theater import, Sequencer
  round-trip, and Movie Render Queue export presets through
  `cinematic-director-mode-manifest.json`.
- **Cross-Cell Replay Editor**: replay-editor for splicing clips from any cell
  into a single merged export with cell filters, splice timeline validation,
  source replay hashes, and privacy-scrubbed timeline metadata through
  `fullvision_cross_cell_replay_editor_manifest.json`.
- **Workshop Publisher**: integrated into UE Editor; one-click publish to V5
  Workshop service; the Year-1 Community Heist Hub reads curated Player Created
  Heist Author uploads through the Workshop discovery contract. The Workshop
  Curated Showcase Year-1 path also feeds the curated-showcase carousel in the
  main menu and a community-spotlight per month through
  `year1_workshop_curated_showcase_manifest.json`. The Modder Marketplace [P3]
  Full-Vision Stretch path (post-Year-1; phased per `V5_TODOS.md` §138) adds a
  paid-mod marketplace with creator KYC, tax interview, purchase entitlement,
  refund, payout, and 70 percent creator revenue share contracts in
  `year1_modder_marketplace_manifest.json` (historical filename retained).

Each tool emits a typed data file (USTRUCT-based) that the runtime loads.

## Mind Palace Deduction Architecture

The Mind Palace is a graph database + a UI shell.

### Data Model

- `V5_Evidence_Node`: { id, cell, location, timestamp_in_fiction, tags,
  description, image, examined_details }
- `V5_Deduction_Edge`: { from_node, to_node, deduction_text, confidence,
  authored=true|false }
- `V5_Accusation_Outcome`: { case_id, accused_id, evidence_chain[], rating,
  outcome_branch }
- `V5_MindPalace_State`: { graph, accusations[], unlocks }

### Graph Operations

- `AddEvidenceNode(node)` — called from V5Investigation when player examines a
  clue.
- `AttemptDeduction(nodeA, nodeB)` — player tries to pair; returns authored
  deduction or null.
- `BuildHypothesisChain(starting_node)` — UI helper for visualizing.
- `MakeAccusation(case_id, accused_id, evidence_chain[])` — locks in outcome.
- `BuildDailyPuzzleForDate(date_utc)` — resolves the annually wrapping Year-1
  daily-puzzle rotation.
- `BuildDailyLeaderboardSubmitRequest(result)` — writes clean daily solve scores
  through `services/leaderboards`.
- `BuildYear1CrossoverPackCatalog()` — exposes the Mind Palace Crossover Pack
  Year-1 Black Archive 6-hour cross-cell mystery arc and 12 new cross-era
  deductions for manifest and runtime validation.

### Cross-Cell Linkage

- Cross-era deductions are gated by Bureau-XP and progression flags.
- Graph queries are cell-aware: filter by cell, by case, by tag.

### Cloud Sync

- `V5_MindPalace_CloudSync` pushes graph diffs to
  `services/mindpalace-cloud-sync` for cross-device.

### Mind Palace UI

- Spatial 3D view: a circular "memory room" with evidence orbs floating in
  concentric rings (by cell of origin).
- Click an orb → close-up examination + linked nodes highlighted.
- Drag two orbs into the center "deduction pedestal" → attempt pair.
- Filter rail on left: cell, case, time period, tag.

## MotionScan Interrogation Architecture

V5's interrogation rig is MetaHuman-based with custom face capture.

### Capture Pipeline

- 12-camera face stage at the LA mocap studio (deps§5).
- Per-actor 16-hour calibration session (FACS-based).
- Capture-take output: `.usd` blendshape stack at 60 fps.
- Editor post: trim, blend, retake; integrated with Sequencer.

### Interrogation Runtime

- Each interrogation scene loads N facial-tell takes per witness.
- `V5_Interrogation_TellPlayer` plays the take in sync with VO.
- Player input (Truth / Doubt / Lie) at statement boundary; system reads the
  player's call against the authored truth-state.

### Interrogation Scoring

- Per-statement accuracy → per-interrogation rating (Brilliant / Good / Average
  / Poor).
- Brilliant rating gates downstream dialogue options + companion reactions.
- Interrogation-result XP feeds Bureau XP via the cross-cell ledger.

## Dialogue Wheel Architecture

V5 dialogue wheel is a runtime + authoring system.

### Dialogue Authoring

- Dialogue trees authored in `V5/tools/missions/dialogue.py` (yaml format).
- Schema: per-node options[], paragon/renegade tag per option, gating conditions
  (state flags, attributes, faction-rep), VO-line references.
- Compile-time: yaml → UAsset DataTable.

### Dialogue Runtime

- `V5_Dialogue_RuntimeStateMachine` walks the tree.
- Per-frame: load eligible options for current node; filter by state conditions.
- Wheel UI: 6 spokes, per-spoke option text + paragon/renegade tint.
- Interrupt detection: in cinematic mode, watch for player input on frame range
  marked "interrupt-able".

### State Integration

- Player choices increment paragon/renegade meters.
- Wheel option visibility gated by attribute (e.g., Charm option needs Paragon ≥
  70).

## Heist Planner Architecture

The Heist Planner is a pre-mission authoring step + a runtime executor.

### Pre-Mission Planning

- `V5_Heist_Planner` Slate panel; loads the heist's target intel + available
  crew + vehicle + weapon pool.
- Player authors:
  - Crew assignment (1-4 players + outside-crew NPCs).
  - Per-member role (driver, hacker, gunner, lookout, demo).
  - Per-member vehicle, primary, secondary, special.
  - Route waypoints (approach, entry, inside, escape, dump-vehicle, safehouse).
- Rehearsal preview: 4× slowed-speed walkthrough; conflict detection highlights
  cross-fire / friendly-fire / high-patrol-zone paths.

### Execution Runtime

- The runtime mission spawns from the planner's plan-data.
- Mid-mission Tab-pause allows live re-routing of waypoints; AI crew resumes
  from the new plan.
- Plan-data persisted as `V5_Heist_PlanRecord` for replay export.

### Three-Ending Logic

- Smooth: completed without alarm, no civilian casualties, target gain full.
- Hard: alarm raised mid-heist, target gain partial.
- Catastrophic: failure of escape, target gain near-zero, crew loss.

Ending type gates downstream cut rates + follow-up heist availability.

## Spaceship Physics Architecture

V5 Hard Vacuum physics is fully Newtonian.

### Newtonian Simulation

- Per-ship rigid body: mass, moment of inertia tensor, thrust vector (main
  engine + RCS).
- Time step: 60 Hz substep within UE 30 Hz rendering tick.
- Forces:
  - Main engine: 1G or 2G at full thrust (per ship class).
  - RCS thrusters: ~0.01 G; primarily for reorientation.
  - Drag: zero (vacuum); zero from atmospheric resistance.
  - Tidal: ignored (no realistic-orbit).
- Solver: PhysX 5 (UE's wrapper).

### Gravity Zones

- Per-volume gravity field:
  - Thrust-G: zone follows ship; orientation = -thrust-direction.
  - Spin-G: centrifugal field on a habitat ring; orientation = radial.
  - Zero-G: no field.
- Pawn locomotion adapts to active field: walk-down-thrust during burn;
  walk-around-ring during spin; float during coast.

### Ship Weapons

- PDC: instant-hit bullets at 7 km / s; tracer; PDC tracking algorithm predicts
  intercept point.
- Railgun: high-velocity slug at 60 km / s; real-time travel; player must lead
  target.
- Torpedo: physical guided/unguided missile; physics object on the radar;
  intercept-able by PDC.

### Ship Damage Model

- Hit location maps to component (engine, weapons, reactor, comms, bridge);
  per-component HP; cascading effects (engine damaged → reduced thrust; comms
  damaged → no torpedo guidance).

## Vehicle Library Architecture

V5 vehicles use **ChaosVehicles**.

### Per-Class Tuning

- Sedans (modern): low CoG, high traction, moderate top speed.
- Sports (modern): low CoG, high traction, high top speed, oversteer-prone.
- Period autos (1930s): high CoG, low traction, drum brakes (long stop
  distance), narrow tires.
- Period autos (1968): mid CoG, mid traction, disc brakes (moderate stop), power
  steering (responsive at low speed, light at high).
- Wagons (frontier): high CoG, very low max speed (10 mph), 4-horse team.
- Spacecraft: completely separate model (V5Spaceship, not Chaos).
- Horses: separate model (V5HorseAI gait library, not Chaos).
- Vehicle Customization Tier 2 Year-1 layers 200 Tier 2 customization parts over
  the modern and period body-shop surfaces; `UV5_Vehicle_CustomizationLibrary`
  validates the authored manifest and keeps every part eligible for Workshop
  vehicle-blueprint share.

### Vehicle Damage Model

- Body deformation: ChaosDestruction at hit zones.
- Tire blowout: per-tire HP; blown tire reduces speed + traction.
- Engine knock-out: per-vehicle HP; knock-out triggers smoke + slow-speed-cap.

## Horse AI Architecture

V5HorseAI is a custom subsystem (frontier + hunter cells).

### Per-Horse State

- `V5_Horse_State` { id, breed, bond_tier, stamina, max_stamina, health,
  max_health, hunger, mood }
- Bonding tier (Wild → Familiar → Trusted → Bonded) drives behavior:
  - Wild: spooks easily; throws rider on threat.
  - Familiar: spooks less; obeys gait inputs.
  - Trusted: rear-on-command, side-step, drift.
  - Bonded: calm-under-fire, comes-when-whistled, drift-into-stop.

### Gait Library

- Walk (3 mph), Trot (8 mph), Canter (15 mph), Gallop (30 mph).
- Stamina cost per gait; depletion forces slow-down.
- Recovery: full stamina in 60 in-game seconds at walk.

### Saddlebag Inventory

- Saddlebag inventory persists with horse; horse-death means saddle + inventory
  loss unless retrieved at carcass.

## Alchemy & Signs Architecture

V5Alchemy + V5Signs are hunter-cell core.

### Alchemy Data

- 120 recipes (`V5_Alchemy_Recipe` data table): { id, type (potion / oil / bomb
  / decoction), ingredients[3], brew_duration, effects[], toxicity }
- Brewing UI: meditation-pose (in-fiction); ingredients consumed; output to
  slot.

### Signs Data

- 5 signs: each with charge-tier variants + 5-tier upgrade tree.
- GAS-based: each sign is a `V5_Ability_Sign_*`.
- Stamina-cost: depletes from V5_AttributeSet_Combat.Stamina; regen during dodge
  / parry.

## Bestiary & Witcher-Sense Architecture

### Bestiary Data

- 80 monsters across 12 categories (`V5_Bestiary_Entry` data table).
- Per-entry: stats, weak-vs-oil, weak-vs-sign, weak-vs-bomb, behavior,
  unlock_state (0-100%).

### Witcher-Sense Runtime

- Toggle state on V5_Player_State.
- World query: in-range clue actors (V5_Clue_Marker) light up; sense-mode camera
  saturation drops; clues highlight by type (scent / blood / track / sound /
  magic).
- Investigate prompt: rotate clue close-up; add notebook entry; push to
  MindPalace.

## Period-Authenticity Pipeline

V5PeriodAuth is an era-bundle abstraction.

### Bundle Data

- `V5_PeriodAuth_Bundle` { era_id, vehicles[], fashion[], signage[], fonts[],
  slang[], music[], food[], radio_station_set, lighting_overrides }

### Runtime Swap

- World Partition data-layer per era; flip data-layer toggles all era-specific
  actors.
- NPC crowd applies era-specific body-language library.
- UI / HUD applies era-specific font + color palette.

### Bundle Authoring

- Per-era research dossiers in `V5/balance/period-auth/<era>/`.
- Asset linter ensures every period-tagged asset has correct era-bundle
  membership.

## Cross-Cell Persistence & Bureau XP

The Cross-Continuum Bureau provides the cross-cell progression spine.

### Bureau XP Ledger

- Earned per significant action (cell-specific weights).
- `V5_Bureau_XP_Ledger` { account_id, total_xp, per_cell_xp[5], current_tier,
  unlocks[] }
- Tier-up unlocks cross-cell loadouts (e.g., Dead-Eye → Reflex in urban;
  Witcher-Sense → Detective Mode in period).

### Cross-Cell Unlocks

- Tier 1: photo-mode unlocked across all cells.
- Tier 5: Mind Palace cross-era pairs unlocked.
- Tier 10: companion-app full sync.
- Tier 20: New Game+ option with five-cell Year-1 branch/modifier plan.
- Tier 30: cosmetic Bureau gear in every cell.
- Bureau HQ multiplayer hub: the Cross-Cell Online Persistent World uses the
  same account-scoped layer for online hub presence, so profile, cosmetics,
  Bureau XP, Mind Palace, codex, and live-event settlements move through the
  shared online backbone while per-cell campaign saves stay namespaced.

### Bureau XP Persistence

- Saved per account (`Profile_<accountId>.json`); cell-save manifest links to
  cell-specific saves.

## Launch Readiness

V5 launch readiness requires:

- All P1 TODOs in `V5_TODOS.md` checked.
- Adversarial stub-scan zero hits across all V5 modules.
- All 9 platforms pass first-party cert.
- All 16 language packs pass localization QA.
- Cross-cell Mind Palace deduction graph validated end-to-end with the cross-era
  main arc playable to all endings.
- Public balance ledger live.
- Day-of-launch live-service event scheduled.
- Single-player offline path validated for every cell.
- Multiplayer matchmaking validated on every supported region with simulated
  ping of up to 80 ms.

## Cross-References

- `V5/V5_features.md` — feature inventory.
- `V5/V5_TODOS.md` — backlog and execution order.
- `V5/V5_DEPENDENCIES.md` — dependency registry.
- `apps/oshun/web/src/design-system/lilith/` — design language tokens available
  for V5 marketing site.
- `libs/shared/` — cross-domain Oshun packages V5 depends on (auth, telemetry,
  observability).