# V2 — Architecture (Fighting Game, Unreal Engine 5) Status: V2 launch architecture and full-vision extension architecture Source: derived from `V2/V2_features.md` (feature map) and `V2/V2_TODOS.md` (implementation backlog) Audience: engineering, online services, build / release, security, and production leads Date: 2026-05-12 > **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 [`V2_features.md`](./V2_features.md). ## Purpose This document describes the runtime, package, and integration architecture V2 must ship. It is grounded in the V2 feature map (`V2_features.md`) and the V2 backlog (`V2_TODOS.md`), and is anchored to the packages and modules that the V2 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: [`V2/V2_features.md`](./V2_features.md), [`V2/V2_TODOS.md`](./V2_TODOS.md), and [`V2/V2_DEPENDENCIES.md`](./V2_DEPENDENCIES.md). V2 is one game, not a platform. The architecture mirrors that ambition: one shared roster, one shared creator suite, one shared online backbone, and swappable per-ruleset gameplay layers. ## Cross-Reference Convention Throughout this document, **bare `§N` and `§N.M` references resolve to `V2_TODOS.md`** (the backlog has 138 numbered top-level sections and ~1000 numbered subsections; it is the only V2 doc with section numbering used as hyperlinks). Explicit doc-prefixed references appear where ambiguity matters: - `§80` → `V2_TODOS.md` §80 (Compliance Deep) — the default convention. - `§52.8` → `V2_TODOS.md` §52.8 (Live-service operations cadence). - `deps§57` → `V2_DEPENDENCIES.md` §57 (Hardware Peripheral SDKs). - `features§"V2 Product Promise"` → `V2_features.md` section by anchor (the features doc is not numbered). - `arch§"Rollback Netcode"` → this document, by section anchor. `V2_features.md` and this document use named anchors, not numbers, to avoid duplicating the TODOs numbering scheme. The other three V2 docs follow the same convention. ## Table of Contents - [V2 Product Promise](#v2-product-promise) - [Subsystem Glossary](#subsystem-glossary) - [High-Level Architecture](#high-level-architecture) - [Project Layout](#project-layout) - [Module Split](#module-split) - [Gameplay Ability System (GAS) Layout](#gameplay-ability-system-gas-layout) - [Tags](#tags) - [Attribute Sets](#attribute-sets) - [Abilities](#abilities) - [Gameplay Effects](#gameplay-effects) - [Match-State Machine](#match-state-machine) - [Animation Pipeline](#animation-pipeline) - [Skeleton & Retarget](#skeleton--retarget) - [AnimBP](#animbp) - [Motion Matching & Mover](#motion-matching--mover) - [Cloth, Hair, Facial](#cloth-hair-facial) - [Input Pipeline](#input-pipeline) - [Game Feel: Hitstop, Hitlag, Camera Shake](#game-feel-hitstop-hitlag-camera-shake) - [Combat Authority & Determinism](#combat-authority--determinism) - [Per-Frame Loop](#per-frame-loop) - [Determinism Rules](#determinism-rules) - [Hitbox Authority](#hitbox-authority) - [Rollback Netcode](#rollback-netcode) - [Architecture](#architecture) - [Transport](#transport) - [Diagnostics](#diagnostics) - [Client-Server Netcode](#client-server-netcode) - [Network Quality & Fallback](#network-quality--fallback) - [Game Modes](#game-modes) - [Per-Mode Architecture Notes](#per-mode-architecture-notes) - [Training, Trials, Replay Pipeline](#training-trials-replay-pipeline) - [Character Presentation Pipeline](#character-presentation-pipeline) - [Tag-Team Architecture](#tag-team-architecture) - [Persistence & Profile](#persistence--profile) - [Online Services Backend](#online-services-backend) - [Anti-Cheat](#anti-cheat) - [Cross-Play & Cross-Progression](#cross-play--cross-progression) - [Audio Pipeline](#audio-pipeline) - [VFX Pipeline](#vfx-pipeline) - [Cinematic Pipeline](#cinematic-pipeline) - [UI / HUD Architecture](#ui--hud-architecture) - [Telemetry & Analytics](#telemetry--analytics) - [Asset Budget & Streaming](#asset-budget--streaming) - [Hotfix, Quick-Resume, Crash Recovery, DRM](#hotfix-quick-resume-crash-recovery-drm) - [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) - [Per-Fighter Signature Library Architecture](#per-fighter-signature-library-architecture) - [Side-Story & Story-Theater Pipeline](#side-story--story-theater-pipeline) - [Match-Flow Mode Plugin Matrix (extension)](#match-flow-mode-plugin-matrix-extension) - [Ranked Season Service](#ranked-season-service) - [Companion App Architecture](#companion-app-architecture) - [Production Pipeline](#production-pipeline) - [Compliance & Data-Subject-Rights Architecture](#compliance--data-subject-rights-architecture) - [Esports Backend Architecture](#esports-backend-architecture) - [Live-Service Calendar Service](#live-service-calendar-service) - [Progression & Codex Service](#progression--codex-service) - [Community & Support Backend](#community--support-backend) - [Per-Platform Store & PPP Pricing](#per-platform-store--ppp-pricing) - [Balance Ops Service](#balance-ops-service) - [Engineering Polish Pipeline](#engineering-polish-pipeline) - [AI Director Service](#ai-director-service) - [Local Multiplayer & Co-op Architecture](#local-multiplayer--co-op-architecture) - [Signature Event Mode Plugins](#signature-event-mode-plugins) - [Privacy-by-Design, DPIA & Sub-Processor Architecture](#privacy-by-design-dpia--sub-processor-architecture) - [Racing Component Architecture](#racing-component-architecture) - [Racing Module Split](#racing-module-split) - [Racing Mode GameFeaturePlugins](#racing-mode-gamefeatureplugins) - [Vehicle Physics Pipeline](#vehicle-physics-pipeline) - [Racing AI & Director](#racing-ai--director) - [Racing Online](#racing-online) - [Vehicle Damage Model](#vehicle-damage-model) - [Racing Replay](#racing-replay) - [Crossover: Racing × Fighting](#crossover-racing--fighting) - [Vehicle Designer Service & Pit Crew Minigame](#vehicle-designer-service--pit-crew-minigame) - [Convoy & Free-Roam Lobby](#convoy--free-roam-lobby) - [Heist Mode Architecture](#heist-mode-architecture) - [Demolition Derby & Crossover Arena](#demolition-derby--crossover-arena) - [VR / AR Architecture](#vr--ar-architecture) - [Hardware Peripherals SDK Integration](#hardware-peripherals-sdk-integration) - [Roguelike, Battle Royale, Sports Vehicle, Specialty Combat Architectures](#roguelike-battle-royale-sports-vehicle-specialty-combat-architectures) - [Persistent World Economy & NPC Schedules](#persistent-world-economy--npc-schedules) - [Director Commentary & Cinematography Pipeline](#director-commentary--cinematography-pipeline) - [Karaoke, Arcade Mini-Games, World Boss, AI Commentary, Vault](#karaoke-arcade-mini-games-world-boss-ai-commentary-vault) - [World Boss Service Contract](#world-boss-service-contract) - [AI Commentary Service Contract](#ai-commentary-service-contract) - [Persistent Economy Service Contract](#persistent-economy-service-contract) - [Real-World Brand & Celebrity Pipeline](#real-world-brand--celebrity-pipeline) - [Launch Readiness](#launch-readiness) - [Sister-Monorepo Integration Surface](#sister-monorepo-integration-surface) - [Sovereign V2 surfaces (never delegated)](#sovereign-v2-surfaces-never-delegated) - [Per-surface mapping (V2 → Oshun owner)](#per-surface-mapping-v2--oshun-owner) - [Generative + procedural pipeline binding](#generative--procedural-pipeline-binding) - [Integration channels](#integration-channels) - [Capabilities V2 forces Oshun to build](#capabilities-v2-forces-oshun-to-build) - [Privacy guard on cross-product entitlement](#privacy-guard-on-cross-product-entitlement) - [Event-name convention](#event-name-convention) - [Resolved decision ledger](#resolved-decision-ledger) - [Missing V2 surfaces from the per-surface mapping](#missing-v2-surfaces-from-the-per-surface-mapping) - [Cross-References](#cross-references) --- ## V2 Product Promise V2 ships as one coherent fighting game that delivers per-ruleset feel matching each inspirational source on its own terms, held together by one shared roster, one shared creator suite, and one shared online backbone. V2 must deliver rollback netcode by default for **1v1 and 2v2 tag** modes (multi-fighter rollback at 60 Hz for 2v2 active fighters per side; 3v3 tag and Royal Rumble / ≥ 30 in-ring modes use client-server with input prediction rather than full rollback), complete launch content across every advertised mode (no "coming soon" panels), and degrade safely under offline, partial-net, low-bandwidth, controller-loss, mid-match-disconnect, and provider-outage conditions. See `V2_features.md` § "V2 Product Promise" for the full list. ## Subsystem Glossary The names below are fixed vocabulary for V2; module names, namespaces, and asset paths inherit from them. **Engine modules** | Module | Responsibility | | ------------------------ | ------------------------------------------------------------------------ | | **V2Core** | Engine subsystems, save game, tags registry, dev cheats | | **V2Gameplay** | GAS abilities, attributes, gameplay effects, match-state machine | | **V2Combat** | Hitbox/hurtbox, frame data, collision authority, juggle/blockstring | | **V2Animation** | AnimBP, motion matching, Mover bindings, IK, retargets | | **V2Input** | Enhanced Input, motion parser, input buffer, deterministic replay | | **V2Netcode** | Rollback engine (1v1 + 2v2 tag), client-server replication (other modes) | | **V2Modes** | Game-mode registry, mode-load orchestration, mode-specific HUD | | **V2UI** | UMG / CommonUI front-end, in-match HUD, accessibility | | **V2Audio** | MetaSounds pipeline, dynamic music, voice barks, commentary | | **V2VFX** | Niagara hit sparks, gore decals, X-Ray render, weapon trails | | **V2Cinematics** | Sequencer presets, slow-mo, finisher cinematics, replays | | **V2Persistence** | Save, profile, currency ledger, offline replay store | | **V2OnlineServices** | Login, friends, parties, matchmaking, leaderboards | | **V2Telemetry** | Event schema, batched sender, balance dashboards feed | | **V2Editor** | Move authoring widget, stage editor, frame-data inspector | | **V2Tests** | Automation specs, gauntlet drivers, golden replay harness | | **V2Racing** | Race-mode glue, registry of `V2RaceMode_*` plugins, race HUD shell | | **V2Vehicles** | Vehicle chassis class, drivetrain, vehicle GAS attribute sets | | **V2RacePhysics** | Chaos vehicle solver, hovercraft / bike-lean / drift physics | | **V2RaceTracks** | Track data, checkpoint graph, racing line authoring | | **V2RaceModes** | Race mode-state machine, lap timing, position ranking | | **V2VehicleAudio** | Engine note, exhaust, tire, surface, racing-music ducking | | **V2VehicleVFX** | Smoke, sparks, debris, motion-blur, damage decals | | **V2Peripherals** | Force-feedback runtime, per-controller-class pool, calibration UI | | **V2Services** | Oshun event-bus + gRPC adapter layer; service observability bindings | | **V2AntiCheat** | Anti-cheat client driver, server-validation hooks, replay-hash emitter | | **V2AdaptiveAI** | Per-CPU adaptive AI, Director hint baking, style-matchup validation | | **V2AICommentary** | AI commentary bridge; routes Iris audio / subtitle output to V2Audio | | **V2DynamicMusic** | Vertical-stack dynamic music, DJ remix, commentary-ducking mix | | **V2FrameDataPublisher** | Public frame-data CSV export + per-patch diff visualizer feed | **Game-feature plugins (modular, hot-swap)** The table below lists the launch-canonical plugin set; the per-celebrity guest plugin and per-venue racetrack plugin are templated and instantiated per license. This roster is the single source of truth — body sections name plugins from it. > **Disk status (2026-06-12):** `V2/ue/Plugins/` currently contains **four V2 > plugins on disk** — `V2AICommentary`, `V2AdaptiveAI`, `V2AssetLinter`, and > `V2Editor` — plus `BellonaUnrealEditor` (synced Bellona editor-consumer > plugin). **None of the `V2Mode_*`, `V2Event_*`, or `V2RaceMode_*` rows below > exist as plugins yet**; they are planned GameFeature plugin surfaces whose > mode identity is currently represented only by the `V2Modes` registry module > (`V2/ue/Source/V2Modes/`). The rows remain the canonical spec for what each > plugin will own when created. | Plugin | Owns | | ------------------------------- | ---------------------------------------------- | | **V2Mode_Arcade** | Arcade ladder mode | | **V2Mode_Story** | Cinematic story mode + branching narrative | | **V2Mode_Tower** | Klassic / Towers of Time / Endless / Survivor | | **V2Mode_Krypt** | 3D first-person Krypt explorable hub | | **V2Mode_BattleHub** | Avatar lobby world, Game Center cabinets | | **V2Mode_WorldTour** | Open-world avatar mode | | **V2Mode_TekkenForce** | Side-scrolling brawler mode | | **V2Mode_DevilWithin** | 3rd-person action-adventure mode | | **V2Mode_Konquest** | MK-style open-realm action-RPG campaign | | **V2Mode_Universe** | WWE-style weekly booker sim | | **V2Mode_MyCareer_WWE** | Wrestling career arc | | **V2Mode_GOATCareer_UFC** | MMA career arc | | **V2Mode_MyGM** | Promoter sim | | **V2Mode_MyFaction** | Card-collector faction battles | | **V2Mode_MyRise** | Story-driven Hero/Heel career | | **V2Mode_RoyalRumble** | 30-/50-entrant rumble | | **V2Mode_FightNight** | UFC Fight Night / PPV booking | | **V2Mode_Chronicles** | Soul Calibur tactical campaign | | **V2Mode_DefJamStory** | Street career with crew progression | | **V2Mode_Crew** | Crew/clique/stable/faction cross-mode | | **V2Mode_Training** | Programmable dummy, lab tools, replay-takeover | | **V2Mode_Mission** | Combat Trials + Mission curriculum | | **V2Mode_Replay** | Replay viewer, takeover, sharing | | **V2Mode_Spectator** | Network spectator + broadcast tools | | **V2Mode_TagTeam** | 2v2 / 3v3 / Trinity / Cross-Assault | | **V2Mode_QuestLog** | Cross-mode quest tracker / weekly objectives | | **V2Mode_StoryTheater** | Per-character side-story cinematic playback | | **V2Mode_SideStory** | Side-story per-fighter unlocked from arcade | | **V2Mode_TimeAttack** | Score-attack ladder against ghost data | | **V2Mode_ScoreAttack** | Score-only ladder variant | | **V2Mode_Wager** | Wager-match online lobby | | **V2Mode_Friendly** | Friendly lobby with custom rules | | **V2Mode_Handicap** | Asymmetric handicap lobby | | **V2Mode_FirstBlood** | First-hit-wins variant | | **V2Mode_Boss** | Solo boss-rush | | **V2Mode_BestOfN** | Best-of-N tournament lobby | | **V2Mode_LAN** | LAN UDP discovery + offline tournament | | **V2Mode_LocalVersus** | Couch versus + hot-seat | | **V2Mode_BattleRoyale** | 100-player BR (fighter / vehicle / hybrid) | | **V2Mode_Roguelike** | Hades-style roguelike adventure mode | | **V2Mode_Karaoke** | Karaoke + rhythm-combat fusion | | **V2Mode_WorldBoss** | Community-shared world boss instance | | **V2Mode_PersistentEcon** | Persistent-world economy + NPC schedule mode | | **V2Mode_VehicleSoccer** | Rocket-League-style sports-vehicle | | **V2Mode_VehicleStunt** | Tony-Hawk-style stunt-vehicle | | **V2Mode_VehicleCrash** | Burnout-style crash-junction | | **V2Mode_Trackmania** | Trackmania-style time-trial | | **V2Mode_BoxingSim** | Punch-Out boxing specialty ruleset | | **V2Mode_BushidoBlade** | One-hit-kill sword specialty ruleset | | **V2Mode_Pinball** | Pinball mini-game cabinet | | **V2Mode_AirHockey** | Air-hockey mini-game cabinet | | **V2Mode_MiniGolf** | Mini-golf mini-game | | **V2Mode_Darts** | Darts mini-game | | **V2Mode_Pool** | Pool mini-game | | **V2Mode_Cooking** | Cooking-simulator mini-game | | **V2Mode_Heist** | 4-player heist co-op | | **V2Mode_TruckChase** | Demolition-derby truck-chase | | **V2Mode_ConvoyRaid** | Convoy-raid demolition mode | | **V2Mode_DemolitionDerby** | Demolition-derby arena | | **V2Mode_CinematographyEditor** | Cinematography library editor (player) | | `V2Mode_CelebrityGuest_` | Per-celebrity-guest one-off mode plugin | | **V2Mode_RhythmCombat** | Rhythm-combat fusion ruleset | | **V2Mode_TekkenBowl** | Tekken Bowl bowling mini-game | | **V2Mode_PhotoTournament** | Photo-Mode jury-vote competition | | `V2ArcadeCabinetAdHocPlugin` | Ad-hoc per-cabinet plugin for Battle Hub | | **V2Event_KingOfIronFist** | Tekken King-of-Iron-Fist signature event | | **V2Event_Marathon** | Marathon endurance event | | **V2Event_WrestleMania** | WWE PPV-style 8-match card event | | **V2Event_FightWeek** | UFC International Fight Week event | | **V2Event_MishimaCup** | Soul Calibur 16-fighter Weapon Master event | | **V2Event_EVO_Top8** | EVO-style Top 8 broadcast event | | **V2Event_CrewWars** | Def Jam 4v4 crew elimination event | | **V2Event_Horde** | Boss-vs-crew asymmetric event | | **V2Event_SpeedrunRace** | 2-4 player Arcade race event | | **V2Event_DeathMatch** | Single-round sudden-death stipulation event | | **V2RaceMode_Circuit** | Closed-circuit lap racing | | **V2RaceMode_PolicePursuit** | NFS-style cop pursuit | | **V2RaceMode_Drift** | Drift score-attack | | **V2RaceMode_CanyonDuel** | NFS Carbon canyon duel | | **V2RaceMode_Drag** | Quarter-mile drag | | **V2RaceMode_OffRoad** | Off-road / dirt-track | | **V2RaceMode_Bikes** | Bike-only mode | | **V2RaceMode_PodRacer** | Futuristic pod-racer | | **V2RaceMode_Combat** | Combat-racing (weapons enabled) | | **V2RaceMode_PowerPlay** | Power-play combat-racing variant | | **V2RaceMode_Free** | Free-roam open-world | | **V2RaceMode_Time** | Time-trial | | `V2RaceTrack_` | Per-licensed-venue tie-in race-track plugin | **Surfaces** | Surface | Path | | ------------------------------ | ------------------------------------------------------------------------ | | Game client | `V2/ue/` (UE5.5 project) | | Marketing / web shell tile | `apps/oshun/web/src/app/v2/` | | Standalone web surfaces | `apps/v2/web/` | | Esports / tournament toolkit | `apps/v2/esports-tools/` (`@v2/esports-tools`) | | Online services backend | `apps/v2/` | | Balance authoring spreadsheets | `V2/balance/` | | Build & release tooling | `V2/ue/Build/`, `V2/tools/release/` (planned — not yet created) | | Localization workspace | `V2/ue/Content/Localization/V2/` + `V2/loc/` (planned — not yet created) | **Web surfaces note.** Two web homes exist and both are canonical for their own split: `apps/oshun/web/src/app/v2/` is the **in-shell product tile** — the V2 entry inside the Oshun shell app (Next.js route with the product page, glossary, roadmap, and public wiki). `apps/v2/web/` is the **standalone marketing / community / dev-portal surface set** — a Vite SPA (marketing homepage with roster, modes, news, store, Discord, esports, tournament, and press surfaces) plus static sub-sites (`calendar/`, `community/`, `support/`, `esports/`, `dev-portal/`, `hub/`, `legal/`, `live-service/`, `balance/`). Product/shell integration work belongs in `apps/oshun/web/src/app/v2/`; public marketing and companion surfaces belong in `apps/v2/web/`. Neither replaces the other. ## High-Level Architecture ```mermaid flowchart TB subgraph CLIENTS["Platforms"] direction LR pc["PC (Win64/Linux/Mac)"] ps5["PlayStation 5"] xsx["Xbox Series X|S"] sw2["Switch 2"] cloud["Cloud Streaming"] pc ~~~ ps5 ~~~ xsx ~~~ sw2 ~~~ cloud end client["V2 Game Client
UE5.5 · C++ gameplay · Blueprint glue · MetaSounds · Niagara"] subgraph MODES["Game Feature Plugins"] direction LR arcade[Arcade] story[Story] tower[Tower] krypt[Krypt] hub[BattleHub] worldtour[WorldTour] tforce[TekkenForce] dwithin[DevilWithin] universe[Universe] career[MyCareer / GOAT] gm[MyGM] faction[MyFaction] rise[MyRise] rumble[RoyalRumble] fnight[FightNight] chron[Chronicles] djs[DefJamStory] crew[Crew] end subgraph CORE["Engine Modules"] direction LR gas[GAS] combat[Combat] anim[Animation] input[Input] net[Netcode] ui[UI] audio[Audio] vfx[VFX] cine[Cinematics] save[Persistence] tele[Telemetry] end services["V2 Online Services
Auth · Matchmaking · Leaderboards · Replays · Moderation"] ac["Anti-Cheat
EAC / BattlEye / Platform-Native"] CLIENTS --> client client --> MODES client --> CORE client --> services client --> ac services --> ac ``` ## Project Layout ```text V2/ ├── V2_TODOS.md Backlog / source of truth ├── V2_features.md Product / feature scope ├── V2_ARCHITECTURE.md This doc ├── V2_DEPENDENCIES.md Dependency registry ├── ue/ Unreal Engine project root │ ├── V2.uproject │ ├── Source/ C++ modules (see "Module Split") │ │ ├── V2.Target.cs │ │ ├── V2Editor.Target.cs │ │ ├── V2Server.Target.cs │ │ ├── V2Core/ │ │ ├── V2Gameplay/ │ │ ├── V2Combat/ │ │ ├── V2Animation/ │ │ ├── V2Input/ │ │ ├── V2Netcode/ │ │ ├── V2Modes/ │ │ ├── V2UI/ │ │ ├── V2Audio/ │ │ ├── V2VFX/ │ │ ├── V2Cinematics/ │ │ ├── V2Persistence/ │ │ ├── V2OnlineServices/ │ │ ├── V2Telemetry/ │ │ ├── V2Editor/ │ │ └── V2Tests/ │ ├── Plugins/ Game-feature plugins (per mode + tooling) │ ├── Content/ Assets (LFS-tracked) │ ├── Config/ Default*.ini, Custom config per platform │ ├── Build/ BuildGraph, target rules, platform configs │ └── Saved/, Intermediate/, DerivedDataCache/, Binaries/ (gitignored) ├── web/ Marketing site ├── services/ Online services backend ├── tools/ Build, release, esports, mocap, data tooling ├── balance/ Spreadsheets driving DataTables (CSV ↔ DT) ├── loc/ Localization workspace └── docs/ Architecture, runbooks, launch, content plans ``` ## Module Split Each module under `Source/` carries `*.Build.cs`, `Public/`, `Private/`, and its module class. Dependencies are declared explicitly; no circular deps. ```mermaid flowchart LR Core[V2Core] Gameplay[V2Gameplay] Combat[V2Combat] Animation[V2Animation] Input[V2Input] Netcode[V2Netcode] Modes[V2Modes] UI[V2UI] Audio[V2Audio] VFX[V2VFX] Cinematics[V2Cinematics] Persistence[V2Persistence] Online[V2OnlineServices] Telemetry[V2Telemetry] Editor[V2Editor] Tests[V2Tests] Core --> Gameplay Core --> Persistence Core --> Telemetry Core --> Input Gameplay --> Combat Combat --> Animation Animation --> Audio Animation --> VFX Combat --> Netcode Modes --> Gameplay Modes --> UI Modes --> Cinematics Modes --> Persistence UI --> Core Cinematics --> Animation Online --> Persistence Online --> Telemetry Editor --> Combat Editor --> Gameplay Tests --> Combat Tests --> Netcode Tests --> Gameplay ``` **Rules** - C++ is the primary gameplay language. Blueprint is for designers / data / state graphs / cinematic glue only. Frame-deterministic combat must live in C++. - No module reaches across more than one layer (e.g., V2UI does not depend on V2Netcode directly). - `V2Editor` is editor-only — never linked in cooked builds. - `V2Tests` is automation-only — never linked in shipping builds. ## Gameplay Ability System (GAS) Layout V2 uses GAS as the spine of combat. Layers: ### Tags - Root tag families authored in `Config/Tags/V2.GameplayTags.ini`. - Subset domains: `State.Stance.*`, `State.Status.*`, `Action.*`, `Cancel.*`, `Rules.Mode.*`, `Style.*`, `Weapon.*`, `Submission.*`, `Position.*`, `Stipulation.*`, `Stage.Hotspot.*`. ### Attribute Sets - `UV2_AttrSet_Vitals` — Health, MaxHealth, RecoverableHealth, Stun, Stamina, Hype, Drive, Heat, Armor, Resolve, Block, Stunmeter. - `UV2_AttrSet_Movement` — WalkSpeed, DashSpeed, RunSpeed, JumpZ, AirControl, SideStepSpeed, BackdashFrames, WakeUpInvulnFrames. - `UV2_AttrSet_Combat` — MeleeDamageMul, BlockReductionMul, ThrowEscapeWindowFrames, CounterHitMul, JuggleScaling. - `UV2_AttrSet_Wrestling` — PinKickoutMeter, SubmissionMeter, LimbDamage, Momentum, SignatureCharge, FinisherCharge, Resilience. - `UV2_AttrSet_MMA` — per-limb stamina, takedown skill / defense, sub skill / defense, transition skill, G&P rating, clinch rating. - `UV2_AttrSet_Weapon` — WeaponDurability, GuardImpactWindow, SoulCharge, RingOutResistance. ### Abilities - Base `UV2_GameplayAbility` with input buffer hook, frame-data binding, cancel-window broadcast, ability-tag filter, network mode switch, replay-strip rules. - Subclasses: Strike, Throw, GroundedSpecial, AirSpecial, Projectile, Super (variants for Drive Impact, Rage Art, X-Ray, Critical Edge, Blazin'), Grapple Clinch, Grapple Takedown, Grapple Pin, Grapple Submission, Cinematic Finisher. ### Gameplay Effects - `GE_Damage_Strike`, `GE_Damage_Throw`, `GE_Damage_Chip`, `GE_Stun_Delta`, `GE_Drive_Cost`, `GE_Heat_Gain`, `GE_Hype_Gain`, `GE_LimbDamage_`, `GE_Stamina_Drain`, `GE_Status_`, `GE_RecoverableHealth_Regen` (modern SF chip recovery). ### Match-State Machine - States: Intro → RoundStart → Live → RoundEnd → (RoundStart | MatchEnd | FinisherWindow | PostMatch). - Per-mode injectable state nodes: MK FinisherWindow, WWE Pin / Submission, UFC RoundEnd judges' interlude, SC RingOut termination, DJ environment-finisher prompt, SF KO replay, Tekken Rage lockout. ## Animation Pipeline ### Skeleton & Retarget - Canonical `SK_V2_Fighter_Base` (UE5 mannequin-compatible) plus archetype variants (Heavyweight, Welterweight, Female, Monster, Child). - IK Rig + IK Retargeter from base to each archetype, with round-trip automation test. ### AnimBP `ABP_V2_Fighter_Base` layers (ordered): 1. Locomotion state machine (idle / walk / run / dash / backdash / airborne / knockdown / wakeup). 2. Upper-body action layer (GAS montage slots: FullBody, UpperBody, LowerBody, Hands). 3. Hit-reaction layer (Chooser Tables keyed on hit-reaction tag × stance × damage-tier). 4. Stance layer (Tekken stance switches, SC weapon stances). 5. Foot IK + look-at IK + opponent-face IK (auto-rotates for 2D rulesets, no-op for free 3D rulesets). 6. Additive emotes / breathing / damage tics. Per-mode AnimBP overlay: SF locks pelvis-yaw to opponent; Tekken adds sidestep blend; WWE adds ragdoll blend and climb/turnbuckle layer; UFC adds full-body grapple and ground-position state machine; SC adds 8-way weapon layer; MK adds X-Ray cinematic insert; DJ adds environment-grab layer. ### Motion Matching & Mover - Motion matching db for World Tour, Tekken Force, Devil Within, DJ street, MyCAREER backstage, SC Chronicles overworld. - Mover 2.0 custom modes: Match2D, Match3DRing, Match3DCage, Match3DStreet, ExplorationFree. ### Cloth, Hair, Facial - Chaos Cloth presets per costume slot, LOD chain. - Hair groom for principals; card hair for crowd. - Chaos Flesh (limited) for MK X-Ray gore. - MetaHuman Animator for principals; Live Link Face for performance capture. ## Input Pipeline - Enhanced Input + IMC per platform (PS5 with DualSense haptics + adaptive triggers, XSX, Switch2, PC KB+M, PC gamepad, mobile touch). - Motion-input parser recognizing QCF / QCB / DP / RDP / HCF / HCB / 360 / 720 / charge-back / charge-down / negative-edge / double-tap / plink / just-frame. - Buffer window configurable per fighter / per move (default 6f, tight 3f, lenient 9f). - Special-cancel, super-cancel, X-Ray / Heat / Drive cancel buffers. - WWE / UFC contextual input (single button → context-aware grapple). - Deterministic byte-stream input encoder for replays. ## Game Feel: Hitstop, Hitlag, Camera Shake V2's game-feel system is centralized so each ruleset hits like the source it's emulating. - **HitConfirmed broadcast** from `UV2_HitboxComponent.OnHitConfirmed` carries a struct (attacker, defender, damage, hit-reaction tag, counter-hit flag, hitstop attacker frames, hitstop defender frames, hitlag defender frames). - **Hitstop curves** authored per damage tier (small / medium / heavy / launcher / bone-shatter / finisher) and stored as `UCurveFloat` referenced from `URV2_Ruleset.HitstopCurves` — so MK / SF / Tekken / SC / UFC / WWE / DJ all feel distinct. - **Camera shake** library keyed on hit-reaction tag × per-ruleset intensity multiplier × per-fighter shake personality. Reduced-motion accessibility clamp. - **Slow-mo / freeze-frame** triggered by match-state events (KO, finisher window, Reversal-Edge clash, mid-combo emphasis). - **Screen tint / vignette** triggered by gameplay events (counter-hit, low-HP, comeback aura, state-aura). - **Resimulation safety**: hitstop frames don't count toward rollback budget (cross-ref Rollback Netcode); cosmetic-only effects suppressed during resim. - **Tuning tool**: editor utility widget loads any move and previews the feel curves; side-by-side replay harness compares ruleset profiles. ## Combat Authority & Determinism ### Per-Frame Loop - Fixed 60Hz sim step. Decouple render (interpolated) from sim (deterministic). - Per-tick sequence: (1) consume input → (2) tick abilities + state → (3) advance animation timers → (4) sweep hitboxes → (5) apply gameplay effects → (6) emit cosmetic events (deferred to render). ### Determinism Rules - No `FApp::GetDeltaTime` reads in gameplay; sim-clock only. - No `FMath::RandRange` in gameplay; use `FRandomStream` seeded from match seed. - No system wall-clock in gameplay graphs (Editor Validator enforces). - Strict-FP build flag; deterministic cook order. - Blueprint guard list: forbid nodes (Time, World Delta Seconds, Random, Now, GetSystemTime). ### Hitbox Authority - In rollback modes: shared deterministic simulator decides; no per-hit server arbitration. - In client-server modes: host authoritative; clients predict; server confirms within RTT/2 + 2 frames. ## Rollback Netcode ### Architecture - `FV2_SimWorld` (deterministic, 60Hz) separated from `FV2_PresentWorld` (interpolated, display refresh). - Snapshot/restore for `FV2_SimWorld`: ASC, attributes, ability state, anim timers, hitbox state, input buffer, RNG. Budget ≤ 8KB per fighter. - Input prediction = last-confirmed; correction triggers rewind + resimulation forward. - Rollback budget ≤ 8 frames; beyond that, "Recovering Connection…" overlay. - Cosmetic suppression during resimulation (audio mute, particle suppress). ### Transport - UDP with FEC, sequence numbers, ACK piggyback, DTLS encryption. - UE Iris for non-rollback channels (chat, presence); custom socket for rollback frame inputs. - Adaptive send: every-frame inputs + last-N replay piggyback. ### Diagnostics - Netgraph overlay (RTT, rollback frames last 5s, packet loss %, input delay, frame advantage). - Telemetry feeds every rollback for postmortem. ## Client-Server Netcode - Dedicated server target `V2Server.Target.cs` (Linux). - Replication graph: own pawn (priority 1.0), nearby fighters (0.8), distant (0.3), ambient props (0.1). - Multi-fighter: tag-team (2v2, 3v3), 4-player FFA, Royal Rumble (≥ 30 in-ring). - Open-world: co-op handshake (party ≤ 4); instance handoff at indoor zones / fight encounters / story beats; tolerant of 250ms RTT. - Hubs: shared social server (capacity 100) with auto-shard and friend-priority. ## Network Quality & Fallback ```mermaid flowchart LR Match[1v1 Match Start] --> Handshake[Pre-Match Network Handshake] Handshake -- RTT/jitter/loss --> Decision{Quality OK?} Decision -- Yes --> Rollback[Rollback Netcode 60Hz] Decision -- Borderline --> Hybrid[Hybrid Rollback + Delay] Decision -- Poor --> Delay[Delay-Based Netcode N-frame buffer] Rollback -- rewinds > 8f sustained 30s --> Offer[One-Time Fallback Offer] Offer -- Accept --> Delay Offer -- Decline --> NoContest[Ranked No-Contest] Match -- LAN-mode --> LAN[LAN UDP Broadcast] ``` - **Rollback default** for 1v1; **delay-based fallback** for RTT > 150ms or sustained rewind pressure; **hybrid** in-between. - **LAN tournament mode**: UDP broadcast peer discovery, no internet required; LAN-only ranking ledger; auto-on at tournament-venue WiFi SSIDs. - **Dedicated server browser** (PC primary; console where TRC permits) with public listings, host config (ruleset, stipulation, fighter restriction, password, AFK kick, rotating-map list), server moderation. - **Custom Room / Private Lobbies**: 1v1 / 2v2 / 4-corner / tournament / Battle Royal / Royal Rumble; ≤ 16 participants + 8 spectators; in-room queue (winners-stay-on, losers-rotate-out, randomized seating); in-lobby training space for spectators. - **Pre-match handshake** measures RTT, jitter, packet loss; results stamped in match record; player can decline poor-condition match. - **Wi-Fi / mobile-hotspot / 4G/5G detection** + warning in ranked queue (where platform API provides connection type). - **Per-account network reliability score** with ops dashboard. ## Game Modes Each mode is a `UGameFeaturePlugin` registered with `V2Modes`. Plugin lifecycle: ```mermaid sequenceDiagram participant Player participant V2Modes participant Plugin as V2Mode_X Plugin participant Gameplay as V2Gameplay participant UI as V2UI Player->>V2Modes: Select mode (e.g., Story) V2Modes->>Plugin: Activate Plugin->>Gameplay: Register ruleset + GAS abilities Plugin->>UI: Inject mode-specific HUD widget Plugin-->>V2Modes: Mode ready V2Modes-->>Player: Start mode Note over Player,Plugin: Mode plays... Player->>V2Modes: Exit mode V2Modes->>Plugin: Deactivate Plugin->>Gameplay: Unregister Plugin->>UI: Remove HUD ``` ### Per-Mode Architecture Notes | Mode | Net model | Save model | Notable | | ------------------ | ------------------------------------ | ---------------------- | ------------------------------------ | | Arcade | Local-only | Per-fighter progress | CPU ladder; mid+end-boss cutscenes | | Story | Local-only | Branch state + chapter | Sequencer cutscenes; QTE prompts | | Tower | Local-only | Tower state | Live modifier engine (server-pushed) | | Krypt | Local-only | Vault unlock state | 3D explorable hub | | BattleHub | Client-server (hub) + rollback (cab) | Avatar profile | 100-cap shards | | WorldTour | Client-server (zone) | Quest state | Master training pipeline | | TekkenForce | Local + co-op (CS) | Score / progress | Side-scroller brawler | | DevilWithin | Local-only | Save points | 3rd-person action | | Universe | Local-only | Universe save | Auto/manual booker sim | | MyCareer (WWE) | Local + online ranked | Career save | Branching narrative | | GOATCareer (UFC) | Local + online ranked | Career save | Camp / weight management | | MyGM | Local + multi-GM (CS) | Promotion save | Up to 4 GMs shared | | MyFaction | Local + online | Faction save | Card collector + faction PvP | | MyRise | Local-only | Career save | Voice-acted milestones | | RoyalRumble | Rollback (1v1) + CS (30-/50-) | n/a | Timed entries | | FightNight | Local + online ranked | Event save | PPV presentation | | Chronicles | Local-only | Campaign save | Turn-based hex grid | | DefJamStory | Local-only | Career save | Crew, rep, shop | | Crew | Online (CS) | Crew save | Cross-mode | | Training | Local-only + opt-in online lab | Lab scenarios | Programmable dummy, lab overlays | | Mission | Local-only | Per-fighter mastery | Trials + missions + tutorial | | Replay / Spectator | Local + online (read-cloud) | Cloud replays | Takeover from any frame | | TagTeam | Rollback (2v2/3v3) + CS (crews) | Per-team profile | Tag-cancel / DHC / assist / X-Factor | ## Training, Trials, Replay Pipeline ```mermaid flowchart LR Match[Live Match] -- captures --> Recorder[Input Stream Recorder] Recorder --> ReplayFile[(Replay File · header + inputs + seed + manifest)] ReplayFile --> CloudReplay[Cloud Replay Store] ReplayFile --> Viewer[Replay Viewer] Viewer --> Takeover[Replay Takeover] Takeover -- pause + take side --> Training[Training Mode Scenario] ReplayFile -- encode --> Ghost[Ghost Data Store] Ghost --> Tekken[Tekken Ghost Battle] Ghost --> Master[World Tour Master Training] Training -- Save as Lab Scenario --> ReplayFile Match -- pause SP --> Photo[Photo Mode] ``` - **Sim/Present split** (cross-ref Rollback Netcode): training mode runs on the same deterministic `FV2_SimWorld` as live matches; lab tools attach to `FV2_PresentWorld` for overlays without affecting determinism. - **Replay file format**: header (build ID, content hash, ruleset ID, fighter IDs, stage ID, custom-cosmetic manifest, RNG seed, timestamp) + per-frame input stream both sides. Budget ≤ 1MB / 5-min match; gated in CI. - **Replay determinism gate**: every replay re-played in CI must produce bit-identical frame outcomes; replays that drift fail the build. - **Replay Takeover**: pause replay → snapshot sim state → load training scenario → swap input source for chosen side. Original replay preserved read-only. - **Multiplayer training**: uses client-server net (`V2Server.Target.cs`) not rollback — tooling-rich semantics over response time. Tolerates ≤ 250ms RTT. ## Character Presentation Pipeline ```mermaid flowchart LR MatchSetup[Match Setup] --> IntroPicker[Intro Picker] IntroPicker -- fighter A + fighter B + stage + round + ruleset --> DialogueDB[Dialogue DB · CSV → DT] DialogueDB --> IntroSeq[Intro Sequencer] IntroSeq --> VOPlayer[VO Player] IntroSeq --> CameraRig[Cinematic Camera Rig] MatchEnd[Match End] --> WinQuotePicker[Win/Loss Quote Picker] WinQuotePicker --> DialogueDB DialogueDB --> OutroSeq[Outro Sequencer] Gameplay[Gameplay Events] --> BarkRouter[Bark Router] BarkRouter --> BarkLibrary[Per-Fighter Bark Library] ``` - **Dialogue DB**: per-fighter CSV at `V2/balance/dialogue/.csv` with columns (situation, opponent, ruleset, line ID, locale-x text, VO path, emotion, length-cap). CSV ↔ DataTable round-trip enforced. - **Intro Picker** selects from per-character / per-matchup / per-stage / per-round / mirror-match dialogue banks. Mirror matches use a uniquely-authored bank, never the cross-matchup pool. - **Win Quote Picker** selects context-aware win quotes per opponent / per finisher / per perfect-round / per comeback / per ring-out / per pinfall / per submission / per KO / per double-KO; per-matchup A-beats-B quotes override generic-bank quotes when authored. - **Bark Router** consumes gameplay events (counter-hit, throw, parry, low-HP, combo-of-N, finisher armed, finisher missed) with priority + cooldown; finisher / KO barks win all races. - **Per-fighter Entrance**: Sequencer preset library (WWE ramp, Tekken stage-arrival, MK pit-summon, SF6 hub-arrival, DJ club-strut) with per-fighter music slot. ## Tag-Team Architecture ```mermaid flowchart LR P1Input[P1 Input] --> SimSide1[Sim - Side 1 Active Fighter] SimSide1 -- tag cancel / assist call --> SimSide1B[Sim - Side 1 Partner] P2Input[P2 Input] --> SimSide2[Sim - Side 2 Active Fighter] SimSide2 -- tag cancel / assist call --> SimSide2B[Sim - Side 2 Partner] SimSide1 -- HP --> HUD SimSide1B -- HP regen off-screen --> HUD SimSide2 -- HP --> HUD SimSide2B -- HP regen off-screen --> HUD ``` - **Rollback for 2v2 / 3v3**: each side has 1-3 fighters; `FV2_SimSnapshot` budget per side ≤ 24KB (3 fighters × 8KB). Tagging is a deterministic state transition with frame-accurate animation handshake. - **Tag-cancel matrix**: per-fighter / per-partner allow-list in the move catalog spreadsheet; restrictions for licensed-IP partners. - **Snapback / DHC / X-Factor / Cross Assault** are abilities in `V2Gameplay` with their own GAS subclass; meter costs tracked in attribute set. - **Crew battle queue** (3v3 KOF single-elim): client-server because matches can rotate fighters mid-set; per-fighter HP carry-over rules. ## Persistence & Profile - `UV2_SaveGame` slots per platform / per user. - Schema: profile, per-mode career progress, unlocked content, loadouts, settings, photo-mode gallery, replays. - Cloud save via OnlineServices; conflict resolution UI on out-of-sync. - Currency ledger: Koins, Hearts, Soul Fragments, Krystals (premium), in-mode currencies (MyCareer XP, MyFaction tokens, DefJam cash). `@maat/finance` owns spend, refund, region-aware pricing, regulatory caps, and sync reconciliation; `V2Persistence` keeps the offline ledger cache. - Save migration framework: every save record carries a version + migrator; no destructive loads. ## Online Services Backend ```mermaid flowchart TB Client[V2 Client] --> Gateway[API Gateway / EOS Online Services] Gateway --> Auth[Auth Service] Gateway --> Friends[Friends / Presence] Gateway --> Party[Party Service] Gateway --> MM[Matchmaking] Gateway --> Lobby[Lobby Service] Gateway --> Rank[Ranked / Leaderboards] Gateway --> Replay[Replay Cloud] Gateway --> Ghost[Ghost Data Store] Gateway --> Store[Cosmetic Store] Gateway --> Mod[Moderation Console] Gateway --> Tele[Telemetry Ingest] MM --> SkillRank[(Glicko2 / TrueSkill2)] Replay --> Storage[(Object Storage)] Ghost --> Storage Tele --> Warehouse[(Analytics Warehouse)] Mod --> Storage ``` - OnlineServices abstraction (EOS baseline; Sony NP, MS Live, Switch SDK shims via platform-specific subsystems). - Friends, presence, parties (≤ 8), invites. - Per-mode matchmaking queues with Glicko2/TrueSkill2, region weighting, ping cap, expansion over wait time, role-pref balancing for tag/FFA. - Per-mode ranked ladder with seasonal reset, placement, promotion/ demotion thresholds. - Cloud replay storage with share-by-code, cloud library, local download. - Ghost-data store for Ghost Battle and master training. **Service contract** - **gRPC services:** `libs/proto/v2/online/auth.proto`, `friends.proto`, `party.proto`, `matchmaking.proto`, `lobby.proto`, `rank.proto`, `replay.proto`, `ghost.proto`, `store.proto`, `moderation.proto`, `telemetry.proto`. - **Key methods:** - `Auth.SignIn(platform_token) → session`, `Auth.Refresh(refresh_token) → session`. - `Friends.ListFriends(account_id) → list`, `Friends.Add(target_id) → ack`, `Friends.UpdatePresence(state) → ack`. - `Party.Create() → party_id`, `Party.Join(party_id, account_id) → ack`, `Party.Invite(target_id, party_id) → ack`. - `Matchmaking.SubmitTicket(mode, prefs) → ticket_id`, `Matchmaking.PollTicket(ticket_id) → status_or_match`, `Matchmaking.CancelTicket(ticket_id) → ack`. - `Rank.GetLadder(mode, region, page) → ladder`, `Rank.RecordMatch(match_result) → ack`. - `Replay.Upload(stream) → replay_id`, `Replay.Download(replay_id) → stream`, `Replay.Share(replay_id, visibility) → share_code`. - `Store.ListCatalog(region, currency) → catalog`, `Store.PurchaseEntitlement(item_id, platform_token) → entitlement`. - **Event-bus publishes:** `v2.player.session.started`, `v2.player.session.ended`, `v2.match.ended`, `v2.match.replay.hash`, `v2.player.reported`, `v2.cosmetic.purchased`, `v2.party.created`, `v2.party.disbanded`, `v2.matchmaking.ticket.completed`. - **Event-bus subscribes:** `kuanyin.action.taken`, `themis.appeal.resolved`, `maat.balance.recommendation`, `iris.commentary.generated`. - **SLOs:** matchmaking ticket p50 ≤ 12 s, p99 ≤ 35 s under 5× expected launch concurrency; auth p99 ≤ 200 ms; replay upload p99 ≤ 8 s for a 10-MB replay; service availability ≥ 99.9% per region. - **Owner:** V2 online services team. **Cost-tier:** standard AWS / EOS bill; ceiling at `V2/docs/cost/online-services.md`. ## Anti-Cheat V2 anti-cheat layers four lines of defense: kernel-level client drivers, server-side input + state validation, ML pattern classifiers, and a replay-based investigation pipeline. The anti-cheat client lives in `V2/ue/Plugins/V2AntiCheat/` and is part of the sovereign-core surface (arch§"Sovereign V2 surfaces (never delegated)"); kernel-driver hot-patch is forbidden. **Client-side surface** - **PC:** Easy Anti-Cheat (EAC) as primary; BattlEye as fallback for titles where EAC has integration friction. Kernel-level driver signed by Epic's EAC chain; init at process launch; teardown only via clean shutdown. - **Consoles:** Platform-native anti-cheat — Sony **PSN ban-list** integration + Sony platform anti-tamper; Microsoft **TruePlay** + Xbox Live ban list; Nintendo **NEX integrity** layer. No third-party kernel driver on console. - **Steam Deck (PC mode):** EAC Linux build via Proton; verified pre-launch. **Server-side validation contract** - Input rate sanity (≤ 180 inputs / second per player; bursts > 240 trigger flag). - Attribute integrity: every gameplay-effect application checked against per-ability whitelist; mismatched application = match-invalidate + flag. - Replay drift detection: every match emits a golden-replay hash to `v2.match.replay.hash` event; server re-simulates 1% of matches end-to-end on a Linux validator pool; drift > 0 frames = flag + manual review. - Rate-limit: matchmaking submissions, friend requests, ranked queue dodges capped per minute per account. **ML cheat classifiers (`@v2/nous-anti-cheat-classifiers` over `@nous/training` + `@nous/safety`)** - V2 publishes labeled fair-play examples on `@oshun/event-bus` topics for match completion, player skill profile updates, ranked point deltas, tournament completion, replay evidence, session starts, account geo changes, and region entitlement checks. - `@nous/training` owns the offline training loop for smurf, win-trading, coordinated-throw, and geographic-anomaly classifiers. The V2 bridge requires clean and positive labels for every classifier before a training plan is valid. - `@nous/safety` hosts `V2/docs/ai/model-cards/anti-cheat-classifier-suite.md`. The Model Card declares the suite limited-risk, review-only, appealable, and off-rollback. - The V2 bridge also publishes the review-only classifier suite event through `@oshun/audit-platform`; V2 publishes anti-cheat audit evidence while Oshun retains and exports the forensic record for investigations. - Classifier output can prioritize fair-play review queues; it cannot issue automatic discipline and cannot influence deterministic rollback frames. **Investigation + appeals** - Replay-based investigation tool at `V2/tools/cheat-investigation/` lets ops load any flagged match, scrub frame-by-frame, view raw input stream, attach notes. Tool emits `v2.cheat.investigation.opened` and `v2.cheat.investigation.closed` events. - Appeals flow via `@v2/themis-dispute-resolution` over `@themis/dispute-resolution` Statement-of-Reasons API (DSA-compliant). Appeal resolution SLA: 7 calendar days; failure to resolve triggers escalation to a senior reviewer. - False-positive rate target: ≤ 0.5% of total bans overturned on appeal; ≥ 0.5% triggers a model retrain. **Rage-quit penalty** - First quit in a ranked session: 5-minute matchmaking cooldown. - Second within 24h: 30-minute cooldown + 50 rank points. - Third within 24h: 24-hour ban from ranked + 150 rank points. - Tournament context: any rage-quit forfeits the match per `@uzume/broadcast` rules. **Cert constraint:** All four platforms require AC enabled at launch for cross-play; CI gate `Tools/check-anti-cheat-cert.py` asserts EAC + BattlEye manifests are present in PC build, platform-native AC bindings are present in console builds, and the appeal-flow Statement-of-Reasons API is reachable in staging. ## Cross-Play & Cross-Progression **Cross-play scope** - **Cross-play enabled by default** for ranked 1v1 / 2v2 tag, custom lobbies, Battle Hub, and World Tour across PC, PS5, PS5 Pro, XSX, and Switch 2. - **Per-platform opt-out:** Sony / Microsoft / Nintendo each expose a system cross-play toggle; V2 reads the toggle on session start and reflects it in matchmaking ticket. Toggle changes mid-session do not affect the current match. - **Steam Deck** treats as PC for cross-play purposes; Steam Deck Verified rating is launch-blocking. - **iOS / Android companion app** is read-only out-of-game; not a play surface. - **Input-method pairing:** each ticket carries `InputClass.{KBM, Gamepad, FightStick, FightPad, ArcadeStick, AdaptiveController}`; cross-class matchmaking is opt-in per-mode. KBM ↔ Fight Stick is on by default in unranked; opt-in only in ranked. Adaptive controllers always opt-in for both sides. **Cross-progression scope** - **Account binding:** `@oshun/identity` is the single account root; per-platform shadow accounts (PSN / Xbox Live / Nintendo Account / Steam) bind to one Oshun account. `@v2/oshun-identity-binding` composes the shared `@oshun/identity` contract for V2 services, and Unreal mirrors it with `FV2OshunIdentityAccountBinding`; re-binding requires a 30-day cool-off and a TOTP step. - **Shared state:** profile, currency ledger (Crowns + per-platform IAP credit), cosmetic inventory, fighter unlocks, ranked rank, Battle Pass progress, Krypt progress, MyCAREER save, MyFACTION roster, replay archive. - **Per-platform-only state:** platform achievement / trophy IDs, platform store entitlements that the platform forbids transferring (e.g. Sony bonus cosmetic from a PS5 disc bundle is PS5-only by Sony cert). - **Conflict resolution:** save-game version tracked per save; merge on account first-login per platform uses `last-write-wins` for non-cosmetic state and `union-of-unlocks` for cosmetic / fighter unlocks. - **Entitlement-claim API:** `@oshun/identity` exports the signed claim contract in `v2-entitlement-claims.ts`; `@v2/cross-product-entitlement` consumes the claims for V2 grants and documents the runtime contract at `V2/docs/integration/cross-product-entitlement.md`. **Cert-blocking edge cases** - Voice chat: cross-platform voice routed through Iris voice; **each platform family chat** stays on platform-native channels per TRC. - Reporting: cross-platform report submission allowed; per-platform reporting duties (mandatory PSN report routing) preserved. - Banning: Oshun-side bans apply across all platforms; platform-side bans apply only on that platform. - Region-locked content (e.g. Korean variant of a fighter costume): cosmetic inventory entry is region-stamped; cross-region accounts see the cosmetic as locked rather than seeing the wrong variant. **CI gates:** `Tools/check-cross-play-cert.py` validates input-class enumeration matches per-platform TRC; `Tools/check-cross-progression.py` validates the per-platform-only state list against each platform's lotcheck docs. ## Audio Pipeline - Native pipeline: MetaSounds + Audio Modulation as the baseline. Wwise as optional middleware if production needs exceed engine native (decision documented in `V2_DEPENDENCIES.md`). - Per-fighter footstep / cloth / weapon foley layer. - Per-fighter voice bank (idle, taunt, intro, victory, defeat, KO, finisher, staredown). - Per-mode commentary banks (WWE play-by-play + color; UFC commentary pair; SC narrator; SF announcer; MK announcer; DJ DJ). - Bark trigger system on gameplay events. - Dynamic music: vertical-stack per match (ambient → tension → climax → KO sting); DJ-style remix for DJ ruleset. - Custom soundtrack import: PC mp3/flac/ogg/wav; console where TRC allows; streaming where licensed. - Spatial audio: Atmos / Tempest3D / Dolby; binaural HRTF fallback. ## VFX Pipeline - Per-style hit-spark library (clean, dust, metal, electric, fire, ice, spirit, blood). - Blood decal pipeline (env projection + vertex paint), gore-tier toggle. - Limb severance / dismemberment (MK-only). - X-Ray render pass (translucent skin + bone stencil overlay + per-bone break states). - Stage hazard effects. - Weapon ribbon trails per weapon profile. - Aura effects: Devil-form, Soul Charge, Heat, Burnout. ## Cinematic Pipeline **Per-ruleset Cine Camera Rigs.** Seven baseline rigs (MK / SF / Tekken / WWE / UFC / SC / DJ) plus the racing camera. Each rig is a `UCineCameraComponent` preset with target distance, FOV, DOF target, look-ahead, post-process override, and per-event lerp curves. Rigs are data-only assets at `Content/Cameras//Rig_.uasset`; selection driven by gameplay-tag state. **Auto-cinematic triggers** - KO last hit: time-dilation curve from `Content/Curves/KO_.uasset` (0.10× for MK Fatal Blow → 0.35× for SF Drive Impact). - Finisher window: full Sequencer take-over (`Content/Sequences/`); player input dropped for the duration; replay re-enters live state at next RoundStart. - Round-clinching hit: half-second slow-mo + camera push-in. **Replay viewer + export** - Replay container is the same deterministic input stream V2Netcode produces; the viewer re-simulates the match from inputs. Saved at `~/V2/Replays/.v2replay` (versioned). - Editable camera + timeline overlay on top of replay re-sim. Camera edits are non-destructive — they layer on top of the original input replay. - **MP4 export** via MoviePipeline + encoder priority (see deps§"Media encoding"): NVENC → AMF → VideoToolbox → Quick Sync → FFmpeg software. 1080p60 default; 4K60 + HDR opt-in. Per-export NIL / IP-rights check via `@themis/likeness` (forthcoming) and `@v2/aphrodite-licensed-likeness-safety`; export is blocked if the match contains a fighter whose NIL grant window has expired or whose licensed-fighter likeness safety gate has been revoked. **Photo Mode** - Mid-match pause-side capture (offline only) and replay-side capture (always-on). - Rotation / DOF / filters / stickers / frames data-driven from `Content/PhotoMode/`. - **NIL gate:** every photo carries a `LikenessRightsManifest.json` that `@themis/likeness` validates before share. Photos with expired-rights fighters are saved locally but cannot be shared online. - **C2PA provenance:** every shared photo includes a C2PA manifest stamping origin (player, timestamp, fighter list, stage); cross-ref `Yemaya living scenes provenance` already shipped in V1. **Sequencer-preset library** - Per-mode: walkout, ring entrance, octagon walkout, DJ club entry, stage transition, mid-fight cinematic, finisher, ending — all under `Content/Sequences///`. - Per-fighter signature stage entrance overrides at `Content/Sequences/Fighter//Entrance.uasset` (see arch§"Per-Fighter Signature Library Architecture"). **Performance + cert** - Cinematic render budget: ≤ 16.6 ms / frame at 60 Hz on PS5; ≤ 8.3 ms at 120 Hz mode. Cinematic spikes deferred to next safe frame rather than dropping below target. - MP4 export cert: per-platform encoder pin verified in `V2/ue/Config/Engine.ini`; PSN ShareStream / Xbox Game DVR integration verified pre-launch. ## UI / HUD Architecture V2 UI is built on **CommonUI 5.5** with the activation framework. Widgets are all UMG + MVVM (ModelViewViewModel) — no direct ASC access from widget code; widgets bind to `UViewModel` instances that mirror ASC attributes. **Layer architecture** - **Front-end** (`V2/ue/Content/UI/FrontEnd/`): CommonUI activation tree. Root activations: `MainMenu` → (`PlayMenu` | `OnlineMenu` | `CreatorSuite` | `Krypt` | `Settings` | `Codex` | `BattleHub`). - **In-match HUD** (`V2/ue/Content/UI/InMatch/`): per-ruleset overlay assets composed from a shared `W_HUD_Base`. Per-ruleset overlays (MK / SF / Tekken / WWE / UFC / SC / DJ) inject their meter widgets via the `IRulesetHUD` interface; mode-plugin overlays (Royal Rumble entrants strip, UFC scorecard interlude, WWE booking shoutout) inject via `IModeHUD`. - **Per-mode HUD injection contract:** every GameFeaturePlugin that needs HUD surface declares `HUDInjections` in its `.uplugin`; on plugin activation, the V2UI subsystem loads the listed `UCommonActivatableWidget` classes into named slots (`Slot.TopLeft`, `Slot.TopRight`, `Slot.Center`, `Slot.Bottom`). - **Notification center** (`W_NotificationCenter`): toast queue + persistent drawer. Toast types: `FriendOnline`, `PartyInvite`, `TournamentRoundPing`, `DailyChallengeComplete`, `BattlePassTier`, `RankUp`, `ModerationAction`, `SystemMaintenance`. Rate-limited at 1 toast / 2s; queue overflow → drawer. - **Settings panels** (`W_Settings_*`): Video, Audio, Controls (rebind), Gameplay (per-ruleset assists, gore tier, tutorial reminders), Accessibility (cross-ref arch§"Accessibility"), Network, Account, Privacy (cross-ref arch§"Security, Privacy, Compliance"). Each panel binds to a single `UViewModel`; settings persist via `@oshun/persistence`. **MVVM contract** - Every ASC attribute referenced by HUD has a corresponding `FObservable` property on `UMatchViewModel`; attribute change notifications flow through the viewmodel, never directly to widgets. This keeps widget code free of GAS includes and makes HUD testable without a live match. - Per-match viewmodel created on `RoundStart`, destroyed on `MatchEnd`. - ViewModels for non-match HUD (notification center, friend list) live on the `UV2UISubsystem` (LocalPlayer subsystem). **Accessibility hooks** - HUD scale slider: 75–150% in 5% steps; per-widget min-readable-size constraint asserted at design time (warns if rescale would drop a label below 18 px on a 1080p target). - Reduced-motion variant: every animated widget has a `Reduced` static variant; the V2UISubsystem swaps at runtime when the accessibility toggle changes. - Colorblind palettes: 4 palettes (Protanope / Deuteranope / Tritanope / Monochromacy) applied via `UColorPaletteSubsystem`; every widget pulls semantic colors through the palette, never a raw hex. - Screen-reader bridge: NVDA / JAWS / VoiceOver / TalkBack via `@v2/iris-accessibility` over `@iris/accessibility`; in-match descriptions and real-time match captions use `@v2/psyche-caption-streaming` over `@psyche/caption-streaming`, menu trees use the platform-native screen-reader API, and every focusable widget carries an `AccessibilityDescription` text token. **Tutorial system** - Per-ruleset interactive tutorials (8–12 lessons per ruleset) live as Sequencer-driven UMG overlays composed with a sandbox training-mode match. - Input-diagram overlay: shared `W_InputDiagram` shows controller / KBM / fight-stick / fight-pad bindings; pulls from the active IMC. - Frame-data overlay: `W_FrameDataOverlay` reads from `DA_Move_*` data assets via the Sophia frame-data RAG (cross-ref arch§"Per-Fighter Signature Library Architecture"). Every release-candidate cook runs `@v2/sophia-release-candidate-ingestion` over the frame-data spreadsheet and patch-notes corpus through `@sophia/ingestion` before cook artifacts are produced. - Hit-reaction trainer: a `W_ReactionTimer` widget under training mode shows hit-confirm windows in real time. **Performance budget** - HUD render budget: ≤ 0.6 ms / frame at 60 Hz; ≤ 0.3 ms at 120 Hz. - Widget tree depth caps at 16 to keep the slate prepass under budget; designer-time linter `Tools/check-widget-tree-depth.py` fails the build on violations. ## Telemetry & Analytics - Event schema covering standard taxonomy events for session start/end, level load, death, achievement, purchase, UI interaction, error, plus match lifecycle, move usage, damage dealt/received per move, combo length, meter usage, finisher trigger rate, rage-quit, crash, frame budget exceedance. - V2Telemetry publishes canonical `@oshun/event-bus` topics under `v2.match.*`, `v2.cosmetic.*`, and `v2.player.*`; it does not publish to a V2-only telemetry ingest endpoint. - Backend ingest with PII strip at ingest. - Balance dashboards (pick rate, win-rate-on-hit, win-rate-on-block, frame-data drift, hot/cold heatmaps). - A/B framework for balance changes with rollback. - Ghost data capture (opt-in). - Telemetry opt-out persistent across save reset. ## Asset Budget & Streaming - **Per-fighter polygon budget**: principals ≤ 80k tris LOD0, mid-roster ≤ 60k, crowd ≤ 25k; LOD chain to LOD3 / impostor. - **Texture memory budget per fighter**: ≤ 64MB at 4K texture pack, ≤ 32MB at 2K base, ≤ 8MB at 1K Switch2. - **Animation budget**: ≤ 800 unique anims per fighter; sharable generic anims pooled in `Content/Animation/Shared/`; total compressed package ≤ 80MB per fighter. - **Audio budget**: per-fighter VO + foley + barks ≤ 50MB per locale at 48kHz Opus. - **Per-stage budget**: ≤ 4M tris LOD0; texture ≤ 256MB at 4K pack; VFX GPU ≤ 4ms at 4K; audio ≤ 30MB per locale. - **Streaming pool sizes**: PS5 / XSX 4GB, PC scalable to 8GB, Switch2 1.5GB. - **Asset chunking** per-fighter: character / voice / base-costume / alt-costume / cosmetic-pack chunks for incremental install + DLC. - **Texture streaming priority**: in-match visible fighters + stage prioritized; off-screen partner fighters demoted. - **Crowd LOD**: instanced static mesh + bone-animated impostor at distance. - **Asset audit** weekly: orphan / oversize / missing-LOD / missing-skin / redundant-material report (cross-ref §57). ## Hotfix, Quick-Resume, Crash Recovery, DRM ```mermaid flowchart LR Server[Hotfix Manifest Server] -- signed manifest --> Client[Game Client] Client -- offline match --> Local[Local Hotfix Values] Client -- online match --> Enforced[Server-Enforced Values] Tournament[Tournament Mode TO] -- freeze snapshot --> Replay[Replay Header] Crash[Mid-Match Crash] --> Reporter[Crash Reporter] Reporter -- symbolicated --> Tele[Telemetry] Reporter -- replay attached --> Ops[Ops Console] Sleep[Console Sleep / App-Switch] --> QR[Quick-Resume State] QR --> Resume[Resume on Wake] ``` - **Server-driven balance hotfix** (data-only): tunable values for damage, frame data, meter cost, drive cost, finisher conditions — within bounds the anti-cheat trusts. - **Hotfix manifest** signed + versioned; offline match honors local hotfix; online enforces server hotfix; rollback capability on failed canary. - **Tournament Mode** freezes hotfix at TO snapshot; snapshot stored in replay header. - **Mid-match crash recovery**: SP auto-save + state reconstruction on relaunch; online ranked graceful disconnect with crash-vs-rage-quit attribution via crash reporter. - **Quick-resume** support per platform (Xbox Quick Resume, PS5 instant-resume, Switch2 sleep, PC sleep) with full session state preservation. - **Background download during play** with bandwidth throttling option. - **PC DRM** (Denuvo or equivalent) at launch with documented removal-plan window (6-12 months); console platform-native anti-piracy; cooked-asset integrity check at boot → safe-boot mode on tamper detection. ## Build, Cook, Patch - BuildGraph at `Build/Build.xml` for Win64, Linux (dedicated server), PS5, XSX, Switch2, Mac (dev only). - UnrealBuildAccelerator / Horde distributed builds with ≥ 75% cache hit-rate gate. - DDC sharing for editor performance. - CI workflows on every PR: editor compile, automation tests, Win64 cook. - Cook frame-budget gate fails CI on regression. - Chunked patch downloads; incremental patches per platform; manifest signing. - Day-one patch budget ≤ 5GB; subsequent patches ≤ 2GB typical. ## Data Architecture - Spreadsheet-of-truth at `V2/balance/data/` (Google Sheets export / CSV). - CSV ↔ DataTable round-trip importer in `V2Editor`. - Per-asset-type validators (move, fighter, moveset, finisher, style, ruleset, arena, entrance). - Drift tests: every `DA_Move` referenced from a `DA_Moveset` exists, every animation referenced exists, every hitbox sequence non-empty. - CSV export of all runtime move frame data to `V2/balance/exports//frame-data.csv`. ## Live-Service & DLC - Year-1 plan: 4 character DLC packs, 1 mode-expansion DLC, seasonal cosmetic drops. - Year-1 free updates: balance patches, new stages, new tower content, new tutorials, accessibility. - GameFeaturePlugin-based modular content delivery. - License-conditional content isolated to plugin for hot-swap removal. - Premium currency rules: transparent items, no real-money loot boxes, daily spend limits. ## Accessibility V2's accessibility surface is cert-critical (PSN / Microsoft / Nintendo each require certain a11y features to ship) and is architected as a first-class subsystem rather than an after-the-fact toggle pass. **Visual a11y** - **Colorblind palettes:** 4 palettes (Protanope, Deuteranope, Tritanope, Monochromacy). Applied via `UColorPaletteSubsystem`; widgets pull semantic color (e.g. `Color.Damage.Health`, `Color.Status.Burn`) not raw hex. - **High-contrast HUD:** 2 levels (Medium, High); HUD widgets carry a `HighContrastVariant` UMG override. - **HUD scale:** 75–150% in 5% steps; min-readable-size linter enforces 18 px @ 1080p minimum at any scale. - **Reduced motion:** every animated widget has a `Reduced` static variant; screen-shake, hitstop visual, camera-shake all have reduced variants; ranked-eligibility flag does **not** flip off when reduced-motion enabled (visual-only accommodation). - **Subtitles + closed captions:** per-locale, per-speaker, per-effect (e.g. "[gunshot]" caption tags). `@v2/iris-accessibility` uses `@iris/accessibility` for the accessibility bridge, while `@v2/psyche-caption-streaming` uses `@psyche/caption-streaming` for real-time match captions across HUD, spectator mode, replay transcripts, companion captions, and broadcast observer captions; in-engine subtitle system handles cinematic dialogue. **Motor a11y** - **Full input rebinding:** every action remappable on every input class (KBM / gamepad / fight-stick / fight-pad / adaptive controller). - **Assist macros:** auto-combo-trigger, motion-shortcut (DP → single button), parry-window-extend (+2 frames), block-assist (auto-block when stick neutral). Assist-macros flag **flips off ranked-eligibility** in the matchmaking ticket; assist-eligible queues match assist-vs-assist or assist-vs-pure-with-handicap. - **Hold-to-press toggles:** every "hold" input has a "toggle" alternative; config-driven. - **One-handed scheme:** preset rebinding for left-only and right-only play; ships with each platform's adaptive-controller integration. - **Adaptive controller integration:** Sony Access Controller (PS5), Microsoft Xbox Adaptive Controller (XSX), Logitech Adaptive Gaming Kit (PC), Quadstick (PC). Per-controller calibration UI from V2Peripherals. **Auditory a11y** - **Audio cues for visual events:** opt-in audio ping for low-HP, ringside rope position, finisher window, Drive Rush whiff — every gameplay state with critical visual cue has a corresponding audio cue. - **Mono / binaural toggle:** for hearing-impaired-in-one-ear players. - **Subtitle-only mode:** mutes voice / commentary but retains gameplay SFX. **Cognitive a11y** - **Tutorial assist:** input prompts persist after first practice (toggle); trial cap removed (some players need 50+ attempts). - **Tooltip everywhere:** every menu item carries a tooltip with text and optional voice-over. - **`@iris/accessibility` integration:** `@v2/iris-accessibility` binds dyslexia-friendly typography, cognitive-load reduction, screen-reader bridge, real-time companion-app assist, native UE accessibility hooks, and accessibility certification gates. It consumes `@v2/psyche-caption-streaming` over `@psyche/caption-streaming` as the caption provider while Iris owns the cross-client accessibility semantics. - **`@psyche/caption-streaming` integration:** `@v2/psyche-caption-streaming` owns the real-time match caption session plan for HUD, spectator mode, replay, companion, and broadcast surfaces. Captions are off rollback presentation state and expose no deterministic gameplay input. **Cert + certification targets** - **VPAT 2.5 (WCAG 2.1 AA)** for marketing site + companion app; certification target ≥ 90% WCAG 2.1 AA criteria pass before launch. - **AbleGamers** + **Can I Play That** community reviews scheduled in pre-launch beta. - **Sony / Microsoft / Nintendo accessibility certification:** each platform's required-a11y-feature list ships in launch build; cert blockers tracked per-platform at `V2/legal/a11y-cert-checklist.md`. - CI gate `Tools/check-a11y-coverage.py` asserts every focusable widget has an `AccessibilityDescription` and every animated widget has a `Reduced` variant. ## Security, Privacy, Compliance V2 security/privacy/compliance composes the existing Oshun shared packages (`@oshun/data-residency`, `@oshun/audit-platform`, `@oshun/trust-safety`) plus Themis governance, `@v2/aphrodite-age-gate` over `@aphrodite/age-verification`, and `@v2/aphrodite-consent-surfaces` over `@aphrodite/consent-engine`. This section pins the cert-blocking surface; the data-subject-rights request flow is detailed in arch§"Compliance & Data-Subject-Rights Architecture", and the privacy-by-design / DPIA / sub-processor governance process is detailed in arch§"Privacy-by-Design, DPIA & Sub-Processor Architecture". **Auth + identity** - **Account binding:** Oshun account is the root (`@oshun/identity`); per-platform shadow accounts bind via `@oshun/auth-client` and the V2 `@v2/oshun-identity-binding` surface. `FV2SaveHeader` stores `OshunAccountId` and `HomeRegionId` separately from `PlatformUserId` so cloud saves cannot merge across identities. - **MFA:** TOTP required for account-merge, payment-detail change, and ranked-pro-tier qualification. - **Session:** JWT short-lived (15 min) + refresh token (30 days); refresh rotates on every use; cross-region session sync via `@oshun/cache`. **PII handling** - **Strip at telemetry ingest:** `@oshun/audit-platform` pipeline applies a per-field PII allowlist; raw IP, raw device fingerprint, real-name fields never reach analytics warehouse. Per-region routing via `@oshun/data-residency`. - **Per-region storage:** EU player data routed to Frankfurt / Stockholm; JP to Tokyo; KR to Seoul; LATAM to São Paulo; CN to publisher-routed cloud; CCPA opt-out honored at ingest. - **DSR routing:** `@v2/themis-privacy-dsr-routing` composes `@themis/privacy` with `@oshun/data-residency`; Themis owns the access / erasure / portability / rectification workflow and data-residency owns the subject-home route. SLA per region remains GDPR 30 days, CCPA 45 days, LGPD 15 days. DSR machine-readable exports are JSON + CSV; deletion cascades to all bound shadow accounts. - **V2 audit publication:** Moderation, anti-cheat, and DSR surfaces publish canonical events through `@oshun/audit-platform`; V2 publishes and Oshun retains and exports the investigation-ready audit trail. - **Per-feature consent:** `@v2/aphrodite-consent-surfaces` replaces standalone V2 consent handling for telemetry, voice processing, and behavioral profiling. It uses `@aphrodite/consent-engine`, requires consent receipts when enabled, defaults missing opt-ins to privacy-preserving fallbacks, redacts disallowed data classes, and stays off rollback. **Rating boards + per-region content rules** - **Rating boards:** ESRB M, PEGI 18, CERO Z, USK 18, ACB R18+, GRAC, ClassInd 18, OFLC R18 — single rating cycle per platform per region. - **Per-region content rules** use shared `@oshun/region-rules` per `V2/docs/decisions/regional-content-rules-owner.md`: China removes blood + finishers + ghost / skeleton imagery; Germany clamps to mild gore and swaps red blood for green / black where applicable; Australia / NZ cook standard gore with finisher pre-clearance; Korea clamps to mild gore and softened finishers. Missing region data defaults to the China most-restrictive profile. - **Age gate:** `@v2/aphrodite-age-gate` replaces the standalone V2 age gate. It uses `@aphrodite/age-verification` as a backend-only driver for gore tier, adult fatalities, and region-conditional cinematics. The Aphrodite brand is not visible to players, and the gate stays off rollback. The primitive-fitness audit keeps the existing Aphrodite primitive but parameterizes it with the `mature-rated-fighting-game` profile, rejects the adult-content default profile, uses rating-board / region-rule thresholds, and excludes 2257, performer-protection, and anti-CSAM performer workflows from V2 game content gating. The adult-content default profile is rejected for V2. - **Per-region build cooks:** `Tools/cook-region.py` produces per-region cooked content with gore-tier overrides; rating-board manifest at `V2/legal/rating-boards.json` is the source of truth. - **2257 record-keeping:** if any CAW / CAF / NIL flow involves licensed performer likeness, `@themis/likeness` (forthcoming) holds the records; out-of-scope for CAW that is purely user-generated likeness. - **Licensed-fighter likeness safety:** `@v2/aphrodite-licensed-likeness-safety` composes `@aphrodite/performer-sovereignty` and `@aphrodite/performer-autonomy`. It consumes Themis `@themis/likeness` stamps by contract, listens for `themis.license.revoked`, and blocks the likeness surface plus Bellona cook for revoked, expired, terminated, mismatched, or withdrawn grants. **Cert constraints** - Every rating board requires a separate Manifest + cert submission; cert windows tracked at `V2/legal/cert-windows.md`. - China cert: pursued via publisher route only; the V2 build always passes `Tools/check-cn-content-rules.py` before publisher hand-off. - **EU AI Act:** every shipping AI service requires a Model Card + conformity assessment; `@v2/eu-ai-act-surface` validates the Director, AI commentary, anti-cheat classifier suite, and generation-pipeline registry against `@nous/safety` Model Cards and `@themis/accountability` AI-system-of-record exports. ## Observability, Evaluation, Release Gates - All Node packages under `apps/v2/` declare `@oshun/metrics` and `@oshun/tracing` as required from day one. The Unreal `V2Services` module exposes matching `FV2ServiceObservabilityBinding` records for `apps/v2/*` and `V2/ue/Source/V2Services`; the path is off rollback and cannot influence deterministic simulation. - Symbolicated crash reporter; in-the-loop fault injection in dev. - Per-platform perf dashboards. - Network-quality dashboard: matchmaking p99, rollback frame distribution, packet loss, rage-quit rate. - Anti-cheat false-positive rate dashboard. - Canary analysis automation for online services. - Release gates: regression suite + golden replays + frame-budget + crash rate + cert pass + RTC pass + canary pass. ## Performance Budgets | Target | Resolution | FPS | Notes | | ----------------------------- | ---------- | --- | ------------------- | | PS5 (standard) | 4K | 60 | RT off | | PS5 Pro | 4K | 60 | RT shadows on | | PS5 Pro (perf mode) | 1080p | 120 | | | Xbox Series X | 4K | 60 | | | Xbox Series S | 1440p | 60 | Reduced VFX density | | Switch2 (docked) | 1080p | 60 | Quality-band drop | | Switch2 (handheld) | 720p | 30 | Quality-band drop | | PC baseline (RTX 3060 / 4060) | 1440p | 60 | Medium settings | | Steam Deck | 800p | 60 | Verified | Per-frame: gameplay 4ms, anim 3ms, render 8ms, audio 1ms, network 0.5ms, GC ≤ 1ms incremental. Loading: cold-boot ≤ 30s on PS5; mid-session match load ≤ 8s. ## Testing, QA, Cert - UE Automation Spec coverage for GAS, motion parser, hitbox engine, rollback determinism, save round-trip, data-table integrity. - Gauntlet suites: launch + tutorial + arcade ladder + online-headless 1v1, on every PR. - Replay-based regression: 200 golden replays per build, frame-by-frame divergence detection. - Cert / TRC / XR / lotcheck on every shipping platform. - Anti-cheat compatibility cert per platform. - Trophy / achievement plans across modes. ## Content Pipeline & Source Control - Perforce primary; Git LFS mirror for OSS-style branches. - Per-asset-type checkout policy (umap exclusive, uasset mostly mergeable with text-format on, blueprint binary). - Build farm with cooked-content caches per platform; weekly hard refresh; nightly delta cook. - Asset audit report weekly (orphans, oversize, missing LODs, missing skin weights, redundant material variants). ## Per-Fighter Signature Library Architecture ```mermaid flowchart LR Checklist[Per-Fighter Checklist] --> Anim[Signature Animations] Checklist --> Audio[Signature Audio] Checklist --> VFX[Signature VFX] Checklist --> Stage[Signature Stage Reactions] Anim --> AnimBP[AnimBP Stance Layer] Anim --> ChooserHit[Hit-Reaction Chooser Tables] Audio --> Bank[Voice Bank] Audio --> Impact[Impact Sting Library] Audio --> Theme[Dynamic Music Stack] VFX --> Niagara[Niagara Templates] Stage --> Sequencer[Sequencer Presets] QA[QA Cert Pass] -- per-fighter audit --> Checklist Budget[Asset Budget] -- gates --> Checklist ``` Signature library is a per-fighter contract enforced by the checklist at `V2/balance/fighters//signature-checklist.md`, asset-budget-gated, and QA-cert-verified. ## Side-Story & Story-Theater Pipeline - **Side Story plugin** (`V2/ue/Plugins/V2Mode_SideStory/`) per fighter: Sequencer-driven cinematic + 3-5 scripted fights + branch logic. - **Story Theater** plugin (`V2/ue/Plugins/V2Mode_StoryTheater/`) indexes all unlocked cinematics across Story (§20) / Character Episodes / Side Stories / Arcade endings and presents a browse / replay UI with alt-language audio override + subtitle override + commentary track toggle. - **Branch tree visualizer** (`V2Mode_StoryTheater`) renders the Story branching graph; player can jump back to any branch point and retry. - **Ending Gallery** in Krypt hub indexes per-fighter Arcade endings. ## Match-Flow Mode Plugin Matrix (extension) This matrix covers the canonical match-flow variants (versus, time / score attack, wager, handicap, and so on). It is a deliberately separate table from the core-mode matrix in arch§"Game Modes" (Arcade, Story, careers, hubs): that table covers full single-player and online experiences, while this one covers the lightweight match-flow variants that wrap a standard fight. | Mode | Net | Save | Plugin | | ----------------------- | ------------------------ | ---------------------- | --------------------------- | | Local Versus (1P vs 2P) | Local | Match record | `V2Mode_LocalVersus` | | Versus CPU | Local | Match record | shares `V2Mode_LocalVersus` | | CPU vs CPU (attract) | Local | n/a | shares `V2Mode_LocalVersus` | | Time Attack | Local + leaderboard | Best-time per fighter | `V2Mode_TimeAttack` | | Score Attack | Local + leaderboard | Best-score per fighter | `V2Mode_ScoreAttack` | | Wager Match | Online ranked-ineligible | Wager ledger | `V2Mode_Wager` | | Friendly / Dare | Online friend-only | Match record | `V2Mode_Friendly` | | Handicap | Local or online | Match record | `V2Mode_Handicap` | | First Blood | Local or online | Match record | `V2Mode_FirstBlood` | | Boss Battle | Local | Per-boss progress | `V2Mode_Boss` | | Sparring | Local + online lab | n/a | shares `V2Mode_Training` | | Iron Man / Bo-N | Online | Set scorecard | `V2Mode_BestOfN` | | LAN | LAN UDP broadcast | Match record | `V2Mode_LAN` | ## Ranked Season Service ```mermaid flowchart TB Match[1v1 Match End] --> MMR[Hidden MMR Update Glicko2 / TrueSkill2] MMR --> RankMap[Visible Rank Tier Mapping] RankMap --> Hysteresis[Hysteresis Gate] Hysteresis --> Visible[Player Rank Display] Inactivity[14-day Inactivity] --> Decay[Rank Decay Above Master] Decay --> MMR Anomaly[Sandbagging Anomaly Detection] --> Penalty[Auto-Derank] Penalty --> MMR Region[Region Pool] --> CrossPlatform[Cross-Platform Unified Pool] CrossPlatform --> MMR Tournament[Tournament Result] --> Crown[Crown Ranking Overlay] Ranked[Ranked Result] --> Crown ``` **Service contract** - **gRPC service:** `libs/proto/v2/online/rank.proto` (cross-ref Online Services contract above). - **Key methods:** `Rank.RecordMatch(match_result) → mmr_delta`, `Rank.GetLeaderboard(mode, region, season, page) → ladder`, `Rank.GetSeasonState(account_id, mode) → season_state`, `Rank.GetCrownPoints(account_id, season) → points`. - **MMR model:** TrueSkill2 with per-mode μ/σ; visible rank tiers mapped via static `rank-tier-map.json`. Hysteresis: ±1 tier requires ≥ 5 matches in the boundary band. - **MMR delta cap:** ±32 points per match (prevents single-match swings). - **Placement matches:** 10 placement matches at season start before visible rank shown; hidden MMR seeded from prior season − 1.5σ decay. - **Rank decay:** Master tier and above decay 50 MMR / 14 days of inactivity; decay stops at Master-tier floor. - **Master tier threshold:** top 1% of TrueSkill2-projected pool per region per mode; recalculated weekly. - **Sandbagging detection:** ML classifier emits `v2.rank.sandbagging.detected` on confidence ≥ 0.95; manual review opens via `@themis/dispute-resolution`; confirmed sandbaggers auto-derank 200 MMR. - **Event-bus publishes:** `v2.rank.season.started`, `v2.rank.season.ended`, `v2.rank.tier.promoted`, `v2.rank.tier.demoted`, `v2.rank.sandbagging.detected`. - **Season authority:** `@v2/maat-live-service-calendar` consumes `@maat/strategy` as the source of truth for V2 seasons and Crown Points pool windows; ranked services expose the calendar but do not define it. - **SLOs:** rank record p99 ≤ 800 ms; leaderboard fetch p99 ≤ 400 ms; season-end snapshot completed within 24h of season close. - **Owner:** V2 ranked team. **Cost-tier:** standard backend; ceiling at `V2/docs/cost/ranked.md`. ## Companion App Architecture ```mermaid flowchart LR Mobile[apps/oshun/mobile/v2 V2 Companion] --> APIGW[Public API Gateway] APIGW --> Auth[Account Auth] APIGW --> Stats[Stats Service] APIGW --> History[Match History Service] APIGW --> Replay[Replay Stream Service] APIGW --> Push[Push Notification Service] Mobile -- second-screen --> LiveMatch[Live Match Bridge] LiveMatch --> Client[Game Client] Coach[Coach Mode] --> Mobile Webhooks[Tournament Webhooks] --> APIGW Discord[Discord Bot] --> APIGW ``` - **Companion app** runs at `apps/oshun/mobile/v2/` inside the shared Oshun Expo shell and consumes `@oshun/shell-core`, `@oshun/auth-client`, `@oshun/concordia-integration`, `@oshun/trust-safety`, `@iris/agents`, and `@sophia/client`. It consumes the same Public API as third-party tools; account-public-flag gates which stats are visible. - **Second-screen mode** during a live match: companion app receives low-bandwidth stream of opponent move list + frame data; no gameplay effect; cosmetic-only. - **Push notifications** routed via APNS / FCM with per-category opt-out. - **Modding policy** (PC) and **Steam Workshop integration** documented at `apps/v2/web/dev-portal/`. **Service contract** - **Public API:** handlers at `apps/oshun/web/api/v2/`, Next route adapters at `apps/oshun/web/src/app/api/v2/`, and OpenAPI 3.1 spec at `libs/openapi/v2/companion.yaml` registered by `@oshun/openapi`. The runtime document is served at `GET /api/v2/openapi`; generated client SDK remains owned by `@oshun/developer-portal`. - **Knowledge pages:** frame-data wiki, combat glossary, and roadmap routes now live at `/v2/wiki`, `/v2/glossary`, and `/v2/roadmap` inside `apps/oshun/web`. They are backed by `@sophia/client` RAG response contracts and render citations from the frame-data schema, public API, companion, and architecture corpus. - **Auth:** OAuth 2.1 with PKCE; third-party apps register via developer portal, get per-app scopes; rate-limit per-app via `@oshun/cache`. - **Key endpoints:** - `GET /v2/player/{id}/stats` — public stats (per-account-public-flag). - `GET /v2/player/{id}/history?limit=N` — match history. - `GET /v2/replay/{id}` — replay stream (auth required for non-public). - `POST /v2/match/{id}/coach-stream` — second-screen low-bandwidth stream. - `POST /v2/notification/subscribe` — push subscription. - **Event-bus subscribes (for push routing):** `v2.match.ended`, `v2.party.invite.created`, `v2.tournament.round.advancing`, `v2.daily-challenge.completed`, `v2.battle-pass.tier.unlocked`. - **SLOs:** API p99 ≤ 400 ms; push delivery p99 ≤ 5 s end-to-end; second-screen stream ≤ 200 ms p99 from match event to companion render. - **Rate limits:** 100 req/min per third-party app (unauthenticated baseline); 1000 req/min per registered app; per-account 30 req/min on personal data. - **Owner:** V2 platform team. **Cost-tier:** ceiling at `V2/docs/cost/companion.md`; APNS / FCM at vendor standard tier. ## Production Pipeline - **Mocap pipeline**: Vicon / OptiTrack recording hardware → `@aja/motion-pipeline-sdk` cleanup / contact-root repair → `@aja/neural-retargeting` V2-skeleton retarget → Bellona/UE import → curve / keyframe edit → Sequencer / AnimBP import. Stunt double + safety + insurance handled at production layer. Every studio capture first passes `@v2/aja-consent-nil-ledger`, which requires active `@aja/consent-management` consent and a Themis `@themis/likeness` NIL link before Aja ingest; revocation blocks future Aja processing and Bellona cook for dependent clips. - **Licensed likeness safety pipeline**: `@v2/aphrodite-licensed-likeness-safety` runs before likeness surfaces, creator-suite publishing, replay export, and Bellona cook. `@aphrodite/performer-sovereignty` validates approved uses while `@aphrodite/performer-autonomy` emits the revocation flow that notifies Themis, Kuanyin, and Aja. - **VO pipeline**: per-locale recording → editing → loudness normalization → Opus encode → per-fighter bank version. - **Music pipeline**: composition → license clearance → master + variant authoring → MetaSounds graph build → in-game audio modulation. - **IP / NIL / Likeness layer**: per-asset rights metadata stored in `V2/legal/rights-manifest.json`; build pipeline verifies every shipping asset has cleared rights or is original-IP. - **Pre-production milestone gates**: Greenlight → Alpha → Beta → Gold master; each gate has documented exit criteria stored at `V2/docs/production/milestones/`. ## Compliance & Data-Subject-Rights Architecture ```mermaid flowchart LR Player[Player] --> DSRForm[In-Game DSR Form] DSRForm --> Auth[Account 2FA] Auth --> ThemisPrivacy[@themis/privacy · DSR workflow] ThemisPrivacy --> DataResidency[@oshun/data-residency · subject-home route] DataResidency --> V2Dsr[@v2/themis-privacy-dsr-routing] V2Dsr --> Access[Access · download JSON export] V2Dsr --> Erasure[Erasure · delete + anonymize aggregates] V2Dsr --> Port[Portability · standard JSON export] V2Dsr --> Rect[Rectification · edit profile data] V2Dsr --> AuditPlatform[@oshun/audit-platform · DSR audit] AuditPlatform --> AuditLog[Retained + exportable audit log] Mod[Moderation Action] --> SoR[Statement of Reasons API · DSA] Mod --> AuditPlatform FairPlay[Anti-cheat Review] --> AuditPlatform SoR --> Appeal[Appeal Flow] Trusted[Trusted Flagger] --> ModQueue[Priority Moderation Queue] EU[EU Player Data] --> EUDC[EU Data Center · Frankfurt / Stockholm] JP[JP Player Data] --> JPDC[Tokyo] KR[KR Player Data] --> KRDC[Seoul] LATAM[LATAM Player Data] --> SPDC[São Paulo] CN[CN Player Data] --> CNCloud[China Publisher Cloud · Tencent / Alibaba] ``` - **Per-region data residency** enforced by `@oshun/data-residency` route decisions and API gateway routing rules. - **DSR SLA**: 30d EU / 45d CCPA with one-time extension option. - **DSR workflow ownership**: access / erasure / portability / rectification are owned by `@themis/privacy` and exposed to V2 through `@v2/themis-privacy-dsr-routing`; V2 does not ship a local DSR ops console. - **Audit-platform ownership**: moderation decisions, anti-cheat review events, and DSR workflow routes are published through `@oshun/audit-platform`. V2 publishes; Oshun retains and exports the retained compliance, audit, and privacy investigation records. - **Erasure preserves anonymized aggregates** per GDPR Recital 26. - **Portability format**: standardized JSON with profile / matches / telemetry / cosmetics / friends / replays. - **Statement of Reasons API** publishes machine-readable moderation reasons per DSA Article 17; appealable. - **Themis dispute adapter** is `@v2/themis-dispute-resolution` over `@themis/dispute-resolution`: moderation appeals route to mediator + safety queues, and tournament-result disputes route to auditor-backed Themis challenge review. The adapter is off rollback. - **Semi-annual transparency report** ingested from moderation pipeline. ## Esports Backend Architecture ```mermaid flowchart TB Event[Tournament Event] --> TOTools[TO Badge Tools] TOTools --> RuleFile[Tournament Rule File · per-event JSON] RuleFile --> ClientLock[Client Tournament Edition Lock] Event --> Bracket[Bracket Service · Smash.gg / Start.gg / Challonge / Battlefy] Bracket --> ResultIngest[Result Ingest] ResultIngest --> CrownPoints[Crown Points Pool] CrownPoints --> WorldFinal[World Final Qualification] Stream[Broadcast Stream] --> Uzume[Uzume Broadcast Pipeline · @uzume/broadcast] Uzume --> Overlay[Caster Overlay · graphics / replay / multiviewer] Stream --> Twitch[Twitch Extensions · Polls / Drops / Cosmetic Wager] Spec[Spectators] --> EmoteSystem[Spectator Emote System] Spec --> IrisTranslation[Iris Real-Time Translation · @iris/voice] IrisTranslation --> Overlay EmoteSystem --> HypeMeter[Hype Meter Service] HypeMeter --> Overlay Archive[Tournament Archive] --> ArchiveDB[(Searchable Archive DB)] ``` - **Per-event Tournament Edition snapshot** stamped in replay header for audit; rule file uploaded via TO badge. - **Crown points** aggregated from the `@maat/strategy` Pro Circuit calendar + cross-region series through `@v2/maat-live-service-calendar`. - **Wildcard / Roulette / Mystery modes** are client-side variants gated by ruleset toggle; results-eligible per tournament rule file. - **Esports Operations team** runs live-event on-call. **Service contract** - **gRPC service:** `libs/proto/v2/esports/esports.proto`. - **Bracket integration:** outbound webhooks to Smash.gg / Start.gg / Challonge / Battlefy via `@oshun/inbound-integrations`; **V2 pulls** results (server-authoritative) rather than accepting client-pushed results — every match's result is cryptographically verified against the replay hash before it counts for Crown Points. - **Key methods:** `Esports.RegisterEvent(rule_file) → event_id`, `Esports.SubmitResult(event_id, match_result, replay_hash) → ack`, `Esports.GetBracket(event_id) → bracket`, `Esports.QualifyForFinals(season_id, region) → qualified[]`. - **Crown Points formula:** `points = base_points[round] × region_factor × participant_factor × season_decay`; full formula at `V2/docs/esports/crown-points-formula.md`. Base points per round (Round-32 = 50, Round-16 = 100, QF = 200, SF = 400, GF = 800). - **Event-bus publishes:** `v2.tournament.event.started`, `v2.tournament.round.advancing`, `v2.tournament.event.completed`, `v2.crown-points.granted`. - **Broadcast pipeline:** `apps/v2/esports-tools/` ships `@v2/esports-tools`, which composes `@uzume/broadcast` for switching, graphics, multiviewer, replay, SRT contribution feeds, stream health, and stream destinations. Standalone OBS / NDI / vMix glue is not primary; OBS WebSocket is retained only for streamer-mode notification suppression. - **Arena LED + projection:** the same `@v2/esports-tools` package composes `@uzume/lumina` and `@uzume/prism` for live tournament LED wall layout, lighting pixel maps, projector mapping, structured-light alignment, arena video routes, and show-cue events. It is presentation/show-control state only and exposes `mayInfluenceRollback: false`. - **Veritas fact-checking:** `@v2/esports-tools` composes `@veritas/fact-checking` for post-match reporting, bracket result verification, and esports news publication readiness. Replay, bracket, report, and news claims are scored with explicit evidence and consensus; winner-record conflicts hold publication without changing match authority. - **Iris real-time translation:** `@v2/iris-realtime-translation` composes `@iris/voice` for spectator chat translation, commentary subtitle localization, broadcast overlays, and companion second-screen feeds. The bridge registers locale receivers per surface and remains presentation-only with `mayInfluenceRollback: false`. - **Twitch Extensions rate-limit:** 100 polls / extension / minute; per-extension auth via Twitch JWT. - **SLOs:** result ingest p99 ≤ 5 s from submit to bracket update; live bracket fetch p99 ≤ 200 ms; broadcast overlay update p99 ≤ 100 ms. - **Owner:** V2 esports ops team. **Cost-tier:** ceiling at `V2/docs/cost/esports.md`; commentary AI cost folds into deps§67. ## Live-Service Calendar Service - **Calendar authority** is `@v2/maat-live-service-calendar` over `@maat/strategy`; there is no standalone V2 live-calendar schema. Maat owns seasons, Crown Points, Pro Circuit calendar events, anniversary events, charity events, console tie-ins, community-voted events, and balance ramp windows. - **Per-region calendar override**: themes that conflict with cultural context auto-hidden via `RegionVariant` data asset. - **Player-facing calendar widget** + 6-month forward view + opt-in digest email. - **Re-engagement service**: 60d-inactivity trigger → returning-player reward grant + lapsed-player email; bandwidth-throttled (no spam). **Service contract** - **gRPC service:** `libs/proto/v2/live/calendar.proto`. - **Key methods:** `Calendar.ListEvents(region, range) → events[]`, `Calendar.GetEvent(event_id) → event`, `Calendar.SubscribeReminder(event_id, channels) → ack`. - **Event-bus publishes:** `v2.calendar.event.starting`, `v2.calendar.event.ended`, `v2.calendar.reminder.dispatched`. - **Re-engagement throttle:** ≤ 1 reactivation email / lapsed-player / 30 days; push notification rate-limit ≤ 1 / day / category. Player can opt out per channel. - **SLOs:** calendar fetch p99 ≤ 250 ms; event notification dispatch p99 ≤ 60 s from event-start; reactivation email delivery p99 ≤ 10 min. - **Owner:** V2 live-ops team. **Cost-tier:** standard email / push; ceiling at `V2/docs/cost/live-calendar.md`. ## Progression & Codex Service - **Per-fighter XP / Mastery** computed server-side from match-record + Trial / Mission / Tournament completion events; mirrored to client for HUD display. - **Account level + Prestige** loop maintained on the persistence layer (arch§"Persistence & Profile" + arch§"Cross-Play & Cross-Progression"); transparent per-level rewards table at `V2/balance/progression/account-rewards.csv`. - **Codex / Encyclopedia** content at `V2/balance/codex/` (CSV / Markdown ↔ DataTable round-trip per arch§"Data Architecture"); per-entry unlock-condition data table; per-entry replay-link target into Story / Side Story / cinematic Vault. - **Unified Quest Log** aggregator (`V2Mode_QuestLog` plugin) ingesting from every mode's quest source. - **Reward Inbox** queue persisted per account; auto-claim toggle enforces low-value-only. **Service contract** - **gRPC service:** `libs/proto/v2/progression/progression.proto`. - **Key methods:** `Progression.GetAccountState(account_id) → state`, `Progression.RecordEvent(account_id, event) → rewards[]`, `Codex.ListEntries(filter) → entries[]`, `Codex.UnlockEntry(account_id, entry_id) → ack`, `QuestLog.GetActive(account_id) → quests[]`, `RewardInbox.Pop(account_id) → reward_or_empty`, `RewardInbox.ConfirmClaim(account_id, reward_id) → ack`. - **Event-bus publishes:** `v2.progression.level.up`, `v2.progression.mastery.advanced`, `v2.codex.entry.unlocked`, `v2.reward.granted`. - **Event-bus subscribes:** `v2.match.ended`, `v2.trial.completed`, `v2.mission.completed`, `v2.tournament.event.completed`. - **SLOs:** state fetch p99 ≤ 300 ms; event-driven reward grant p99 ≤ 3 s end-to-end (event → reward in inbox). - **Owner:** V2 progression team. **Cost-tier:** standard backend; ceiling at `V2/docs/cost/progression.md`. ## Community & Support Backend ```mermaid flowchart LR Player[Player] --> Support[Support Portal Web/In-Game] Support --> Ticket[Ticket Service] Ticket --> SLA[Priority-Tier SLA Router] Player --> Feedback[Feedback Widget] Feedback --> FeedbackDB[Feedback DB] FeedbackDB --> Canny[Canny Feature Voting] Ambassador[Community Ambassador] --> ModConsole[Moderation Console] Ambassador --> CommunityChan[Community Channels] HallOfFame[Hall of Fame Service] --> Inductees[(Inductees DB)] Inductees --> Museum[In-Engine Museum Hub] Coach[Certified Coach] --> CoachRoute[Coach-Mode Routing] News[Devs-to-Players Announcement] --> Localize[24h Loc SLA] Localize --> InGameBanner[In-Game Banner] Localize --> NewsletterEmail[Newsletter Email] ``` **Service contract** - **gRPC + REST services:** `libs/proto/v2/community/*.proto`; Zendesk webhook integration via `@oshun/inbound-integrations`. - **Key methods:** - `Support.OpenTicket(account_id, payload) → ticket_id`, `Support.GetTicket(ticket_id) → ticket`, `Support.PostMessage(ticket_id, message) → ack`. - `Feedback.Submit(account_id, feedback) → ack`, `Feedback.Vote(feature_id, vote) → ack`. - `Ambassador.GrantRole(account_id, role) → ack`, `Ambassador.RevokeRole(account_id, role) → ack`. - `HallOfFame.Induct(account_id, citation) → induction_id`. - `Coach.RegisterCertification(account_id, certification) → ack`, `Coach.GetRoster(filter) → coaches[]`. - **SLA tiers (Priority-Tier SLA Router):** - P0 (account compromise, payment dispute, harassment-in-progress): first response ≤ 1 hour, resolution ≤ 24h. - P1 (cheat report, ban appeal, payment failed): first response ≤ 8 hours, resolution ≤ 72h. - P2 (cosmetic loss, friend-list bug, UI bug): first response ≤ 48 hours, resolution ≤ 14 days. - P3 (feature request, general feedback): first response ≤ 7 days, resolution N/A. - **Event-bus publishes:** `v2.support.ticket.opened`, `v2.support.ticket.resolved`, `v2.feedback.submitted`, `v2.ambassador.role.granted`. - **News localization SLA:** 24h from English authoring to all 18 launch locales (subtitle level); 7d for full VO patch updates. - **SLOs:** ticket open p99 ≤ 1 s; feedback submit fire-and-forget; ambassador console p99 ≤ 500 ms. - **Owner:** V2 community ops team. **Cost-tier:** Zendesk subscription + Canny + email vendor; ceiling at `V2/docs/cost/community.md`. ## Per-Platform Store & PPP Pricing V2's store integration is **per-platform-store-native**: each platform store has its own consumable / entitlement / refund / family-share semantics, and the V2 client surfaces those through a thin `IPlatformStore` adapter. **Non-store flows** (coaching marketplace, donations, esports prize pools, companion-app subscription) flow through Stripe / Adyen per deps§"Payment processing". **Per-platform store integration** - **Steam (Steamworks SDK):** consumable IAP via Steam Inventory; entitlement manifests via Steamworks Web API; Steam Workshop for community cosmetics; Steam Family Library Sharing honored; refund window 14 days / 2h play (per Steam policy); `OnlineSubsystemSteam` adapter. - **PSN:** consumable / non-consumable IAP via PSN Commerce; PSN trophies + PS Plus integration; PS Plus Premium tier may include V2 in catalog; family-share honored; refund per Sony policy; `OnlineSubsystemPSN` adapter. - **Microsoft Store (XSX + PC):** IAP via Microsoft Commerce; Xbox achievements + Smart Delivery between XSX and PC; Game Pass tier may include V2; family-share via Microsoft Family; refund per MS policy; `OnlineSubsystemMS` adapter. - **Nintendo eShop (Switch 2):** IAP via Nintendo eShop; Nintendo Switch Online integration; cloud save; family-share via Nintendo Family; refund per Nintendo policy (digital purchases generally non-refundable); `OnlineSubsystemNintendo` adapter. - **Epic Games Store:** IAP via EOS Ecom; achievements via EOS Achievements; EGS overlay; `OnlineSubsystemEOS` adapter (also doubles as cross-platform auth/lobby backbone). - **iOS / Android (companion app only — no IAP grants game items):** App Store / Play Store IAP for companion-app subscription only; non-item flows. **PPP pricing surface** - **PPP table:** `@maat/finance` publishes the V2 regional pricing policy used by `@v2/maat-finance-ledger` and mirrored in `FV2MaatFinanceLedgerPolicy`. Source data is regenerated quarterly from IMF + World Bank per-capita PPP data and signed via `@oshun/config` so clients consume the latest table without an app patch. - **Per-region price tiers:** baseline price × per-region PPP ratio rounded to the nearest platform-store-allowed tier (Steam has discrete tiers per region; Sony / MS / Nintendo similar). Per-region price ceiling capped at baseline; floor at ratio × 0.4 to prevent inversion attacks. - **Local-currency display:** client surface shows local-currency price + baseline-currency equivalent + reverse-look-up to regional purchase-power ratio (transparency). - **Per-region price-change cadence:** ratio refresh quarterly; no in-month changes (players can plan purchases against a stable price for ≥ 30 days). - **Offline ledger cache:** `V2Persistence` can apply a Maat-approved offline cache entry when online authority is unavailable; the entry carries a Maat decision id and reconciles on next online sync before cloud save promotion. - **Responsible-play spend insight:** `@v2/lakshmi-responsible-play-spend-insight` composes `@lakshmi/behavioral`, `@lakshmi/budgeting`, and `@lakshmi/transactions` for opt-in nudges, parental controls, self-imposed caps, and weekly summary reflection. This surface is off rollback and can only affect store confirmation or guardian approval, never match simulation. **VPN-region-shop detection** - **Detection signal:** `account_region` (set at first purchase + verified at age-gate) vs `session_region` (geo-IP per-session) vs `payment_region` (per-IAP). Disagreement on more than one of the three for ≥ 90 days triggers a soft block on purchase. - **Action on detection:** prompt user to either confirm permanent region change (re-verify age, accept new region's content rules + ratings) or cancel purchase; never silently apply different region rules to the same account. - **Whitelist:** known business traveller patterns (consistent home region with brief secondary-region windows) do not trigger the block. - **Honest disclosure:** the V2 privacy notice discloses VPN detection as a fraud-prevention measure, not as a punitive cross-region price-arbitrage block (the latter would invite consumer-protection scrutiny in EU / UK). **Cert constraints** - Each platform store must be the **exclusive** path for items that grant in-game gameplay state on that platform — coaching / donation / subscription are non-item flows and explicitly allowed under TRC. - CI gate `Tools/check-payment-cert.py` asserts no Stripe / Adyen call path can ever grant a gameplay item or cosmetic on console. - Steam DRM, Sony anti-tamper, Microsoft anti-tamper, Nintendo lotcheck signing all required at submission. ## Balance Ops Service - **Public frame data tool** starts as shell-native Sophia knowledge pages at `/v2/wiki`, `/v2/glossary`, and `/v2/roadmap`, consuming the same cited frame-data corpus that drives runtime data tables (cross-ref arch§"Data Architecture"). Raw CSV download and patch diff views remain owned by `V2FrameDataPublisher`. - **Auto-matchup-chart generator** in `apps/v2/balance/` ingests match-result events from telemetry → produces per-fighter / per-rank matchup percentage. - **ML balance recommender** at `apps/v2/ml-balance/` proposes buff/nerf candidates with confidence + telemetry justification; designer-reviewed; never auto-applied. - **A/B framework** integrated with PTB branch (cross-ref §52.8); per-A/B outcome published post-patch. **Service contract** - **gRPC service:** `libs/proto/v2/balance/balance.proto` + `ml-balance.proto`. - **Key methods:** `Balance.GetMatchupChart(fighter_id, rank_tier) → chart`, `Balance.GetFrameData(fighter_id, move_id) → frame_data`, `MLBalance.GetRecommendations(window, scope) → recommendations[]`, `Balance.PublishPatch(version, changes) → ack`. - **Event-bus publishes:** `v2.balance.dataset.published`, `v2.balance.recommendation.generated`, `v2.balance.patch.shipped`. - **Event-bus subscribes:** `v2.match.ended` (telemetry feed), `maat.balance.dashboard.surface` (`@v2/maat-balance-dashboard` over `@maat/intelligence` + `@maat/dashboard` + `@maat/reporting`), `sophia.framedata.published` (Sophia citation feed sourced from the `@v2/sophia-release-candidate-ingestion` release-candidate cook hook). - **ML threshold:** balance recommendation surfaces only when ≥ 5,000-match sample at the target rank tier, win-rate Δ ≥ 5 pp, matchup confidence ≥ 0.95. A/B duration default 14 days (PTB) before promotion. - **SLOs:** matchup-chart fetch p99 ≤ 600 ms; recommendation generation weekly cadence (Monday 04:00 UTC). - **Owner:** V2 balance team + Maat team. **Cost-tier:** Maat balance dashboard pipeline budget at `V2/docs/cost/balance.md`; there is no standalone V2 balance dashboard. ## Engineering Polish Pipeline - **PSO pre-cache** built into cooked content per platform; runtime PSO cache validation at boot. - **Shader pre-warm** at first-launch + per-cosmetic-pack load via dedicated worker thread. - **Asset pre-load** scheduled by `V2Persistence` load handler based on per-account session-pattern segment (§55.6). - **Adaptive tickrate** server-side switch in `V2Netcode` dedicated-server target; rollback paths exempt. - **Per-session telemetry sampling** randomized in `V2Telemetry` ingest layer; crash + cheat events always 100% sampled by event-class override. ## AI Director Service ```mermaid flowchart LR SessionSignals[Session Signals · WinRate / Length / Frustration / Stomp] --> Director[AI Director State Machine] Director -- Calm --> Light[Light CPU Difficulty] Director -- Build --> Med[Medium Difficulty + Slow Climb] Director -- Climax --> Cinematic[Cinematic Max-Challenge + Hype Audio] Director -- Recovery --> Eased[Eased Difficulty] Director --> PerModeTuning[Per-Mode Director Profile] PerModeTuning --> ArcadeProfile[Arcade] PerModeTuning --> TowerProfile[Tower of Time] PerModeTuning --> TForceProfile[Tekken Force] PerModeTuning --> StoryProfile[Story] PlayerProfile[Per-Player Tendency Profile] --> AdaptiveAI[Adaptive AI] CombatTelemetry[V2 Combat Telemetry] --> ShaktiStyle[Shakti Style Classification] ShaktiStyle --> StyleMatchups[Style Matchup Hints] StyleMatchups --> Director Director -. opt-out toggle .- Player[Player Settings] Director -. EU AI Act conformity .- Compliance[EU AI Act Conformity] ``` - **Director never active in ranked / tournament** — static rule-of-the-day only. - **Per-player tendency profile** stored alongside the save game (arch§"Persistence & Profile"); never shared cross-account. - **EU AI Act conformity** documented; per-player profile DSR honored. **Service contract** - **gRPC service:** `libs/proto/v2/director/ai-director.proto`. - **Key methods:** `Director.GetSessionState(player_id, mode) → state`, `Director.RecordMatchSignal(player_id, signals) → ack`, `Director.ApplyProfile(player_id, mode, profile) → ack`. - **Rollback-safety binding (corrected per arch§"Sister-Monorepo Integration Surface"):** offline / training consumes live Psyche tendency hints freely through `@v2/psyche-ai-director-hints` and `V2AdaptiveAI`; online rollback-with-CPU defense-in-depth matches sample `@psyche/behavior-prediction` at match load, bake `tendency-vector + seed` into the deterministic match-start input stream, and run rollback-deterministic AI from then on. Live mid-match updates queue and apply at the next match-start. **Never** call Psyche or Director gRPC inside the rollback envelope. - **Tunable parameters** (per-mode, in `apps/v2/ai-director/profiles/`): `epsilon ∈ [0.05, 0.30]` (difficulty drift step), session-signal weights (win-rate / length / frustration / stomp; sum-to-1 vector), recovery-easing rate. - **Event-bus publishes:** `v2.director.profile.applied`, `v2.director.signal.recorded`. - **Event-bus subscribes:** `psyche.behavior.prediction`, `v2.match.ended`. - **Unreal bridge:** `V2AdaptiveAI` validates that live `@psyche/behavior-prediction` hints are non-rollback-only and that any rollback-with-CPU hint is serialized into `FV2AdaptiveAIMatchStartInputVector` before `V2Netcode` starts simulating. - **Shakti style matchup binding:** `@shakti/sota-critical` classifies per-player combat style as `boxer`, `kickboxer`, `striker`, `grappler`, or `submission-specialist`. `@v2/shakti-style-classification` converts the off-rollback `shakti.player.style.updated` output into AI Director matchup hints and `V2AdaptiveAI` validates the `FV2AdaptiveAIShaktiStyleClassification` / `FV2AdaptiveAIStyleMatchupHint` contract. Rollback frames cannot call Shakti; rollback-with-CPU consumers use match-start or next-match snapshots only. - **EU AI Act:** Director is **Limited risk**. `@psyche/action-safety` provides classifier transparency and opt-out, `@v2/eu-ai-act-surface` binds the V2 adapter, `@nous/safety` hosts `V2/docs/ai/model-cards/adaptive-ai-director.md`, and `@themis/accountability` owns the AI-system-of-record and conformity export. User-visible opt-out in Settings switches the player to the static CPU profile before classifier use; profile data remains per-account and DSR delete cascades to Director profile + Psyche tendency vector + Shakti style classification. - **SLOs:** profile fetch p99 ≤ 100 ms (off-rollback); signal recording fire-and-forget. - **Owner:** V2 AI team + Psyche team. **Cost-tier:** Psyche inference budget at `V2/docs/cost/ai-director.md`. ## Local Multiplayer & Co-op Architecture ```mermaid flowchart LR Local[Local Input Streams] --> Multiplayer[Split-Screen Renderer] Multiplayer --> RenderBudget[Per-View Render Budget] Coop[Co-op Online] --> SessionHost[Session Host Migration ≤ 30s grace] Coop --> LootShare[Per-Player Loot Share] Crew[3v3 / 4v4 Crew Co-op] --> TeamHP[Shared Team HP] PartyMM[Party Matchmaking 2-4] --> MMRBalance[MMR-Balanced Pairing] Ghost[Ghost Co-op] --> GhostStore[Ghost Data Store] ``` - **Split-screen** preserves 60fps target with per-view render budget; per-side accessibility independence. - **Co-op online** for Story / Tekken Force / Devil Within / Konquest: client-server net (cross-ref arch§"Client-Server Netcode") with session host migration on host disconnect. - **Crew co-op** (3v3 / 4v4) uses tag-team rollback for the 1v1 portions and client-server for crew-rotation moments. ## Signature Event Mode Plugins Mode plugins for §93 signature events ship as `UGameFeaturePlugin`: - `V2Event_Marathon` — 24-hour charity-aligned event - `V2Event_KingOfIronFist` — 8-fighter elimination ladder - `V2Event_WrestleMania` — WWE PPV-style 8-match card - `V2Event_FightWeek` — UFC International Fight Week - `V2Event_MishimaCup` — SoulCalibur 16-fighter Weapon Master tournament - `V2Event_EVO_Top8` — EVO-style Top 8 broadcast event - `V2Event_CrewWars` — Def Jam 4v4 crew elimination - `V2Event_Horde` — Boss-vs-crew asymmetric mode - `V2Event_SpeedrunRace` — 2-4 player Arcade race - `V2Event_DeathMatch` — single-round sudden death stipulation ## Privacy-by-Design, DPIA & Sub-Processor Architecture This section covers the proactive privacy-engineering process — privacy-by-design review, Data Protection Impact Assessments, and the sub-processor registry. It is the companion to arch§"Compliance & Data-Subject-Rights Architecture", which covers the reactive data-subject-rights request flow. ```mermaid flowchart LR Feature[New Feature] --> PrivacyByDesign[Privacy-by-Design Review] PrivacyByDesign --> DPIA[Data Protection Impact Assessment] DPIA --> ReleaseGate[Release Gate] ReleaseGate --> Ship[Ship] SubProcessor[New Sub-Processor] --> Notice[30-Day Notice] Notice --> Registry[Public Sub-Processor Registry] Privacy[Quarterly Privacy Review] --> DPO[Data Protection Officer] DPO --> AuditReport[Sanitized Public Summary] DSR[Access / Erasure / Portability / Rectification] --> ThemisDSR[@themis/privacy] ThemisDSR --> ResidencyDSR[@oshun/data-residency] ResidencyDSR --> DSRQueue[themis.privacy.dsr.] DSRQueue --> AuditPlatformDSR[@oshun/audit-platform] AuditPlatformDSR --> AuditTrail[DSR Audit Trail · retained + exportable] ``` - **Privacy-by-design** + **DPIA** required on every feature touching identifiable / sensitive data. - **Sub-processor registry** at `V2/legal/sub-processors.md` + public view at `apps/v2/web/legal/sub-processors`. - **Per-region compliance variants** (cross-ref §54.2 + §80 + §94): AB 2273 / Bill 96 / Bill 25 / LGPD / Italy / Belgium / France surfacings via `RegionVariant` data asset. ## Racing Component Architecture V2 ships a full racing component as a peer genre to fighting. Architecture extends existing systems: ### Racing Module Split These modules extend the module set in arch§"Module Split". | Module | Responsibility | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **V2Racing** | Race-mode registry, race-state machine, racing HUD injection, race rules / scoring / officiating | | **V2Vehicles** | Vehicle data assets (`DA_Vehicle`, `DA_VehicleTune`, `DA_VehicleCustomization`, `DA_VehicleDamage`), per-chassis archetype components, drive-train logic, engine + RPM model, tire model | | **V2RacePhysics** | Racing-specific physics (arcade-sim spectrum), off-road suspension, anti-grav hover, bike lean, hover-magnet attraction | | **V2RaceTracks** | Track / circuit / open-world racing-zone data, racing-line authoring, AI racing-line, sector splits, replay-deterministic pose recording | | **V2RaceModes** | GameInstance registry of race-mode plugins (Circuit / Sprint / Drag / Drift / Time Trial / Eliminator / Pursuit / Combat / Power-Play / Canyon Duel / Rally / Bike / Pod Racer) | | **V2VehicleAudio** | Engine notes (per-RPM bin), exhaust, turbo, tire screech, transmission whine, Doppler shifting, environmental ambience | | **V2VehicleVFX** | Tire smoke, sparks, debris, motion blur, speed lines, anti-grav engine glow, jump dust, mud splash | ### Racing Mode GameFeaturePlugins ```mermaid flowchart TB Racing[V2 Racing Hub] --> Career[V2RaceMode_Career] Racing --> Circuit[V2RaceMode_Circuit] Racing --> Sprint[V2RaceMode_Sprint] Racing --> Drag[V2RaceMode_Drag] Racing --> Drift[V2RaceMode_Drift] Racing --> TimeTrial[V2RaceMode_TimeTrial] Racing --> Eliminator[V2RaceMode_Eliminator] Racing --> SpeedTrap[V2RaceMode_SpeedTrap] Racing --> Pursuit[V2RaceMode_Pursuit] Racing --> Combat[V2RaceMode_Combat] Racing --> PowerPlay[V2RaceMode_PowerPlay] Racing --> CanyonDuel[V2RaceMode_CanyonDuel] Racing --> Rally[V2RaceMode_Rally] Racing --> Bike[V2RaceMode_Bike] Racing --> PodRacer[V2RaceMode_PodRacer] Racing --> OpenWorld[V2RaceMode_OpenWorld] Racing --> Crossover[V2RaceMode_FighterCrossover] ``` ### Vehicle Physics Pipeline - **Determinism boundary for racing.** Racing modes ship on **client-server with input prediction**, not on the rollback envelope from arch§"Rollback Netcode". Continuous-physics solvers (hovercraft, bike-lean, drift) under cross-platform float modes are not bit-identical-deterministic across vendors. The Chaos vehicle solver runs **server-authoritative** and replicates to all clients; client-side prediction smooths the local pose only, never resimulates physics. The "bit-identical" promise applied to combat (arch§"Combat Authority & Determinism") does **not** apply to vehicle physics; the corresponding promise here is "**server-consistent outcomes** across all clients within one frame of replication latency." - **Per-vehicle physics LOD** is server-authoritative: the server runs the full physics solver for all vehicles regardless of client camera; clients receive full pose for vehicles inside camera frustum and interpolated pose for distant vehicles. Client physics LOD therefore never affects sync — it affects only local visual quality. There is no client-resimulated physics path for racing. - **Per-mode physics profile**: Arcade-Sim continuous dial preset per ruleset; per-vehicle handling personality baked. ### Racing AI & Director - **Cop AI** (cross-ref §103) state machine: Patrol → Alert → Pursue → Engage → Disengage → Lay-Low; per-heat-level behavior. - **AI Driver personalities** (cross-ref §110): Aggressive / Defensive / Drafter / Reckless / Conservative / Slipstream-Master / Drift- Specialist; per-fighter driving personality reflecting character. - **Racing AI Director** (cross-ref arch§"AI Director Service"): observes player race-skill level + tunes CPU race-time within tunable epsilon. ### Racing Online Racing online extends arch§"Client-Server Netcode" and arch§"Online Services Backend". - **Per-mode matchmaking queues** with separate Racing MMR. - **Per-mode ranked ladder** (Racing + Cop separate where applicable). - **Cross-play** across PC / PS5 / XSX / Switch2 with input-method labeling (wheel vs gamepad vs KB+M). - **Custom Room** with full ruleset customization. - **Autolog rivalry** (Hot Pursuit-inspired) auto-surfacing friend challenges. - **Per-mode max players**: 12 / 4 / 8 / 8 / 12 / 6 / 2 (Circuit / Drag / Drift / Combat / Power-Play / Pursuit / Canyon Duel). ### Vehicle Damage Model ```mermaid flowchart LR Collision[Vehicle Collision] --> Calculate[Damage Calc] Calculate --> CleanTier[Tier 0: Clean] Calculate --> Scuff[Tier 1: Scuffed] Calculate --> Damaged[Tier 2: Damaged] Calculate --> Wrecked[Tier 3: Wrecked] Calculate --> Totaled[Tier 4: Totaled] Wrecked --> PerfImpact[Performance Impact · sim ruleset] Totaled --> RaceRetire[Race Retire · sim] Totaled --> GetOutFight[Get-Out-and-Fight · crossover] PerImpact[Per-Tier Visual Transform] --> MaterialBlend[Material Param + Bone Deformation + Part Fall-Off] ``` ### Racing Replay Racing replay extends the replay system in arch§"Training, Trials, Replay Pipeline". - **Deterministic race replay** ≤ 2MB per 5-min race; replay determinism gate in CI. - **GRID Flashback** (time-rewind) supported in non-ranked modes with per-race-budget. - **Photo Mode** racing-aware with auto-suggest photo opportunities at signature moments (overtakes / crashes / Power-Play / finish-line). - **Racing ghost data** export per Time Trial / Canyon Duel. ### Crossover: Racing × Fighting - **Shared roster** + **shared online backbone** + **shared cosmetic store** + **shared Battle Pass** + **shared currency ledger**. - **Crossover modes** (cross-ref §118): - Fighter-as-driver in any race - Vehicle-on-vehicle melee combat - Get-Out-and-Fight transitions - Crossover signature events (race-then-fight chained) - **Crossover ranked queue** with separate MMR from pure fighting or pure racing. - **Per-fighter signature vehicle** unlocked via fighter Mastery + Side Story. ## Vehicle Designer Service & Pit Crew Minigame ```mermaid flowchart LR Player[Player] --> Designer[Vehicle Designer] Designer --> Sculpt[Geometry Sculpting] Designer --> EngineLayout[Engine Layout Authoring] Designer --> Budget[Per-Component Balance Budget] Designer --> Paint[Paint / Decal / Vinyl] Designer --> SaveSlot[Custom Vehicle Save Slot] SaveSlot --> Code[Shareable Code] SaveSlot --> Gallery[Community Vehicle Gallery] PitCrew[Pit Crew Minigame] --> Actions[Per-Action Mini-Game] Actions --> TireChange[Tire Change] Actions --> OilChange[Oil Change] Actions --> EngineSwap[Engine Swap] Actions --> Alignment[Wheel Alignment] PitCrew --> CrewSpecialty[Per-Crew-Member Specialty Bonus] PitCrew --> CoopPit[Coach-Mode Co-op Pit] ``` - **Vehicle Designer** asset-budget-gated; custom vehicles ranked-eligible only when in the designer-approved subset. - **Pit Crew Minigame** integrated with sim-mode racing for pit-stop strategy. - **Per-driver telemetry dashboard** in profile (cross-ref §47.3). **Service contract** - **gRPC service:** `libs/proto/v2/racing/vehicle-designer.proto`. - **Key methods:** `VehicleDesigner.SaveCustom(account_id, payload) → vehicle_id`, `VehicleDesigner.GenerateShareCode(vehicle_id) → code`, `VehicleDesigner.ImportShareCode(account_id, code) → vehicle_id`, `VehicleDesigner.SubmitForApproval(vehicle_id) → review_id`, `VehicleDesigner.GetGallery(filter) → vehicles[]`. - **Asset-budget gate:** per-vehicle slot has component-cost ceilings (engine tier 1-5 ≤ 100 budget pts; aero ≤ 80; tires ≤ 60; weight reduction ≤ 40). Designer rejects if sum > 240 pts. - **Share-code grammar:** Base32-encoded 12-char code over (vehicle hash + account watermark + creation-time nonce); decoded via `@oshun/crypto` HMAC validation. Codes never expire but can be revoked per-account via moderation. - **Approval workflow:** Themis Originality Shields verify designs against IP / brand database per `V2/docs/decisions/originality-shields-launch-gate.md`; manual reviewer approves designs that pass. Approved designs eligible for ranked custom-vehicle queues. - **Event-bus publishes:** `v2.designer.vehicle.saved`, `v2.designer.vehicle.approved`, `v2.designer.share.imported`. - **SLOs:** save p99 ≤ 600 ms; approval workflow ≤ 7 calendar days; gallery fetch p99 ≤ 400 ms. - **Owner:** V2 racing team + Themis (originality). **Cost-tier:** storage + approval-reviewer; ceiling at `V2/docs/cost/vehicle-designer.md`. ## Convoy & Free-Roam Lobby ```mermaid flowchart TB Lobby[Free-Roam Lobby · 8-32 players] --> InstanceShard[Per-Region Instance Shard] Lobby --> DayNight[Synchronized Day/Night Cycle] Lobby --> Weather[Synchronized Weather] Lobby --> Convoy[Convoy Formation 2-8 players] Convoy --> SharedWaypoint[Shared Waypoint] Convoy --> CrewBonus[Crew Cosmetic Bonus] Convoy --> NPCChallenge[NPC-Initiated Challenge] Lobby --> MeetSpot[Per-District Meet-up Hot-Spot] Lobby --> CruisePhoto[Cruise Photo Session] Lobby --> ChatSystem[Open-World Chat + Radio + Horn] ``` - **No ranked progression** in cruise mode; cosmetic + XP only. - **Per-instance friend-priority sharding** (cross-ref §8.4). ## Heist Mode Architecture ```mermaid flowchart TB HeistStart[Heist Start] --> Recon[Recon Stage · stealth] Recon --> Approach[Approach Stage · drive] Approach --> Infiltration[Infiltration Stage · fight + hack] Infiltration --> Extraction[Extraction Stage · drive + pursue] Extraction --> Resolution[Resolution · cinematic] HeistRoles[Per-Crew Role] --> Hacker HeistRoles --> Wheelman HeistRoles --> Muscle HeistRoles --> Strategist Branches[3 Branch Decisions] --> AltOutcome[Alternate Outcome] HeistOnline[4-Player Online Co-op] --> HostMigration[Session Host Migration] HeistOnline --> LootShare[Per-Player Loot Share] ``` - **Per-quarter signature heist** (cross-ref §83 live service). - **Solo heist** with AI crew at 75% reward. **Service contract** - **gRPC service:** `libs/proto/v2/heist/heist.proto`. Heist instances are **dedicated-server hosted** (cross-ref arch§"Client-Server Netcode"); not inside the rollback envelope. - **Key methods:** `Heist.MatchmakeCrew(account_id, role_pref) → crew_id`, `Heist.StartHeist(crew_id, heist_id, difficulty) → instance_id`, `Heist.ReportStageOutcome(instance_id, stage, outcome) → ack`, `Heist.SubmitFinalResult(instance_id, result) → rewards[]`. - **Per-stage state machine:** `Recon(stealth) → Approach(drive) → Infiltration(fight+hack) → Extraction(drive+pursue) → Resolution`. Each stage has explicit fail-state + retry budget; ≥ 3 failures in a stage triggers branch to alternate-outcome. - **3 branch decisions** at fixed stage transitions; outcome data-driven from `Content/Heist//branches.dat`. - **Loot-share algorithm:** equal split by default with per-crew Robin-Hood modifier (player who contributed most can voluntarily share more). Anti-abuse: rage-quit forfeits loot share; AFK detected via gameplay-tag inactivity. - **AI guard behavior:** state machine `Patrol → Suspicious → Searching → Alerted → Combat → Lost-Sight → Patrol`; behavior tree at `Content/AI/HeistGuard/`. Difficulty scales guard count + perception radius. - **Stealth vs fight balance:** stealth bypass grants 1.5× loot multiplier; full-combat clear grants 1.0× + bonus combat XP. Mixed outcomes scale linearly. - **Event-bus publishes:** `v2.heist.started`, `v2.heist.stage.completed`, `v2.heist.completed`, `v2.heist.failed`. - **SLOs:** crew matchmake p99 ≤ 25 s; dedicated server allocation p99 ≤ 10 s; heist completion ≥ 95% session-success (no server-side disconnects). - **Owner:** V2 modes team. **Cost-tier:** dedicated-server budget; ceiling at `V2/docs/cost/heist.md`. ## Demolition Derby & Crossover Arena - **Demolition Derby** mode plugins as `V2Mode_DemolitionDerby` with per-arena-type variants. - **Vehicle-Hijack input-RPS** layer integrated with Combat Racing ruleset (cross-ref §104). - **Fight-On-Vehicle** ruleset using fighting GAS system (cross-ref §2) on a moving-vehicle stage; per-vehicle Fight-On-Vehicle compatibility authored. - **Mad-Max truck/bike chase combat** plugin `V2Mode_TruckChase`. - **Convoy Raid co-op** plugin `V2Mode_ConvoyRaid` (2-4 player attacker vs AI convoy). ## VR / AR Architecture ```mermaid flowchart LR Player[Player] --> Platform[Per-Platform VR Path] Platform --> PSVR2[PSVR2 · 4K-per-eye + foveated + eye tracking] Platform --> Quest[Quest 3 · async-time-warp + hand tracking] Platform --> VisionPro[Vision Pro · MR + gaze-and-pinch] Platform --> PCVR[PC VR · SteamVR / Oculus / Windows MR] Platform --> Comfort[Comfort Modes · vignette + snap-turn] Platform --> HUD[VR HUD · minimal + 3D physical UI] Platform --> Cert[Per-Platform VR Cert + Comfort Review] Cross[Cross-play VR vs non-VR] --> Matchmaking[Opt-in for non-ranked] ``` - **VR-specific cert** per platform with epilepsy / motion-sickness compliance. - **VR accessibility**: seated mode + one-controller mode + voice-activated menu + 3D subtitle positioning. ## Hardware Peripherals SDK Integration - **Per-vendor SDK integration layer** at `Source/V2Peripherals/`: Logitech / Thrustmaster / Fanatec / Hori / MOZA / Cammus / Asetek SimSports / Simucube / Heusinkveld / Quadstick / PlayStation Access Controller / Xbox Adaptive Controller / Logitech Adaptive Gaming Kit. - **Per-vendor force-feedback runtime**: per-vehicle FFB profile authored + per-vehicle FFB tuning UI; Direct-Drive specific scaling to avoid overpowering force. - **Per-controller-class ranked pool**: Wheel + Pedals vs Gamepad separation in tournament mode with per-pool assists baseline. - **First-launch calibration wizard** for detected peripheral. - **Community FFB profile gallery** sharing. ## Roguelike, Battle Royale, Sports Vehicle, Specialty Combat Architectures ```mermaid flowchart LR Player[Player] --> RogueHub[Roguelike Hub] RogueHub --> ProcGen[Procedural Room Graph] ProcGen --> CombatRoom[Combat Room] ProcGen --> ShrineRoom[Boon Shrine] ProcGen --> ShopRoom[Shop Room] ProcGen --> BossRoom[Cinematic Boss] BossRoom --> MetaCurrency[Meta-Currency Hub Upgrade] Player --> BR[Battle Royale] BR --> Ring[Shrinking Ring · 4-6 contraction phases] BR --> LootCrate[Loot Crate · per-rarity drops] BR --> SquadComms[Squad Voice / Ping] Player --> SportsModes[Sports Vehicle Modes] SportsModes --> Soccer[Vehicle Soccer] SportsModes --> Stunt[Stunt Mode] SportsModes --> CrashMode[Burnout Crash] SportsModes --> Trackmania[Time-Trial Precision] Player --> Specialty[Specialty Combat] Specialty --> Boxing[Punch-Out Boxing Sim] Specialty --> Bushido[Bushido One-Hit-Kill] ``` - **Roguelike Hub world** persisted between runs; per-run procedural generation seed; per-boon synergy graph data. - **Battle Royale** uses client-server net (cross-ref arch§"Client-Server Netcode") with 100-player session sharding; squad-voice via EOS Voice; ring-state is **server-authoritative** and replicated to all clients **consistently** (within one frame of replication latency). BR sits **outside the rollback envelope** described in arch§"Combat Authority & Determinism"; "deterministic" never applies to BR — clients see the same state because the server is the source of truth, not because clients resimulate. Cheat detection runs server-side on the authoritative state. - **Sports Vehicle Modes** each ship as own `V2Mode_VehicleSoccer` / `V2Mode_VehicleStunt` / `V2Mode_VehicleCrash` / `V2Mode_Trackmania` GameFeaturePlugins. - **Specialty Combat Modes** as `V2Mode_BoxingSim` / `V2Mode_BushidoBlade` plugins. ## Persistent World Economy & NPC Schedules ```mermaid flowchart LR Players[Player Population] -- purchases --> EconomyService[Persistent Economy Service] EconomyService -- daily rotation --> ShopInventory[Per-Shop Inventory] EconomyService -- supply-demand --> CosmeticPrices[Cosmetic Price Adjuster] NPCSchedule[NPC AI Schedule Manager] --> NPCBehavior[Per-NPC Daily Routine] NPCBehavior --> DistrictPop[Per-District Population Density] PlayerActivity[Player + NPC Criminal Activity] --> CrimeRate[Per-District Crime Rate] CrimeRate --> CopSpawn[Cop Spawn Density] CrimeRate --> Lockdown[Extreme Lockdown Trigger] ``` - **Economy ops dashboard** (cross-ref arch§"Telemetry & Analytics") for inflation / deflation / cosmetic-price-distribution monitoring. - **NPC schedule + crime-rate state** persisted per-account world-state save; cross-platform synced. ## Director Commentary & Cinematography Pipeline - **Per-cinematic commentary track** authored as a Sequencer audio sub-track; toggleable at runtime (cross-ref §45.7 + §73.3). - **ADR pipeline** integrated with VO production (cross-ref §77.3); per-quarter session scheduled at recording studios. - **Cinematography library** assets at `V2/balance/cinema/` consumed by `V2Mode_CinematographyEditor` plugin for authoring tooling. - **Per-fighter origin comic** content at `V2/balance/comics//` with per-locale translation tables. - **Story DLC seasons** delivered via GameFeaturePlugin (cross-ref §52.2) with full ADR + comics + cinematics bundled per season. ## Karaoke, Arcade Mini-Games, World Boss, AI Commentary, Vault ```mermaid flowchart LR Player[Player] --> Karaoke[Karaoke + Rhythm Mode] Karaoke --> RhythmGrid[Rhythm-aware Music Grid] Karaoke --> ScoreFreq[Pitch + Timing + Style Scoring] Player --> Arcade[Arcade Mini-Game Suite] Arcade --> Pinball Arcade --> AirHockey Arcade --> MiniGolf Arcade --> Darts Arcade --> Pool Arcade --> Cooking Arcade --> TekkenBowl Arcade --> PhotoTournament WorldBoss[World Boss Service] --> SharedHP[Community-Shared HP] SharedHP --> PerContribution[Per-Player Contribution Validation] PerContribution --> RewardTier[Per-Tier Reward · Bronze → Mythic] AICommentary[AI Commentary Service] --> MatchData[Per-Match Telemetry] MatchData --> PlayByPlayGen[Play-by-Play Generation · per-locale TTS] MatchData --> HighlightAI[Auto-Edited Highlight Reel] MatchData --> AnalysisScreen[Per-Match Analysis] Vault[Per-Account Vault] --> CloudStore[Cloud-Side Unlimited Cosmetic Storage] Vault --> ReplayArchive[Lifetime Replay Archive] Vault --> GhostArchive[Lifetime Ghost Data Archive] Vault --> Inheritance[Estate-Planning Inheritance] ``` - **Karaoke + Rhythm Mode** uses MetaSounds graph with per-track BPM tagging; per-song scoring server-validated to prevent cheating. - **Karaoke rhythm-combat bridge:** `@v2/karaoke-rhythm-combat-bridge` composes Euterpe genesis / accompany / protect, Calliope sound-design, and Iris voice for procedural backing tracks, adaptive accompaniment, DMCA-safe streamer-mode swaps, per-fighter theme variations, and guide-voice speed/pitch directives. The bridge emits cook-time manifests for `V2Mode_Karaoke`, `V2Mode_RhythmCombat`, `V2DynamicMusic`, `V2Audio`, and the V2-owned pitch/rhythm scoring rubric; it is off rollback and rejects live rhythm-combat frame RPCs. - **Arcade Mini-Game plugins**: each ships as its own GameFeaturePlugin — `V2Mode_Pinball`, `V2Mode_AirHockey`, `V2Mode_MiniGolf`, `V2Mode_Darts`, `V2Mode_Pool`, `V2Mode_Cooking` (and `V2Mode_PhotoTournament` for the Photo-Mode jury-vote competition). The Subsystem Glossary enumerates the full plugin list; arcade-cabinet plugins compose with `V2Mode_BattleHub` for in-hub cabinet rendering and with `V2Mode_QuestLog` for daily achievements. - **Maya mini-game suite bridge:** `@v2/maya-minigame-suite-bridge` reuses Maya games projectile physics, Maya scene readiness, Maya physics readiness, and Maya input mapping for `V2Mode_Pinball`, `V2Mode_AirHockey`, `V2Mode_MiniGolf`, `V2Mode_Darts`, and `V2Mode_Pool`. V2 plugins keep per-game rules, scoring, cabinet art, leaderboard schema, quest hooks, and tuning. Maya combat, abilities, items, and inventory systems are explicitly excluded for the basic suite. The bridge is off rollback and rejects live mini-game frame RPCs. - **Tekken Bowl arcade cabinet bridge:** `@v2/tekken-bowl-arcade-cabinet-bridge` reuses Maya games `ProjectilePhysicsSystem` for the Tekken Bowl lane probe and Maya client `MayaClientModPluginManager` for ad-hoc per-cabinet plugins. The bridge emits the `v2.battle-hub.arcade-cabinets.maya-games-plugins` cook manifest for `V2Mode_BattleHub`, `V2Mode_TekkenBowl`, and `V2ArcadeCabinetAdHocPlugin`, enforces 1 Fighter Coin play gates with ambassador / pro-player free-play, requires per-cabinet leaderboards, stays off rollback, and rejects live Battle Hub frame RPCs. - **World boss community raid bridge:** `@v2/world-boss-community-raid-bridge` composes Themis shared HP governance and contribution-validation schema, Maat per-contribution aggregate dashboard signals, Hathor world-state spawn simulation, and Kuanyin raid defense for grief coordination. The bridge emits the `v2.world-boss-community-raid-manifest`, publishes only post-match server submission contracts, keeps shared HP display-only, and rejects live rollback frame RPCs. - **Per-account vault estate bridge:** `@v2/per-account-vault-estate-bridge` composes Lakshmi estate planning, `@oshun/identity` account inheritance / delegation gates, and Themis transfer audit. The bridge emits the `v2.per-account-vault-estate-transfer-manifest` and reciprocal `v2.per-account-vault-asset-transfer` schema, requires verified identity, beneficiary readiness, accepted delegation evidence, and immutable transfer audit records, stays off rollback, and rejects live gameplay frame RPCs. - **Photo Mode tournament voting bridge:** `@v2/photo-mode-tournament-voting-bridge` composes Kuanyin precognition moderation pre-pass with Themis ranked-choice jury voting and approval voting. The bridge emits the `v2.photo-mode-tournament-voting-manifest` and reciprocal `v2.photo-mode-tournament-voting-profile`, certifies winners for community gallery surfaces only, stays off rollback, and rejects live gameplay frame RPCs. - **World Boss Service** runs as cloud backend (cross-ref §16). World Boss sits **outside the rollback envelope**: per-contribution damage is computed client-side from the local match's frame-deterministic combat, then **submitted to the server after the contributing match ends** rather than applied inside the rollback loop. The community-shared HP state is therefore **gameplay-inert during any individual match** — it never affects the in-match simulation. Clients receive shared-HP updates via server push for HUD display only; the HUD is gameplay-inert per the arch§"Sovereign V2 surfaces (never delegated)" rule. Per-contribution validation runs server-side after match submission; tampered submissions are rejected without affecting any live match. - **AI Commentary Service** generates play-by-play text from match telemetry; per-locale text + TTS per-locale voice (cross-ref §43.7); EU AI Act-disclosed (cross-ref §80.4). - **Per-account Vault** stored cloud-side with daily immutable cold-storage snapshots; vault transfer on account merge audited. ### World Boss Service Contract - **gRPC service:** `libs/proto/v2/world-boss/world-boss.proto`. - **Key methods:** `WorldBoss.GetActiveBoss(region) → boss_state`, `WorldBoss.SubmitContribution(account_id, match_id, damage) → ack`, `WorldBoss.GetLeaderboard(boss_id, region, page) → contributors[]`, `WorldBoss.ClaimRewards(account_id, boss_id) → rewards[]`. - **Determinism boundary:** match-time damage submission only; no rollback-loop reads of shared HP. Damage validation runs the match's golden-replay hash through `@nous/safety` cheat classifier before crediting the account. - **Event-bus publishes:** `v2.world-boss.spawned`, `v2.world-boss.defeated`, `v2.world-boss.contribution.submitted`. - **SLOs:** contribution submit p99 ≤ 2 s; leaderboard fetch p99 ≤ 400 ms; shared-HP update push p99 ≤ 5 s end-to-end. - **Owner:** V2 modes team + Hathor (world-state). **Cost-tier:** ceiling at `V2/docs/cost/world-boss.md`. ### AI Commentary Service Contract - **gRPC service:** `libs/proto/v2/ai-commentary/commentary.proto`. - **Determinism rule:** off-rollback only; outputs are audio / subtitle inert (cross-ref arch§"Sovereign V2 surfaces (never delegated)" — commentary outputs never feed simulation state). - **V2AICommentary bridge:** `V2/ue/Plugins/V2AICommentary/` uses `@v2/iris-commentary-orchestration` to call `createMatchCommentaryStream` on `@iris/conversation-orchestration`. The bridge rejects `fromRollbackFrame=true`, records `(matchId, cueId, cueTriggerFrame, branchId)`, and routes only audio/subtitle output back to V2Audio. - **Calliope commentator personas:** `@v2/calliope-commentator-personas` validates the `@calliope/persona-live` launch roster at `V2/ue/Content/V2/Audio/Commentary/commentator-personas.json`. Each commentator has cleared `@iris/voice` voice clone metadata. The roster stores brand metadata, talent signoff, deterministic fallback-bank metadata, and audio/subtitle-only `gameplayInert` output. `V2Audio` consumes the roster via `BuildDefaultCommentaryPersonas()`. - **Psyche commentator face animation:** `@v2/psyche-commentary-face-animation` consumes `@iris/voice` output metadata, then drives `@psyche/avatar-lipsync` viseme frames and `@psyche/avatar-expressions` ARKit expression curves for commentator face animation. `V2Audio` validates the generated `/Game/V2/Audio/Commentary/FaceAnimation` export as gameplay-inert and off-rollback. - **Euterpe commentary mix ducking:** `@v2/euterpe-commentary-ducking` reads `@euterpe/accompany` dynamic music context, uses `@euterpe/master` loudness and gain math, and exports `FV2CommentaryDuckingMixSpec` automation from `V2.Commentary` into `V2.DynamicMusic`. `V2Audio` applies the ducking as audio-mix-only, gameplay-inert, and off-rollback. - **Key methods:** `Commentary.StreamCommentary(match_stream) → audio_stream`, `Commentary.GenerateHighlightReel(match_id) → reel_url`, `Commentary.GenerateAnalysis(match_id) → analysis`. - **Backed by deps§67:** Anthropic Claude Sonnet 4.6 generates the play-by-play text, ElevenLabs Multilingual v2 synthesizes the TTS audio, and Isis `ai-video` performs the highlight-reel auto-edit. - **Esports cost-ceiling:** per-match-per-minute LLM cost capped per `V2/docs/cost/ai-commentary.md`; on-cap routes to `@iris/conversation-providers-local`. - **EU AI Act:** Limited risk; on-screen "AI commentary" badge mandatory. `V2/docs/ai/model-cards/ai-commentary.md` is hosted by `@nous/safety`, and `@themis/accountability` owns the conformity export through `@v2/eu-ai-act-surface`. - **SLOs:** real-time KO commentary lag p99 ≤ 800 ms from gameplay event to audio. V2 reserves 420 ms for Iris LLM round trip, 240 ms for persona TTS, 100 ms for Psyche lipsync/expression render, and 40 ms safety margin; on miss, it falls back to the pre-recorded bank keyed by `(cueKind,ruleset,commentatorId,seed)`. Highlight reel generation p99 ≤ 90 s for a 5-min match. - **Owner:** V2 audio team + Iris + Calliope + Psyche + Euterpe. **Cost-tier:** ceiling at `V2/docs/cost/ai-commentary.md`. ### Persistent Economy Service Contract - **gRPC service:** `libs/proto/src/oshun/v2/persistent_economy/economy.proto`. - **Key methods:** `Economy.GetShopInventory(district_id) → inventory`, `Economy.GetPriceCurve(item_id) → curve`, `Economy.RecordTransaction(account_id, item_id, qty, price) → ack`, `NPCSchedule.GetActiveSchedule(district_id, time_of_day) → schedule`, `CrimeRate.GetDistrictRate(district_id) → rate`. - **Tick rate:** market simulation runs at 1 tick / hour (server-side); NPC schedules tick at 1 / 5min; crime-rate aggregates over 24h windows. - **Anti-bot enforcement:** `@nous/safety` market-bot classifier flags abnormal transaction patterns (rapid alt-account farming, pump-dump on player-driven prices); flagged accounts blocked from market. - **Event-bus publishes:** `v2.economy.price.shifted`, `v2.economy.transaction.recorded`, `v2.crime.lockdown.triggered`. - **SLOs:** inventory fetch p99 ≤ 400 ms; transaction p99 ≤ 800 ms; bot-detection latency ≤ 24h to first flag. - **Owner:** V2 world team + Hathor (simulation) + Maat (economy). **Cost-tier:** ceiling at `V2/docs/cost/persistent-economy.md`. ## Real-World Brand & Celebrity Pipeline - **Per-brand sponsorship slot** managed via `V2/legal/sponsorships.md` with a per-brand contract lifecycle (term / royalty / removal clause). - **Per-celebrity guest character** ships as `V2Mode_CelebrityGuest_` GameFeaturePlugin (license-conditional, removable on contract end). - **Per-venue tie-in stage** ships as `V2RaceTrack_` plugin with per-venue licensing-conditional manifest. - **Per-partnership ethics review** workflow at `V2/docs/partnerships/` with community-advisory board sign-off. ## Launch Readiness See `V2_TODOS.md` § 138 "Launch Readiness". Architecture must satisfy: - Internal dogfood ≥ 60 days across all modes and platforms. - Closed beta with measurable target metrics (concurrent peak, matchmaking time, rollback frame distribution, crash rate, AC false-positive rate). - Cert / TRC / XR / lotcheck on every shipping platform. - Network stress test at 5× launch-estimated concurrency. **Planning assumption (adopted 2026-06-12; revisit at beta):** launch-estimated global concurrency = **100,000 CCU** — sized against recent AAA fighting-game launches (SF6 and MK1 peaked at roughly 60-70k concurrent on Steam, with consoles adding a comparable share), rounded up for cross-platform day-one overlap. 5× therefore = **500,000 CCU** for the stress-test gate. - Per-platform rollback plan + per-service rollback plan. - Day-one patch staged. - Critical-journey verification across every advertised mode. ## Sister-Monorepo Integration Surface V2 is its own codebase with its own quality bar, but the Oshun monorepo already ships production-grade domains that cover most of V2's non-deterministic surface area. Rather than re-implement these inside `apps/v2/` and `V2/tools/`, V2 consumes named Oshun domains across three integration channels: (a) Bellona's offline content pipeline at cook time, (b) the Oshun event bus + gRPC clients at runtime for non-deterministic warm-path services, and (c) the Oshun shell apps (`apps/oshun/web`, `apps/oshun/mobile`) for the out-of-game surface area. The deterministic combat inner loop — `V2Combat`, `V2Gameplay`, `V2Input`, `V2Netcode` rollback, save-format/replay-container, platform anti-cheat — stays V2-local without exception. ### Sovereign V2 surfaces (never delegated) The following are non-negotiably V2-local because they sit inside the frame-deterministic, rollback-synchronized, or cert-driven envelope: hitbox / hurtbox engine, frame-data table runtime, motion-input parser + buffer, rollback engine, client-server replication for asymmetric modes, save-format binary + replay container, Sequencer cinematic timelines, per-platform IMC files, anti-cheat client driver, and the per-fighter signature animation runtime. Anything else is in scope for the integration table below. ### Per-surface mapping (V2 → Oshun owner) | V2 surface | Oshun owner | Integration channel | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | Auth + cross-progression | `@oshun/identity` + Shared auth | gRPC client (runtime) | | ML balance recommender | `@v2/maat-balance-dashboard` over `@maat/intelligence` + `@maat/dashboard` + `@maat/reporting`, `@v2/sophia-release-candidate-ingestion` over `@sophia/ingestion` for frame-data spreadsheet + patch-notes corpus citations, and Nous (model serving); no standalone V2 balance dashboard | Event bus + Maat dashboards | | AI commentary + highlight reel | Iris (LLM orchestration + voice), Calliope (commentator personas), Psyche (commentator face animation), Euterpe (music ducking) + Nous (model hosting) | gRPC client + Bellona/audio cook | | AI Director + adaptive difficulty | Psyche (behavior prediction) + Shakti (combat-sport tendency) + Nous (model serving) | gRPC client (off-rollback) | | Creator Suite (CAF/CAW/CAS/CAA/CAE) | Yemaya (orchestration) + Isis (gen) + Aglaea (`@aglaea/style-coaching` + `@aglaea/color-analysis`) + Themis (`@v2/themis-originality-shields` over `@themis/music-shield`, `@themis/visual-shield`, `@themis/text-shield`, `@themis/video-shield`, `@themis/design-shield`) | Bellona cook + companion app | | Moderation (gallery, chat, replays) | Kuanyin (`@v2/kuanyin-first-line-moderation` over `@kuanyin/precognition` + `@kuanyin/foundation`, `@v2/kuanyin-mindful-friction` over `@kuanyin/mindful-friction`, `@v2/kuanyin-performer-protection` over `@kuanyin/performer-protection`) + Themis (`@v2/themis-dispute-resolution` over `@themis/dispute-resolution` for DSA Statement of Reasons + appeals) | Event bus + Iris voice hooks | | Esports broadcast + bracket | Uzume (broadcast / show control / overlays) + Veritas (post-match reporting) + Iris (real-time translation) | Apps/oshun web + companion | | Marketing site + roster microsite | `apps/oshun/web` shell + Calliope content + Sophia lore | Apps/oshun web | | Companion app + public API + knowledge pages | `apps/oshun/mobile/v2/` + `apps/oshun/web` `/v2/wiki`, `/v2/glossary`, `/v2/roadmap` + `@iris/agents` (assistant) + `@sophia/client` (codex/frame-data RAG and citations) + `@oshun/concordia-integration` / `@oshun/trust-safety` for appeals and safety gates | Apps/oshun web + mobile | | Currency ledger + cosmetic store | Maat (BI + compliance) + Aje (optional cosmetic NFT) + Lakshmi (`@v2/lakshmi-responsible-play-spend-insight` player-side spend insight, opt-in) | gRPC client + store confirmation | | Telemetry + balance dashboards | `@v2/maat-balance-dashboard` composes `@maat/intelligence` + `@maat/dashboard` + `@maat/reporting`; `@v2/sophia-release-candidate-ingestion` refreshes Sophia cited frame-data context on every release-candidate cook and Nous serves model recommendations | Event bus | | Anti-cheat ML (smurf, win-trading, coordinated-throw, geographic-anomaly) | `@v2/nous-anti-cheat-classifiers` over `@nous/training` + `@nous/safety`, with Kuanyin precognition for salt-cascade context only | Event bus + hosted Model Card | | Cinematic Story / Side Stories / Krypt | Hathor (worldbuilding, dialogue trees, story graphs, lore-compiler) + Sophia (consistency) + Iris (LLM dialogue) | Bellona/lore-compiler cook | | NPC AI (World Tour / Tekken Force / DW) | Hathor `@hathor/llm-npc` via V2 `@v2/hathor-npc-adapter` (personality, memory, world awareness, NPC-to-NPC, safety guardrails) | gRPC client (off-rollback) | | Mocap pipeline | Aja (capture / clean / retarget / quality) + Bellona/mocap + Bellona/unreal Live Link | Bellona cook | | MetaHuman pipeline | Bellona `@bellona/metahuman` (already shipped) | Bellona cook | | Combat Trials / Mission curriculum | Shakti (combat-sports, martial-arts, form-analysis) + Metis (adaptive paths, AI tutoring) | gRPC client + companion | | Profile cards / titles / achievements | `@oshun/identity` + Yemaya (asset orchestration) | gRPC client (runtime) | | Voice chat | Iris voice + `@v2/iris-accessibility` over `@iris/accessibility` for screen-reader bridge semantics + `@v2/psyche-caption-streaming` over Psyche `@psyche/caption-streaming` for real-time match captions, spectator mode captions, and translation/captions + Kuanyin (real-time toxicity shield) | Iris voice runtime | | Per-feature consent surfaces | `@v2/aphrodite-consent-surfaces` over `@aphrodite/consent-engine` for telemetry, voice processing, and behavioral profiling consent receipts, redaction, and privacy-preserving fallbacks | gRPC client + apps/oshun | | Crew / faction / clique systems | Kuanyin (`@v2/kuanyin-community-harmony` over `@kuanyin/community-harmony`) for temperature + raid defense, Themis (`@v2/themis-community-governance` over `@themis/community`) for rule votes, reputation standing, and constitutions + Aje (optional fan tokens) | gRPC client + apps/oshun | | Photo Mode + replay auto-edit | Isis (`ai-video`, `video-enhancement`, `post-production-ai`) + Calliope `cinema` | Bellona cook + apps/oshun web | | Real-world brand / celebrity / NIL | Themis (IP / NIL ledger) + Aje (optional on-chain rights manifest) + Kuanyin (`@v2/kuanyin-performer-protection`) + Aphrodite (`@v2/aphrodite-licensed-likeness-safety` over `@aphrodite/performer-sovereignty` + `@aphrodite/performer-autonomy`) for licensed-fighter likeness safety and revocation flow | gRPC client + Bellona cook | | Adult-content gore gating per region | `@v2/aphrodite-age-gate` over `@aphrodite/age-verification` for runtime gore tier, adult fatalities, and region-conditional cinematics; primitive-fitness audit applies the `mature-rated-fighting-game` profile instead of the adult-content default; shared `@oshun/region-rules` cooks CN / DE / AU / NZ / KR gore variants and content cuts from Aphrodite age / consent inputs, defaulting missing region data to the China most-restrictive profile | gRPC client + Bellona cook | | Live-service calendar / battle pass | `@v2/maat-live-service-calendar` over `@maat/strategy` for seasons, Crown Points, Pro Circuit calendar, anniversary events, charity events, and balance ramp windows + Maat finance + Calliope (seasonal artist tie-ins) + Euterpe (seasonal music drops) | gRPC client + apps/oshun | | Compliance (GDPR / CCPA / DSA / 2257) | Shared `data-residency` + Maat compliance + Themis `arbitration` + `@v2/aphrodite-age-gate` over `@aphrodite/age-verification` + `@v2/aphrodite-consent-surfaces` over `@aphrodite/consent-engine` + Kuanyin restorative | gRPC client + audit log | ### Generative + procedural pipeline binding Bulk content that V2's previous draft left hand-authored is delegable to the following Oshun pipelines. The pattern is uniform: **Isis generates → Themis verifies originality → Kuanyin moderates → Bellona cooks → V2 consumes.** - Character textures / costume palette variants → Isis `ai-texturing` + Aglaea palette intelligence + Bellona/unreal cook. - Decals / logos / patterns for CAW gallery → Isis image-gen + `@v2/themis-originality-shields` + Kuanyin moderation. - Stage variants (weather, time-of-day, crowd dressing) → Isis `3d-scene-assembly` + Hathor simulation + Maya `genesis-terrain` / `genesis-urban` + Bellona/openusd. - Real-world venue capture → Isis `gaussian-splatting` + Bellona/openusd + Bellona/unreal Nanite stage cook. - Music adaptive stems / per-fighter themes / seasonal drops → Euterpe `genesis` (music generation) + Euterpe `accompany` + Euterpe `protect` (copyright clearance). - Crowd voice barks / ambient VO → Iris voice + Psyche voice synthesis + Calliope persona voice bank. - AI commentary lipsync (the V2 Audio2Face gap) → Psyche `avatar-lipsync` + Psyche `avatar-expressions` driven by `@iris/voice` output + Bellona/metahuman. - NPC schedules + open-world dressing → Hathor `simulation` (economy, politics, ecology) + Hathor `@hathor/llm-npc` + Maya `inspirations`. - Fighter banter / win quote permutations → Hathor `@hathor/llm-npc` under Themis IP gates + Kuanyin safety filter. - Auto-edit highlight reels + thumbnails → Isis `ai-video` + Calliope `cinema` + Themis originality stamp from `@v2/themis-originality-shields`. - Frame-data balance permutations under recommender → `@v2/maat-balance-dashboard` (`@maat/intelligence` trends/anomalies, `@maat/dashboard` surface manifest, `@maat/reporting` scorecards/charts) + `@v2/sophia-release-candidate-ingestion` release-candidate cook citations from the frame-data spreadsheet and patch-notes corpus + Nous model serving. - Adaptive training drills → Metis adaptive paths + Shakti technique database + Psyche behavior modeling. - Animation cleanup / retarget → Aja `motion-processing`, `neural-retargeting`, `motion-quality`, `optimization-ik`. - Form / pose validation for player-driven fitness modes → Shakti `form-analysis` + Aja pose estimation. ### Integration channels - **Channel A — Build-time content pipeline (offline).** Bellona orchestrates Isis-generated assets, Aja-cleaned mocap, Hathor-authored narrative, Euterpe-generated music, and Themis-cleared rights manifests into engine-native `.uasset` / `.umap` artifacts via the existing `@bellona/unreal` bridge and `BellonaUnrealEditor.uplugin`. V2 cook consumes these. - **Channel B — Runtime services bus (warm path, off-rollback).** `apps/v2/` becomes a thin adapter layer over the existing Oshun `@oshun/event-bus` (Redis Streams) and gRPC clients generated from `libs/proto/`. V2 runtime publishes events (`v2.match.ended`, `v2.cosmetic.purchased`, `v2.player.reported`) and subscribes to ecosystem events (`hathor.dialogue.ready`, `hathor.world.published`, `isis.asset.cooked`, `maat.balance.recommendation`). Latency-sensitive matchmaking / presence deploy regionally; the rest reuses shared infra. V2 narrative source for Story, Side Story, Krypt, Chronicles, and DJ Story lives in `apps/hathor/studio-web`; V2 consumes the `@hathor/lore-compiler` output as compiled artifact only. - **Channel C — Out-of-game surfaces.** The V2 marketing tile, companion app, public API, frame-data wiki, and esports portal become new tiles under `apps/oshun/web` and `apps/oshun/mobile`, consuming the `@oshun/shell-core` umbrella plus per-surface clients (`@oshun/auth-client`, `@oshun/developer-portal`, `@oshun/concordia-integration`, `@oshun/persistence`, `@oshun/trust-safety`, `@oshun/persona-registry`). The historical monolithic `@oshun/sdk` package does not exist; consumers import the specific surfaces they need. The web tile now lives at `apps/oshun/web/src/app/v2/` and is linked from `/explore`; standalone Sanity / Contentful content stacks are not V2 dependencies for that route. The companion surface lives at `apps/oshun/mobile/v2/` and links from mobile Explore through the shared Expo shell. Cross-product entitlements (e.g., Lilith meditation-streak unlocks a V2 card border) become trivial because account state already lives in `@oshun/auth-client` and related Oshun account surfaces. - **Aje Web3 cosmetic ownership and faction governance.** Optional Web3 cosmetic ownership is exposed through `@v2/aje-web3-cosmetic-ownership`, composing `@aje/identity` and `@aje/nft`; optional fan-token faction governance is exposed through `@v2/aje-faction-governance`, composing `@aje/governance`. Both paths require explicit opt-in and a per-platform cert-ban gate. The source of truth is `V2/legal/platform-cert-bans.json`; cooked-binary reachability is recorded in `V2/ue/Build/PlatformCookAjeReachability.json`, and `check-platform-cert-bans.py` fails CI if any Aje surface is reachable where `bannedSurfaces[]` prohibits it. - **Racing ecosystem bridge.** The V2 racing component (§96-119) consumes Galatea kinematics / whole-body control, Saraswati EV powertrain primitives, and Maya Genesis terrain / urban generation through `@v2/racing-ecosystem-bridge`. The bridge emits cook-time manifests for `V2Vehicles`, `V2RacePhysics`, and `V2RaceTracks`; it is off rollback and rejects live race-frame RPCs. - **Lakshmi responsible-play spend insight.** Player spend insight is exposed through `@v2/lakshmi-responsible-play-spend-insight`, composing `@lakshmi/behavioral`, `@lakshmi/budgeting`, and `@lakshmi/transactions` for opt-in nudges, parental controls, self-imposed caps, weekly summary reflection, and category budget velocity. It is off rollback and can only affect store confirmation, warnings, or guardian approval. - **Kuanyin first-line moderation.** Text, report, replay transcript, player name, and UGC caption checks are exposed through `@v2/kuanyin-first-line-moderation`, composing `@kuanyin/precognition` and `@kuanyin/foundation` as the first-line taxonomy and decision source. Two Hat and Community Sift are retired from V2 first-line text moderation; Hive AI and AWS Rekognition are retained only as media fallback providers for image or video coverage gaps. The service is off rollback and cannot influence deterministic inputs, simulation, or competitive frame outcomes. - **Kuanyin mindful friction.** Report submissions and flagged-message send attempts are exposed through `@v2/kuanyin-mindful-friction`, composing `@kuanyin/mindful-friction` pause-and-breathe overlays, Samma Vaca reflection gates, compassion nudges, timing optimization, skip policy, frequency management, and rewrite suggestions. Reports use the `report_submitted` trigger; flagged messages use `flagged_content`. The service is off rollback and can delay only report or message release timing, never deterministic inputs, simulation, or competitive frame outcomes. - **Kuanyin community harmony.** Crew, faction, and Battle Hub communities are exposed through `@v2/kuanyin-community-harmony`, composing `@kuanyin/community-harmony` temperature monitoring, tension detection, faction formation, intervention triggers, raid detection, defense mode, new-user throttles, posting restrictions, trusted-only mode, raid documentation, recovery, reassurance messaging, and platform reporting. The service is off rollback and can affect only community trust-and-safety controls, never deterministic inputs, simulation, or competitive frame outcomes. - **Themis community governance.** Crew, clique, stable, and faction governance is exposed through `@v2/themis-community-governance`, composing `@themis/community` sports-club rule committees, rule proposal voting, member reputation standing, and association-style constitution ratification for crew rules. The service is off rollback and can publish or hold social governance state, never deterministic inputs, simulation, or competitive frame outcomes. - **Kuanyin performer protection.** Licensed-fighter chat, Battle Hub chat, replay comments, creator-suite uploads, and commentary mentions are exposed through `@v2/kuanyin-performer-protection`, composing `@kuanyin/performer-protection` real-time shield, harmful-message interception, performer blindness, threat assessment, protection adjustment, emergency lockdown, boundary enforcement, shield configuration, and dashboard custom-rule builders. Every request cross-references the Themis NIL ledger stamp (`@themis/likeness`, `rightsManifestSha256`, `consentChainRefs`, and `themis.license.revoked`). The service is off rollback and can affect only likeness safety, publishing, cook, or moderation routing controls. - **Aphrodite licensed-fighter likeness safety.** Likeness surfaces, creator-suite uploads, replay exports, voice-line banks, commentary mentions, esports broadcast use, and Bellona cook run through `@v2/aphrodite-licensed-likeness-safety`. The bridge composes `@aphrodite/performer-sovereignty` for approved-use gating and `@aphrodite/performer-autonomy` for revocation flow, cross-references `@themis/likeness`, and treats `themis.license.revoked` as a hard cook block. ### Capabilities V2 forces Oshun to build Integration is bidirectional. V2's requirements expose real gaps Oshun must close, each tracked as a reciprocal task in its owning `DOMAINS//` spec. 1. `BellonaUnrealRuntime` — runtime-shipped UE plugin (current `BellonaUnrealEditor` is editor-only). _Owner: Bellona._ 2. Low-latency in-match commentary contract for Iris. **Determinism rule:** commentary outputs are audio / subtitle only and never feed simulation state, so the contract can be off-rollback because its outputs are gameplay-inert. Implemented by `createMatchCommentaryStream` in `@iris/conversation-orchestration` and consumed by `@v2/iris-commentary-orchestration` / `V2AICommentary`. _Owner: Iris._ 3. AI Director behavior-hint integration with Psyche. **Determinism rule:** behavior hints cannot use a live mid-match channel — both peers must run identical CPU logic inside the rollback envelope. Two valid modes only: **(a) offline / training** consumes live Psyche tendency hints freely; **(b) online rollback matches** bake a tendency-vector + seed into the deterministic match-start input stream, then run rollback-deterministic AI for the match. Live mid-match Psyche updates queue and apply at the next match-start. _Owner: Psyche._ 4. Shakti per-player combat-style classification for AI Director matchup tuning. `@shakti/sota-critical` emits `boxer`, `kickboxer`, `striker`, `grappler`, or `submission-specialist` classifications; V2 consumes them through `@v2/shakti-style-classification` and `V2AdaptiveAI` as off-rollback match-end or match-start snapshot hints. _Owner: Shakti._ 5. Aja → Bellona/mocap → Bellona/unreal export: **60 Hz resampling and frame-snap alignment** for source mocap. `@bellona/mocap` rejects sub-frame notify-segment boundaries, `@bellona/unreal` receives an editor-only Live Link handoff, and runtime Live Link plugins remain disabled. Notify-segment authoring (hit-active, armor, cancel-window) stays in UE animation montage authoring. _Owner: Aja + Bellona._ 6. Themis NIL / likeness ledger schema (per-fighter / per-region / per-license-window) in a **new `@themis/likeness` library**. `@themis/identity` is governance-identity scope (DID, eligibility, Sybil resistance) and is the wrong home. Reciprocal tracker: `docs/domains/themis/deep-dive/specifications.md` § 11.8. _Owner: Themis._ 7. Aphrodite licensed-fighter likeness safety and revocation flow is implemented by `@aphrodite/performer-sovereignty` and `@aphrodite/performer-autonomy`, with `@v2/aphrodite-licensed-likeness-safety` enforcing Bellona cook blocks until the Themis `@themis/likeness` package lands. _Owner: Aphrodite._ 8. Maat live-service calendar shape for fighting-game live-ops (Crown Points, Pro Circuit calendar, balance ramp windows) is implemented by `@maat/strategy` and consumed through `@v2/maat-live-service-calendar`. _Owner: Maat._ 9. Kuanyin rage-quit / competitive-salt cascade class, distinct from generic toxicity. _Owner: Kuanyin._ 10. Shakti combat-sport ↔ fighting-game-ruleset bridge mapping real-sport biomechanics onto MK / SF / Tekken / SC / DJ ruleset frame-data is implemented by `@shakti/fighting-ruleset-bridge` and consumed through `@v2/shakti-ruleset-bridge`. The bridge emits off-rollback `V2BalanceImporter` CSV rows plus Sophia reference-card corpus entries, with explicit `game-only` cards for authored moves without real-sport antecedents. _Owner: Shakti._ 11. Substrate composition for Concordia-style flows until `libs/concordia/*` ships — anti-cheat appeals + tournament-result disputes + crew conflicts compose `@nous/cooperative-bargaining` + `@nous/preference-inference` + `@nous/agreement-search` + `@nous/concordia-sealed-memory` in `@v2/concordia-substrate`; the same surface wires `@iris/concordia-assistant` for consent-gated appellant / arbiter dialogue scaffolding with party-isolated prompt contexts and `@oshun/concordia-integration` for V2 → substrate event routing, nav descriptors, and redacted telemetry registration. The high-impact moderation path also wires `@kuanyin/concordia-restorative` for anti-cheat appeal restorative preflight with Kuanyin safety gates. External launch exposure is gated by `@oshun/config` through `ENABLE_V2_CONCORDIA_SUBSTRATE`, default disabled until launch readiness. _Owner: Nous + Iris + Oshun + Kuanyin + V2 service integration._ 12. Aje fan-token gating for crew / faction membership is composed by `@v2/aje-faction-governance` over `@aje/governance` (opt-in **and** per-platform cert-ban gate — Apple / PS5 / XSX / Switch2 may prohibit on-chain in-game items entirely; "opt-in" is insufficient on those platforms). _Owner: Aje._ 13. Themis Originality Shields launch — `@themis/music-shield`, `@themis/visual-shield`, `@themis/text-shield`, `@themis/video-shield`, `@themis/design-shield` feed `@v2/themis-originality-shields`. V2 UGC accept-gates block unless the required shield set passes. _Owner: Themis._ 14. EU AI Act conformity surface is implemented for the Adaptive AI Director: `@psyche/action-safety` emits classifier transparency and opt-out, `@v2/eu-ai-act-surface` composes the V2 contract, `@nous/safety` hosts the Model Card, and `@themis/accountability` records the AI-system-of-record. _Owner: Psyche + Nous + Themis._ 15. Regional content-rule engine for per-region gore variants: shared `@oshun/region-rules` owns CN / DE / AU / NZ / KR SKU cook profiles and consumes Aphrodite age / consent inputs. _Owner: Oshun platform + Aphrodite._ ### Privacy guard on cross-product entitlement Aphrodite is adult content; visible cross-product unlocks would create an outing risk, so Aphrodite community-status badges do not unlock V2 cosmetic / card-border / title grants by default. Cross-product entitlement claims from Aphrodite are **opt-in per individual grant**, with explicit out-of-context warning at grant time, and never surface implicitly via title / badge / lobby visibility. Cross-product entitlement from Lilith, Shakti, and Calliope may default-on under the `@oshun/identity` entitlement-claim API. The implemented `@v2/cross-product-entitlement` surface exposes `aphroditeImplicitLobbyTitleBadgeBlocked: true` so lobby, title, and badge surfaces cannot implicitly reveal Aphrodite activity. ### Event-name convention A canonical naming convention prevents the inconsistent emission patterns that surfaced in earlier drafts (`v2.match.*`, `v2.cosmetic.purchased`, `v2.cosmetic.requested`, `v2.dialogue.requested`). All V2 events on `@oshun/event-bus` follow this convention: - **Past-tense for emitted facts:** `v2.match.ended`, `v2.cosmetic.purchased`, `v2.player.reported`, `v2.mocap.captured`, `v2.replay.exported`, `v2.balance.dataset.published`. - **`.requested` suffix for command-style intent:** `v2.cosmetic.cook.requested`, `v2.stage.variant.requested`, `v2.dialogue.requested`, `v2.replay.export.requested`. These signal a job; the worker emits a paired past-tense event on completion (`v2.cosmetic.cook.completed` etc.). - **`v2..`:** subject is the entity touched (`match`, `cosmetic`, `player`, `mocap`, `dialogue`, `replay`, `stage`, `balance`); verb-tense is unambiguous past or `.requested`. - **Subscribed events from other domains keep their owner-prefixed names:** `hathor.dialogue.ready`, `isis.asset.cooked`, `maat.balance.recommendation`, `kuanyin.action.taken`, `themis.license.revoked`, `bellona.artifact.cooked`, `hathor.world.published`. ### Resolved decision ledger The third-pass adversarial review identified several items that needed explicit publisher / architecture decisions before agents could implement safely. They are now closed by ADRs and mirrored as checked decision tasks in `V2_TODOS.md` §1.6.19: | Decision | Accepted default | ADR | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Identity reconciliation | `@oshun/identity` is canonical; EOS is a linked platform/provider adapter. | `V2/docs/decisions/identity-reconciliation.md` | | Per-service SLOs | Three tiers: A critical regional, B product services, C queued/batch AI. | `V2/docs/decisions/slo-tier-per-service.md` | | AI inference cost | Text-first commentary with hard match/minute caps and local/preauthored failover. | `V2/docs/decisions/ai-inference-cost-model.md` | | Failure modes | Preserve match integrity first; disable nonessential online/UGC/AI surfaces safely. | `V2/docs/decisions/failure-mode-matrix.md` | | Sovereign core | Deterministic gameplay, replay input stream, save schema, and anti-cheat stay V2-local. | `V2/docs/decisions/sovereign-core-boundary.md` | | Neith integration | V2 owns P1 rollback and matchmaking adapters; Neith can be evaluated after §7. | `V2/docs/decisions/neith-integration-scope.md` | | Entitlement claims | Signed `@oshun/identity` claims via `@v2/cross-product-entitlement`; sensitive source products require per-grant opt-in. | `V2/docs/decisions/identity-entitlement-claim-api.md` | | Originality Shields | Public UGC publishing blocks until shields are available; private/local creation can ship. | `V2/docs/decisions/originality-shields-launch-gate.md` | | Regional content rules | Shared `@oshun/region-rules` cooks CN / DE / AU / NZ / KR gore variants and content cuts; Aphrodite supplies age / consent signals; missing regions use the China most-restrictive profile. | `V2/docs/decisions/regional-content-rules-owner.md` | | Platform cert bans | `V2/legal/platform-cert-bans.json` is the source of truth; deny risky features by default. | `V2/docs/decisions/platform-cert-ban-truth-table.md` | | Model cards | Cards live in `V2/docs/ai/model-cards/`; Nous owns runtime metadata, Themis owns audit export. | `V2/docs/decisions/model-card-hosting.md` | | `@nous/platform` | Model registry, deployment manifests, routing metadata, cost caps, and eval links. | `V2/docs/decisions/nous-platform-scope.md` | | Frame-data schema | V2 balance owns schema; `@v2/sophia-release-candidate-ingestion` sends the spreadsheet and patch-notes corpus through `@sophia/ingestion` on release-candidate cook. | `V2/docs/decisions/frame-data-spreadsheet-schema.md` | ### Missing V2 surfaces from the per-surface mapping The mapping table at the top of this section listed the major V2 surfaces, but several large V2 features added in later sections of `V2_features.md` and `V2_TODOS.md` were not mapped to ecosystem owners in the first pass. Filling the gap: | V2 surface (later sections) | Plausible owner(s) | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Racing component (§96-119) | `@v2/racing-ecosystem-bridge` over Galatea (kinematics + whole-body control) + Saraswati (EV powertrain) + Maya (open-world traversal + tracks) + Bellona/unreal | | Karaoke + rhythm-combat fusion (§132) | `@v2/karaoke-rhythm-combat-bridge` over Euterpe `genesis` + `accompany` + `protect` + Calliope `sound-design` + `@iris/voice` | | Mini-game suite — pinball, air hockey, mini-golf, darts, pool (§133) | `@v2/maya-minigame-suite-bridge` over Maya `games` projectile physics + Maya `physics` + Maya `scene` + Maya `client` input mapping; V2 plugins own game rules | | Cooking simulator mini-game (§133) | `@v2/hestia-cooking-minigame-bridge` over Hestia recipe intelligence, guided cooking, cooking education, ingredient database, and pantry sourcing | | World boss + community raid (§134) | `@v2/world-boss-community-raid-bridge` over Themis `community` (governance for community-shared HP rules + validation schema) + Maat `intelligence` (per-contribution aggregate) + Hathor `simulation` (world-state) + Kuanyin `community-harmony` (raid defense) | | Per-account vault + estate planning (§137 / per-account vault) | `@v2/per-account-vault-estate-bridge` over Lakshmi estate planning (`@lakshmi/estate`) + `@oshun/identity` account inheritance / delegation gates + Themis `transparency` transfer audit | | Photo Mode tournament + jury voting (§133) | `@v2/photo-mode-tournament-voting-bridge` over Themis `voting` (ranked-choice jury aggregation + approval voting) + Kuanyin `precognition` moderation pre-pass | | Tekken Bowl extension + arcade cabinets in Battle Hub (§133) | `@v2/tekken-bowl-arcade-cabinet-bridge` over Maya `games` `ProjectilePhysicsSystem` for the Tekken Bowl lane probe and Maya client ad-hoc per-cabinet plugin manifests for Battle Hub cabinet shells, coin gates, and leaderboards | | AI-generated commentary + match analysis (§135) | Already mapped (Iris + Calliope + Psyche) | | Real-world brand / celebrity guest / venue tie-ins (§136) | Already mapped (Themis NIL + Aje optional + Kuanyin performer-protection) | Each row above needs a corresponding subsection in `V2_TODOS.md` §1.6 before the related content cook starts. Reciprocal tasks land in the named domain's `DOMAINS//specifications.md`. The racing row is closed by `@v2/racing-ecosystem-bridge`: Galatea owns the vehicle-as-articulated-body driver/ragdoll probe, Saraswati owns hybrid / electric powertrain modeling, Maya owns deterministic terrain/urban traversal readiness, and Bellona/Unreal remains the cooked artifact path. The karaoke row is closed by `@v2/karaoke-rhythm-combat-bridge`: Euterpe genesis owns procedural backing tracks and the pitch/rhythm scoring source material, Euterpe accompany owns adaptive accompaniment analysis, Euterpe protect owns streamer-safe swap/originality checks, Calliope sound-design owns per-fighter theme variations, and Iris voice owns guide-voice speed/pitch directives. The bridge is cook-time only, off rollback, and rejects live rhythm-combat frame RPCs. The CI contract uses this exact guard phrase: rejects live rhythm-combat frame RPCs. The mini-game suite row is closed by `@v2/maya-minigame-suite-bridge`: Maya games projectile physics, Maya physics readiness, Maya scene readiness, and Maya input manifests are reused for pinball, air hockey, mini-golf, darts, and pool; V2 plugins retain per-game-specific authoring and runtime rules. The bridge is cook-time only, off rollback, and rejects live mini-game frame RPCs. The Tekken Bowl extension and Battle Hub arcade cabinet row is closed by `@v2/tekken-bowl-arcade-cabinet-bridge`: Maya games projectile primitives drive the Tekken Bowl 10-pin lane probe, Maya client ad-hoc plugins bind each cabinet to `v2.battle-hub.arcade-cabinet`, and V2 owns the cabinet shell, Fighter Coin gating, free-play exemptions, leaderboards, strike VFX, per-fighter bowling animations, themed alleys, and bowling-rank ladder. The bridge is cook-time only, off rollback, and rejects live Battle Hub frame RPCs. The cooking simulator row is closed by `@v2/hestia-cooking-minigame-bridge`: Hestia recipe intelligence (`@hestia/ai-ml`) selects candidate recipes, `@hestia/cooking` provides guided step parsing, `@hestia/education` provides walkthrough and virtual-kitchen simulation metadata, and `@hestia/ingredients` plus `@hestia/pantry` validate ingredient sourcing. The bridge emits the `hestia.recipe-as-mini-game-script` cook manifest for `V2Mode_Cooking`, stays off rollback, and rejects live cooking frame RPCs. ## Cross-References - Backlog: [`V2_TODOS.md`](./V2_TODOS.md) (see § "Oshun Integration Skeleton") - Product scope: [`V2_features.md`](./V2_features.md) - Dependencies: [`V2_DEPENDENCIES.md`](./V2_DEPENDENCIES.md) (see § "Oshun Domain Dependencies") - Ecosystem index: [`/DOMAINS.md`](../DOMAINS.md), [`/DOMAINS/README.md`](../docs/domains/README.md) - Bellona Unreal bridge: [`/docs/domains/bellona/deep-dive/features.md`](../docs/domains/bellona/deep-dive/features.md) - Hathor narrative & NPC AI: [`/docs/domains/hathor/deep-dive/specifications.md`](../docs/domains/hathor/deep-dive/specifications.md) - Iris in-match commentary contract: [`/docs/domains/iris/deep-dive/specifications.md`](../docs/domains/iris/deep-dive/specifications.md) - Shakti combat-sport ↔ ruleset bridge: [`/docs/domains/shakti/deep-dive/specifications.md`](../docs/domains/shakti/deep-dive/specifications.md) - Themis NIL / likeness ledger: [`/docs/domains/themis/deep-dive/specifications.md`](../docs/domains/themis/deep-dive/specifications.md) - Kuanyin rage-quit / salt class: [`/docs/domains/kuanyin/deep-dive/specifications.md`](../docs/domains/kuanyin/deep-dive/specifications.md) - Sister monorepo: [`/CLAUDE.md`](../CLAUDE.md), [`V1/features.md`](../V1/features.md)