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/. 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 V5_features.md / features/.

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/V5_TODOS.md, and V5/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
• Subsystem Glossary
  • Engine Modules
  • Game-Feature Plugins (one per mode-variant)
• High-Level Architecture
• Project Layout
• Module Split
• Gameplay Ability System (GAS) Layout
  • Attribute Sets
  • Ability Categories
  • Gameplay Effects
  • Gameplay Tags
• Animation Pipeline
• Input Pipeline
• AI Perception, NPC Schedules, Crowd
  • Perception State Machine
  • Stimuli Sources
  • Cell-Specific NPC Behaviors
  • NPC Schedule Architecture
• Honor / Karma / Paragon Bridge
  • Per-Cell Local Axis
  • Cross-Cell Meta-Axis
  • Use of the Moral Compass
• Combat Authority & Determinism
• Client-Server Netcode (Open-World, PvP)
• Rollback-Emulated Prediction (Spaceship PvP)
• Game Modes (GameFeatures Plugins)
• Open-World Streaming (World Partition + Crowd)
• Procedural Generation Pipeline
• Persistence & Profile
  • Save Categories
  • Save Format
  • Cross-Device Save Sync
  • Save Corruption Recovery
• Online Services Backend
• Anti-Cheat
• Cross-Play & Cross-Progression
• Audio Pipeline
  • Audio Plumbing
• VFX Pipeline
• Cinematic Pipeline
• UI / HUD Architecture
• Telemetry & Analytics
  • Critical Events
• Build, Cook, Patch
• Data Architecture
• Live-Service & DLC
• Accessibility
• Security, Privacy, Compliance
• Observability, Evaluation, Release Gates
• Performance Budgets
• Testing, QA, Cert
• Content Pipeline & Source Control
• Creator Suite Architecture
• Mind Palace Deduction Architecture
  • Data Model
  • Graph Operations
  • Cross-Cell Linkage
  • Cloud Sync
  • Mind Palace UI
• MotionScan Interrogation Architecture
  • Capture Pipeline
  • Interrogation Runtime
  • Interrogation Scoring
• Dialogue Wheel Architecture
  • Dialogue Authoring
  • Dialogue Runtime
  • State Integration
• Heist Planner Architecture
  • Pre-Mission Planning
  • Execution Runtime
  • Three-Ending Logic
• Spaceship Physics Architecture
  • Newtonian Simulation
  • Gravity Zones
  • Ship Weapons
  • Ship Damage Model
• Vehicle Library Architecture
  • Per-Class Tuning
  • Vehicle Damage Model
• Horse AI Architecture
  • Per-Horse State
  • Gait Library
  • Saddlebag Inventory
• Alchemy & Signs Architecture
  • Alchemy Data
  • Signs Data
• Bestiary & Witcher-Sense Architecture
  • Bestiary Data
  • Witcher-Sense Runtime
• Period-Authenticity Pipeline
  • Bundle Data
  • Runtime Swap
  • Bundle Authoring
• Cross-Cell Persistence & Bureau XP
  • Bureau XP Ledger
  • Cross-Cell Unlocks
  • Bureau XP Persistence
• Launch Readiness
• 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#

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:

┌───────────────────────────────────────────────────────────────────┐
│                       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#

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#

[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:

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/.

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.

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).