add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/14-data-assets/115_DA_AdaptationRule.md
+++ b/docs/blueprints/14-data-assets/115_DA_AdaptationRule.md
@@ -0,0 +1,53 @@
+# DA_AdaptationRule — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_DifficultyManager`](../10-adaptive/62_BPC_DifficultyManager.md)
+**Purpose:** Defines adaptation rules for dynamic difficulty adjustment — thresholds, modifiers, and response curves.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `RuleTag` | `FGameplayTag` | Unique rule identifier |
+| `AdaptationDomain` | `EAdaptationDomain` | EnemyCount, EnemyAggression, ResourceScarcity, EnvironmentalHazard |
+| `ThresholdCheck` | `EThresholdType` | PlayerDeathCount, ClearTime, HealthLost, AmmoUsed |
+| `ThresholdValue` | `float` | Trigger value for adaptation |
+| `ModifierCurve` | `UCurveFloat*` | Response curve for modifier scaling |
+| `ResponseMultiplier` | `float` | Base modifier strength |
+| `MaxModifier` | `float` | Cap on total modifier |
+| `CooldownMinutes` | `float` | Min time between adaptations |
+| `bCanRevert` | `bool` | Adaptation can reverse |
+
+---
+
+## Gameplay Tags
+- Namespace: `Adaptation.<Domain>.<Rule>` (e.g., `Adaptation.EnemyCount.IncreaseOnLowDeaths`)
+
+---
+
+## Validation Rules
+- `RuleTag` must be unique
+- `ModifierCurve` must be valid
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| RuleTag | `Adaptation.EnemyAggression.IncreaseOnSpeed` |
+| AdaptationDomain | EnemyAggression |
+| ThresholdCheck | ClearTime |
+| ThresholdValue | 300.0 |
+| ResponseMultiplier | 1.5 |
+
+---
+
+## Consumed By
+- [`BPC_DifficultyManager`](../10-adaptive/62_BPC_DifficultyManager.md)
+
+## Reuse Notes
+- Rules are composable — multiple rules apply simultaneously
+- Curves allow non-linear adaptation responses
--- a/docs/blueprints/14-data-assets/116_DA_AtmosphereProfile.md
+++ b/docs/blueprints/14-data-assets/116_DA_AtmosphereProfile.md
@@ -0,0 +1,54 @@
+# DA_AtmosphereProfile — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_AtmosphereStateController`](../10-adaptive/BPC_AtmosphereStateController.md)
+**Purpose:** Defines an atmosphere preset — lighting key, audio ambience, VFX, and intensity — for the atmosphere controller.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ProfileTag` | `FGameplayTag` | Unique atmosphere preset identifier |
+| `AtmosphereState` | `EAtmosphereState` | Exploration, Suspense, Combat, Panic, etc. |
+| `LightingKey` | `FName` | Lighting preset key for LightEventController |
+| `AudioAmbienceKey` | `FName` | Audio preset key for AudioAtmosphereController |
+| `VFXPresetKey` | `FName` | VFX preset key |
+| `Intensity` | `float` | Global intensity bias (0.0-1.0) |
+| `TransitionTime` | `float` | Seconds for crossfade to this profile |
+| `bLoops` | `bool` | Whether this profile loops indefinitely |
+| `Priority` | `int32` | Higher priority overrides lower |
+
+---
+
+## Gameplay Tags
+- Namespace: `Atmosphere.<State>` (e.g., `Atmosphere.Combat`, `Atmosphere.Panic`)
+
+---
+
+## Validation Rules
+- `ProfileTag` must be unique
+- `Intensity` must be 0.0-1.0
+- `TransitionTime` must be > 0
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| ProfileTag | `Atmosphere.Combat.Intense` |
+| AtmosphereState | Combat |
+| LightingKey | `Lighting.Combat.RedAlert` |
+| AudioAmbienceKey | `Audio.Combat.HighTension` |
+| Intensity | 0.9 |
+
+---
+
+## Consumed By
+- [`BPC_AtmosphereStateController`](../10-adaptive/BPC_AtmosphereStateController.md)
+
+## Reuse Notes
+- All preset data is keyed by FName for extensibility
+- Profiles support full crossfade blending via TransitionTime
--- a/docs/blueprints/14-data-assets/117_DA_BehaviourVariant.md
+++ b/docs/blueprints/14-data-assets/117_DA_BehaviourVariant.md
@@ -0,0 +1,54 @@
+# DA_BehaviourVariant — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_BehaviourVariantSelector`](../09-ai/)
+**Purpose:** Defines AI behaviour variants — patrol patterns, aggression levels, flee thresholds, and combat tactics.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `VariantTag` | `FGameplayTag` | Unique behaviour variant identifier |
+| `AggressionLevel` | `float` | 0.0 (passive) to 1.0 (hyper-aggressive) |
+| `FleeHealthThreshold` | `float` | Health % below which AI flees |
+| `CombatTactic` | `ECombatTactic` | Flank, Rush, Ambush, Ranged, HitAndRun |
+| `PatrolSpeed` | `float` | Walk speed during patrol (cm/s) |
+| `ChaseSpeed` | `float` | Run speed during chase |
+| `DetectionModifier` | `float` | Multiplier for perception ranges |
+| `ReinforcementCallRadius` | `float` | Distance to call nearby allies |
+| `bCanUseCover` | `bool` | AI can use cover points |
+| `PreferredWeaponType` | `EWeaponType` | Melee, Ranged, Throwable |
+
+---
+
+## Gameplay Tags
+- Namespace: `Behaviour.<Type>` (e.g., `Behaviour.Aggressive`, `Behaviour.Stealthy`)
+
+---
+
+## Validation Rules
+- `VariantTag` must be unique
+- `AggressionLevel` must be 0.0-1.0
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| VariantTag | `Behaviour.Aggressive.Hunter` |
+| AggressionLevel | 0.8 |
+| FleeHealthThreshold | 0.15 |
+| CombatTactic | Flank |
+
+---
+
+## Consumed By
+- [`BPC_BehaviourVariantSelector`](../09-ai/)
+- [`AI_BaseAgentController`](../09-ai/AI_BaseAgentController.md)
+
+## Reuse Notes
+- Behaviour variants are data-driven; new tactics added without code
+- Variant selection is influenced by difficulty, fear, and narrative state
--- a/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md
+++ b/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md
@@ -0,0 +1,54 @@
+# DA_DataAssetArchitecture — Data Asset Architecture Overview
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** All consuming systems
+**Purpose:** Overview of all 20 Data Asset types in the framework, naming conventions, and dependency rules.
+
+---
+
+## Architecture
+
+The Modular Game Framework uses `UDataAsset` (and subclass `UPrimaryDataAsset` where persistent identifiers are needed) as the primary authoring format for designer-facing content. Each DA type covers one content domain: weapons, AI profiles, atmosphere presets, narrative data, encounter definitions, etc.
+
+### Conventions
+- **Naming:** `DA_<Domain><Subtype>` — e.g., `DA_WeaponData`, `DA_AIProfile`, `DA_AtmosphereProfile`
+- **Storage:** All DA files live in `Content/DataAssets/<Domain>/` in-engine
+- **Loading:** Use `UAssetManager` with `FPrimaryAssetType` and `FPrimaryAssetId` for async loading
+- **Validation:** Each DA implements `ValidateData()` for editor-time data integrity checks
+- **Gameplay Tags:** All DAs carry a `FGameplayTagContainer` for query and filtering
+
+### Dependency Rules
+1. DAs reference other DAs by `FPrimaryAssetId` or `TSoftObjectPtr`, never by hard pointer
+2. No DA may reference a runtime system; only other DAs
+3. Circular DA references are prohibited — use `World Context Object` for runtime resolution
+4. All DA types are registered in `DefaultGame.ini` under `[/Script/Engine.AssetManagerSettings]`
+
+### Registered DA Types (Section 13 of Master)
+
+| # | DA Type | Domain | Consumed By |
+|---|---------|--------|-------------|
+| 1 | `DA_ItemData` | Items | `BPC_InventorySystem` |
+| 2 | `DA_WeaponData` | Weapons | `BPC_FirearmSystem`, `BPC_MeleeSystem` |
+| 3 | `DA_AmmoData` | Weapons | `BPC_AmmoComponent` |
+| 4 | `DA_AIProfile` | AI | `AI_BaseAgentController` |
+| 5 | `DA_NarrativeData` | Narrative | `BPC_NarrativeStateSystem` |
+| 6 | `DA_EndingData` | Narrative | `BPC_EndingAccumulator` |
+| 7 | `DA_InteractionData` | Interaction | `BPC_InteractionDetector` |
+| 8 | `DA_ObjectiveData` | Narrative/UI | `BPC_ObjectiveSystem`, `WBP_ObjectiveDisplay` |
+| 9 | `DA_EncounterData` | Adaptive | `BPC_ProceduralEncounter` |
+| 10 | `DA_AtmosphereProfile` | Adaptive | `BPC_AtmosphereStateController` |
+| 11 | `DA_ScareEvent` | Adaptive | `BPC_ScareEventSystem` |
+| 12 | `DA_RoomMutation` | Adaptive | `BPC_AdaptiveEnvironmentDirector` |
+| 13 | `DA_BehaviourVariant` | AI | `BPC_BehaviourVariantSelector` |
+| 14 | `DA_HapticProfile` | Settings | `BPC_HapticsController` |
+| 15 | `DA_AdaptationRule` | Adaptive | `BPC_DifficultyManager` |
+| 16 | `DA_EquipmentConfig` | Inventory | `BPC_EquipmentSlotSystem` |
+| 17 | `DA_PuzzleData` | Interaction | `BP_PuzzleDeviceActor` |
+| 18 | `DA_RareEvent` | Adaptive | `BPC_RareEventSystem` |
+| 19 | `DA_LevelConfig` | Core | `GM_CoreGameMode` |
+| 20 | `DA_AudioSettings` | Audio | `SS_AudioManager` (132) — replaces deprecated `DA_AudioPresets` |
+
+### Reuse Notes
+- This overview serves as a registry — all DA types referenced in any system must appear here
+- New DA types require registration in DefaultGame.ini AND this document
+- All individual DA spec files are in `docs/blueprints/14-data-assets/`
--- a/docs/blueprints/14-data-assets/119_DA_EncounterData.md
+++ b/docs/blueprints/14-data-assets/119_DA_EncounterData.md
@@ -0,0 +1,61 @@
+# DA_EncounterData — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_ProceduralEncounter`](../10-adaptive/70_BPC_ProceduralEncounter.md)
+**Purpose:** Defines procedural encounter configurations — enemy types, spawn rules, difficulty scaling, and encounter triggers.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `EncounterTag` | `FGameplayTag` | Unique encounter identifier |
+| `EnemyArchetypes` | `TArray<FPrimaryAssetId>` | Allowed enemy DA_AIProfile references |
+| `MinEnemies` | `int32` | Minimum spawn count |
+| `MaxEnemies` | `int32` | Maximum spawn count |
+| `SpawnRadius` | `float` | Radius around trigger point (cm) |
+| `SpawnDelay` | `float` | Time between individual spawns |
+| `bTriggerOnOverlap` | `bool` | Auto-trigger on player overlap |
+| `bTriggerOnAlert` | `bool` | Trigger when alert level reaches threshold |
+| `RequiredAlertLevel` | `float` | Alert threshold (0.0-1.0) |
+| `EncounterCooldown` | `float` | Min time between encounters |
+| `DifficultyScaling` | `UCurveFloat*` | Curve for scaling enemy count/strength by difficulty |
+| `NarrativePrerequisites` | `TArray<FGameplayTag>` | Narrative flags required |
+
+---
+
+## Gameplay Tags
+- Namespace: `Encounter.<Type>.<Name>` (e.g., `Encounter.Ambush.Hallway`, `Encounter.Siege.Room`)
+
+---
+
+## Validation Rules
+- `MinEnemies` must be >= 1
+- `MaxEnemies` must be >= `MinEnemies`
+- At least one `EnemyArchetype` required
+- `SpawnRadius` must be > 0
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| EncounterTag | `Encounter.Ambush.DarkCorridor` |
+| EnemyArchetypes | `[DA_AIProfile_Crawler, DA_AIProfile_Stalker]` |
+| MinEnemies | 2 |
+| MaxEnemies | 5 |
+| SpawnRadius | 800.0 |
+| bTriggerOnOverlap | true |
+
+---
+
+## Consumed By
+- [`BPC_ProceduralEncounter`](../10-adaptive/70_BPC_ProceduralEncounter.md)
+- [`BPC_DifficultyManager`](../10-adaptive/62_BPC_DifficultyManager.md)
+
+## Reuse Notes
+- Encounter data is completely data-driven; spawning logic reads from this DA
+- DifficultyScaling curve allows non-linear difficulty adjustment
+- Narrative prerequisites gate encounters behind story progression
--- a/docs/blueprints/14-data-assets/120_DA_EquipmentConfig.md
+++ b/docs/blueprints/14-data-assets/120_DA_EquipmentConfig.md
@@ -0,0 +1,48 @@
+# DA_EquipmentConfig — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_EquipmentSlotSystem`](../04-inventory/BPC_EquipmentSlotSystem.md)
+**Purpose:** Defines equipment slot configurations — which item categories map to which slots, socket names, and auto-equip rules.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Slot` | `E_EquipmentSlot` | Equipment slot identifier |
+| `SocketName` | `FName` | Character skeletal mesh socket |
+| `AllowedCategories` | `TArray<E_ItemCategory>` | Categories allowed in this slot |
+| `bAutoEquipOnPickup` | `bool` | Auto-equip matching items on pickup |
+| `bMustBeEmptyToEquip` | `bool` | Slot must be empty before equipping |
+| `VisualAttachmentClass` | `TSubclassOf<AActor>` | Visual attachment actor class |
+
+---
+
+## Gameplay Tags
+- Namespace: `Equipment.Slot.<Name>` (e.g., `Equipment.Slot.Head`, `Equipment.Slot.Torso`)
+
+---
+
+## Validation Rules
+- `Slot` must be unique
+- `SocketName` must not be empty if visual attachment is used
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| Slot | Head |
+| SocketName | `head_socket` |
+| AllowedCategories | `[Equipment]` |
+| bAutoEquipOnPickup | true |
+
+---
+
+## Consumed By
+- [`BPC_EquipmentSlotSystem`](../04-inventory/BPC_EquipmentSlotSystem.md)
+
+## Reuse Notes
+- Equipment configs are data-driven; new slots added without code changes
--- a/docs/blueprints/14-data-assets/121_DA_HapticProfile.md
+++ b/docs/blueprints/14-data-assets/121_DA_HapticProfile.md
@@ -0,0 +1,52 @@
+# DA_HapticProfile — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_HapticsController`](../12-settings/)
+**Purpose:** Defines haptic feedback profiles for controller vibration and force feedback effects tied to gameplay events.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ProfileTag` | `FGameplayTag` | Unique haptic profile identifier |
+| `EventType` | `EHapticEvent` | Damage, Heartbeat, Explosion, Footstep, WeaponFire, AmbientPulse |
+| `IntensityCurve` | `UCurveFloat*` | Vibration intensity over time |
+| `Duration` | `float` | Total haptic effect duration (seconds) |
+| `MotorMask` | `EHapticMotor` | Left, Right, Both |
+| `Priority` | `int32` | Higher priority overrides lower during conflicts |
+| `bCanInterrupt` | `bool` | Can this effect be interrupted by higher priority |
+| `PlatformMinIntensity` | `float` | Minimum intensity per platform capability |
+
+---
+
+## Gameplay Tags
+- Namespace: `Haptic.<Event>` (e.g., `Haptic.Damage.Heavy`, `Haptic.Heartbeat`)
+
+---
+
+## Validation Rules
+- `ProfileTag` must be unique
+- `Duration` must be > 0
+- `IntensityCurve` must be valid
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| ProfileTag | `Haptic.Damage.Critical` |
+| EventType | Damage |
+| Duration | 0.5 |
+| MotorMask | Both |
+| Priority | 10 |
+
+---
+
+## Consumed By
+- [`BPC_HapticsController`](../12-settings/)
+
+## Reuse Notes
+- Haptic profiles are platform-agnostic; translation handled by PlatformServiceAbstraction
--- a/docs/blueprints/14-data-assets/122_DA_InteractionData.md
+++ b/docs/blueprints/14-data-assets/122_DA_InteractionData.md
@@ -0,0 +1,73 @@
+# DA_InteractionData — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** `BPC_InteractionDetector`, `I_Interactable`
+**Purpose:** Defines interaction properties for interactable world objects — prompt text, hold duration, required items, and context tags.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `InteractionTag` | `FGameplayTag` | Unique tag for this interaction type |
+| `ActionLabel` | `FText` | "Open", "Pick Up", "Pull Lever", etc. |
+| `ObjectName` | `FText` | Display name of the object |
+| `bRequiresHold` | `bool` | Whether interaction requires hold input |
+| `HoldDuration` | `float` | Seconds to hold (if bRequiresHold) |
+| `ActionKeyIcon` | `UTexture2D*` | Platform-specific input icon |
+| `ContextTags` | `TArray<FText>` | Display tags: "Safe", "Locked", "Dangerous" |
+| `bConsumeOnInteract` | `bool` | Item is consumed after interaction |
+| `InteractionCooldown` | `float` | Seconds before re-interaction allowed |
+| `RequiredItemTag` | `FGameplayTag` | Item required in inventory to interact |
+| `bBlockDuringCombat` | `bool` | Interaction blocked during combat |
+| `InteractionRange` | `float` | Max distance for interaction (cm) |
+| `PromptOffset` | `FVector2D` | Screen offset for prompt widget |
+
+---
+
+## Gameplay Tags
+- Namespace: `Interaction.<Type>` (e.g., `Interaction.Open`, `Interaction.Pickup`)
+- Required item tags in `Item.<Category>` namespace
+
+---
+
+## Validation Rules
+- `ActionLabel` must not be empty
+- `HoldDuration` > 0 if `bRequiresHold` is true
+- `InteractionTag` must be unique across all interaction DAs
+- `InteractionRange` must be > 0
+
+---
+
+## Example Data
+
+**Example 1: Door**
+| Field | Value |
+|-------|-------|
+| InteractionTag | `Interaction.Door.Open` |
+| ActionLabel | "Open" |
+| ObjectName | "Wooden Door" |
+| bRequiresHold | false |
+| InteractionRange | 200.0 |
+
+**Example 2: Locked Chest**
+| Field | Value |
+|-------|-------|
+| InteractionTag | `Interaction.Chest.Locked` |
+| ActionLabel | "Unlock" |
+| ObjectName | "Iron Chest" |
+| bRequiresHold | true |
+| HoldDuration | 1.5 |
+| RequiredItemTag | `Item.Key.IronKey` |
+
+---
+
+## Consumed By
+- [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) — reads interaction data for prompt display
+- [`BP_DoorActor`](../03-interaction/BP_DoorActor.md) — door-specific interaction config
+- [`BP_PuzzleDeviceActor`](../03-interaction/) — puzzle interaction definitions
+
+## Reuse Notes
+- All interactable objects reference this DA via a `TSoftObjectPtr` on their component
+- Context tags drive HUD prompt coloring and iconography
--- a/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md
+++ b/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md
@@ -0,0 +1,58 @@
+# DA_ObjectiveData — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_ObjectiveSystem`](../07-narrative/39_BPC_ObjectiveSystem.md), [`WBP_ObjectiveDisplay`](../06-ui/WBP_ObjectiveDisplay.md)
+**Purpose:** Defines objective content — objective text, requirements, completion conditions, linked narrative flags, and reward data.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ObjectiveTag` | `FGameplayTag` | Unique tag for this objective |
+| `ObjectiveText` | `FText` | Display text for HUD/journal |
+| `ObjectiveCategory` | `EObjectiveCategory` | Main, Side, Hidden, Tutorial |
+| `PrerequisiteFlags` | `TArray<FGameplayTag>` | Narrative flags required before objective activates |
+| `CompletionFlags` | `TArray<FGameplayTag>` | Flags set when objective completes |
+| `bIsOptional` | `bool` | Objective can be skipped |
+| `ObjectiveLocation` | `FVector` | World location for marker |
+| `RewardItems` | `TArray<FPrimaryAssetId>` | Items granted on completion |
+| `RewardExperience` | `int32` | XP awarded |
+| `LinkedEndingWeight` | `float` | Score contribution to ending evaluation |
+
+---
+
+## Gameplay Tags
+- Namespace: `Objective.<Category>.<Name>` (e.g., `Objective.Main.FindKey`, `Objective.Side.RescueNPC`)
+
+---
+
+## Validation Rules
+- `ObjectiveTag` must be unique
+- `ObjectiveText` must not be empty
+- At least one `CompletionFlag` required (unless narrative-driven)
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| ObjectiveTag | `Objective.Main.EscapeHospital` |
+| ObjectiveText | "Escape the abandoned hospital" |
+| ObjectiveCategory | Main |
+| CompletionFlags | `Narrative.EscapedHospital` |
+| RewardExperience | 500 |
+
+---
+
+## Consumed By
+- [`BPC_ObjectiveSystem`](../07-narrative/39_BPC_ObjectiveSystem.md)
+- [`WBP_ObjectiveDisplay`](../06-ui/WBP_ObjectiveDisplay.md)
+- [`BPC_EndingAccumulator`](../07-narrative/BPC_EndingAccumulator.md)
+
+## Reuse Notes
+- Objectives are data-driven; no blueprint logic changes needed for new objectives
+- `PrerequisiteFlags` gate objective activation behind narrative flags
+- `LinkedEndingWeight` feeds into ending evaluation system
--- a/docs/blueprints/14-data-assets/124_DA_PuzzleData.md
+++ b/docs/blueprints/14-data-assets/124_DA_PuzzleData.md
@@ -0,0 +1,162 @@
+# DA_PuzzleData — Puzzle Data Asset
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UPrimaryDataAsset`
+
+### Dependencies
+- **Requires:** GameplayTags — PuzzleTag, OnSolveFlag, OnFailFlag
+- **Required By:** [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) — Reads puzzle solution data at runtime
+- **Required By:** [`BPC_NarrativeStateSystem`](../07-narrative/38_BPC_NarrativeStateSystem.md) — OnSolveFlag/OnFailFlag set as narrative flags
+- **Engine/Plugin Requirements:** GameplayTags
+
+### Purpose
+Defines a puzzle's solution, constraints, and outcome flags. Each puzzle in the game has a corresponding DA_PuzzleData asset that the [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) reads at runtime. The solution, attempt limits, time limits, and narrative flag consequences are all data-driven — no puzzle logic is hardcoded.
+
+---
+
+## 1. Enums
+
+*No enums defined. Uses GameplayTags for all outcome and condition flags.*
+
+---
+
+## 2. Structs
+
+### `S_PuzzleSolution`
+| Field | Type | Description |
+|-------|------|-------------|
+| `SolutionType` | E_PuzzleInputType | How the solution is structured (Sequence, Combination, Timing, Pattern, ToggleSet) |
+| `SequenceEntries` | Array of Integer | For sequence-type puzzles: the correct order of inputs |
+| `CombinationValues` | Array of Name | For combination-type puzzles: correct values per input |
+| `PatternTimings` | Array of Float | For timing/pattern puzzles: expected input timings |
+| `ToggleTargets` | Array of GameplayTag | For toggle puzzles: which toggles must be ON |
+| `Tolerance` | Float | Acceptable deviation (for timing puzzles) |
+
+### `S_PuzzleConfig`
+| Field | Type | Description |
+|-------|------|-------------|
+| `PuzzleTag` | GameplayTag | Unique identifier for this puzzle |
+| `PuzzleType` | E_PuzzleType | Logical puzzle category |
+| `Solution` | S_PuzzleSolution | The correct solution definition |
+| `MaxAttempts` | Integer | Maximum allowed attempts (0 = unlimited) |
+| `TimeLimit` | Float | Time limit in seconds (0 = unlimited) |
+| `OnSolveFlag` | GameplayTag | Narrative flag set when puzzle is solved |
+| `OnFailFlag` | GameplayTag | Narrative flag set when puzzle fails permanently |
+| `bResettable` | Bool | Whether the puzzle can be retried after failure |
+| `ResetDelay` | Float | Seconds before puzzle resets after failure |
+| `RequiredFlag` | GameplayTag | Narrative flag required to interact with puzzle |
+| `FailPenalty` | E_PuzzleFailPenalty | What happens on failure (None, Damage, Stress, Trapped, SpawnEnemy) |
+| `FailPenaltyValue` | Float | Magnitude of fail penalty (damage amount, stress amount) |
+
+---
+
+## 3. Variables
+
+### Data Asset Fields
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `PuzzleTag` | GameplayTag | — | Identity | Unique puzzle identifier |
+| `PuzzleType` | E_PuzzleType | Sequence | Solution | Logical puzzle category |
+| `DisplayName` | FText | — | Presentation | Puzzle name shown to player |
+| `PromptText` | FText | — | Presentation | Interaction prompt text |
+| `SolutionSequence` | Array of Integer | Empty | Solution | Correct input sequence |
+| `CombinationValues` | Array of Name | Empty | Solution | Correct combination values |
+| `MaxAttempts` | Integer | 3 | Constraints | Max wrong attempts before permanent fail |
+| `TimeLimit` | Float | 0.0 | Constraints | Time limit in seconds (0=unlimited) |
+| `OnSolveFlag` | GameplayTag | — | Consequences | Narrative flag set on solve |
+| `OnFailFlag` | GameplayTag | — | Consequences | Narrative flag set on permanent fail |
+| `bResettable` | Bool | True | Config | Can retry after failure |
+| `ResetDelay` | Float | 2.0 | Config | Seconds before reset |
+| `RequiredFlag` | GameplayTag | — | Conditions | Flag required to interact |
+| `FailPenalty` | E_PuzzleFailPenalty | None | Consequences | Effect on failure |
+| `FailPenaltyValue` | Float | 0.0 | Consequences | Magnitude of penalty effect |
+| `AvailableInputs` | Array of Integer | Empty | UI | Valid input values shown to player |
+| `bShowSolutionProgress` | Bool | True | UI | Show partial progress during attempt |
+
+---
+
+## 4. Enums (Puzzle System)
+
+```text
+Enum Name: E_PuzzleType
+(DisplayName = "Puzzle Type")
+
+Values:
+  Sequence       = 0    // Input a specific sequence of buttons/actions
+  Combination    = 1    // Enter a correct combination/code
+  Timing         = 2    // Match a rhythm or timing pattern
+  ToggleSet      = 3    // Set a group of toggles to correct positions
+  PatternMatch   = 4    // Match a displayed pattern
+```
+
+```text
+Enum Name: E_PuzzleInputType
+(DisplayName = "Puzzle Input Type")
+
+Values:
+  Sequence       = 0    // Ordered inputs
+  Combination    = 1    // Named value inputs
+  Timing         = 2    // Time-based inputs
+  Pattern        = 3    // Position/pattern inputs
+  ToggleSet      = 4    // Boolean toggle inputs
+```
+
+```text
+Enum Name: E_PuzzleFailPenalty
+(DisplayName = "Puzzle Fail Penalty")
+
+Values:
+  None           = 0    // No penalty
+  Damage         = 1    // Deal damage to player
+  Stress         = 2    // Increase stress
+  Trapped        = 3    // Trigger environmental trap
+  SpawnEnemy     = 4    // Spawn enemy encounter
+  LockPermanent  = 5    // Permanently lock puzzle
+```
+
+---
+
+## 5. Functions
+
+*Data asset only. No runtime functions. Data is read by [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) at runtime.*
+
+---
+
+## 6. Event Dispatchers
+
+*Data asset only. No event dispatchers.*
+
+---
+
+## 7. Validation / Testing Checklist
+
+- [ ] PuzzleTag is unique and valid GameplayTag
+- [ ] SolutionSequence/CombinationValues matches PuzzleType
+- [ ] OnSolveFlag and OnFailFlag are valid GameplayTags
+- [ ] MaxAttempts of 0 = unlimited attempts
+- [ ] TimeLimit of 0 = no time pressure
+- [ ] FailPenalty matches game systems (Damage targets BPC_HealthSystem, Stress targets BPC_StressSystem)
+- [ ] RequiredFlag correctly gates puzzle interaction
+- [ ] Edge case: all puzzles solved → narrative state reflects all OnSolveFlags
+- [ ] Edge case: permanent fail with no fail flag → puzzle locks silently
+- [ ] Edge case: resettable with ResetDelay of 0 → immediate reset
+
+---
+
+## 8. Reuse Notes
+
+- One DA_PuzzleData per puzzle in the game
+- PuzzleType determines how BP_PuzzleDeviceActor processes input
+- E_PuzzleInputType tells the puzzle device what input mechanism to use (buttons, text, timing, toggles)
+- FailPenalty allows puzzles to have real stakes without scripting per puzzle
+- Extend S_PuzzleSolution with new solution types per project
+- For non-puzzle games, leave this data asset unused
+
+---
+
+*Specification based on Master Section 13, line 3420.*
--- a/docs/blueprints/14-data-assets/125_DA_RareEvent.md
+++ b/docs/blueprints/14-data-assets/125_DA_RareEvent.md
@@ -0,0 +1,138 @@
+# DA_RareEvent — Rare Event Data Asset
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UPrimaryDataAsset`
+
+### Dependencies
+- **Requires:** GameplayTags — EventTag, EventConditions, EventActions
+- **Required By:** [`BPC_RareEventSystem`](../10-adaptive/BPC_RareEventSystem.md) — Reads rare event pool at runtime, rolls probability, fires events
+- **Engine/Plugin Requirements:** GameplayTags
+
+### Purpose
+Defines a single rare world event that can occur with limited probability during gameplay. Each rare event asset specifies its unique tag, probability of occurrence, eligibility conditions, resulting actions, and whether it can fire only once per session.
+
+---
+
+## 1. Enums
+
+```text
+Enum Name: E_RareEventActionType
+(DisplayName = "Rare Event Action Type")
+
+Values:
+  PlayAudio              = 0    // Play a one-shot sound or stinger
+  SpawnActor             = 1    // Spawn a visual/hallucination actor
+  TriggerScreenEffect    = 2    // Trigger a screen effect (vignette, flash)
+  SetNarrativeFlag       = 3    // Set a narrative flag
+  TriggerDialogue        = 4    // Play a dialogue line or sequence
+  ModifyAtmosphere       = 5    // Temporarily change atmosphere state
+  SpawnCollectible       = 6    // Spawn a hidden collectible
+  DisplayMessage         = 7    // Show a subtitle/message to player
+  ModifyLighting         = 8    // Change room lighting temporarily
+  TeleportEntity         = 9    // Teleport an entity near player briefly
+```
+
+---
+
+## 2. Structs
+
+### `S_RareEventAction`
+| Field | Type | Description |
+|-------|------|-------------|
+| `ActionType` | E_RareEventActionType | What kind of action to perform |
+| `ActionTag` | GameplayTag | Action-specific identifier (audio cue, actor class, effect tag) |
+| `ActionValue` | Float | Numeric parameter (duration, intensity, volume) |
+| `Delay` | Float | Seconds to wait before executing this action |
+
+---
+
+## 3. Variables
+
+### Data Asset Fields
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `EventTag` | GameplayTag | — | Identity | Unique identifier for this rare event |
+| `DisplayName` | FText | — | Editor | Human-readable name for designers |
+| `Probability` | Float | 0.01 | Core | Chance of occurring on each roll (0.0–1.0) |
+| `EventConditions` | Array of GameplayTag | Empty | Conditions | Narrative flags required for event to be eligible |
+| `ForbiddenConditions` | Array of GameplayTag | Empty | Conditions | Narrative flags that block the event if set |
+| `EventActions` | Array of S_RareEventAction | Empty | Actions | Sequence of actions executed when event fires |
+| `bOncePerSession` | Bool | True | Core | If true, event fires at most once per game session |
+| `bOncePerSaveFile` | Bool | False | Core | If true, event fires at most once per save file lifetime |
+| `bBlockOtherEvents` | Bool | False | Core | No other rare events can fire during this event's action sequence |
+| `RequiredPlaystyleTag` | GameplayTag | — | Conditions | Player must have this playstyle for eligibility |
+| `RequiredChapterTag` | GameplayTag | — | Conditions | Current chapter must match for eligibility |
+| `MinSessionTime` | Float | 0.0 | Conditions | Minimum session elapsed time before eligible |
+| `MinDeathCount` | Integer | 0 | Conditions | Minimum player deaths before eligible |
+| `MaxOccurrences` | Integer | 1 | Limits | Maximum times event can occur (overrides bOncePerSession) |
+| `CooldownAfterFire` | Float | 0.0 | Limits | Cooldown in seconds before this event is eligible again |
+| `Priority` | Integer | 0 | Core | Priority over other events when multiple are eligible (higher = first) |
+
+---
+
+## 4. Functions
+
+*Data asset only. No runtime functions. Data is read by [`BPC_RareEventSystem`](../10-adaptive/BPC_RareEventSystem.md) at runtime.*
+
+---
+
+## 5. Event Dispatchers
+
+*Data asset only. No event dispatchers.*
+
+---
+
+## 6. Validation / Testing Checklist
+
+- [ ] EventTag is unique and valid GameplayTag
+- [ ] Probability is in range 0.0–1.0 (0.001 = 0.1%, 0.01 = 1%, 0.1 = 10%)
+- [ ] EventConditions tags exist in GI_GameTagRegistry
+- [ ] EventActions array has at least one action
+- [ ] S_RareEventAction.ActionType matches the data needed (audio uses ActionTag for cue, spawn uses ActionTag for actor class)
+- [ ] bOncePerSession and bOncePerSaveFile properly gated (don't set both unless intended)
+- [ ] Priority values correctly order competing events
+- [ ] Edge case: Probability of 0.0 = never fires randomly (scripted only)
+- [ ] Edge case: Probability of 1.0 = always fires when eligible
+- [ ] Edge case: empty EventConditions = always eligible
+- [ ] Edge case: CooldownAfterFire of 0 = no cooldown (only gated by bOncePerSession/MaxOccurrences)
+
+---
+
+## 7. Example Data Row
+
+| Field | Value | Note |
+|-------|-------|------|
+| `EventTag` | `RareEvent.Hallucination.CorridorGhost` | Unique identifier |
+| `DisplayName` | "Corridor Ghost Sighting" | Designer reference name |
+| `Probability` | 0.005 | 0.5% chance per roll |
+| `EventConditions` | [Narrative.Phase.Ch2, Player.Stress.High] | Only in chapter 2 when stress is high |
+| `ForbiddenConditions` | [Narrative.Flag.SeenGhost] | Doesn't repeat if already seen |
+| `EventActions` | [SpawnActor(GhostMesh, 0.5, 0.0), TriggerScreenEffect(Flash, 0.3, 0.5), PlayAudio(GhostWhisper, 0.8, 1.0)] | Three sequential actions |
+| `bOncePerSession` | True | Don't repeat |
+| `bOncePerSaveFile` | False | Can appear in different save files |
+| `RequiredPlaystyleTag` | Cautious | Prefer scaring cautious players |
+| `RequiredChapterTag` | Narrative.Phase.Ch2 | Only in chapter 2 |
+| `MinSessionTime` | 600.0 | At least 10 minutes played |
+| `MinDeathCount` | 2 | Player must have died at least twice |
+| `Priority` | 5 | Higher than ambient events, lower than story reveals |
+
+---
+
+## 8. Reuse Notes
+
+- One DA_RareEvent per rare world occurrence
+- Probability values should be very low (0.001–0.05) for true "rare" feel
+- EventActions array supports complex multi-step sequences with delays
+- bBlockOtherEvents prevents simultaneous rare events from stacking
+- For non-horror games, use rare events for easter eggs and hidden content instead of scares
+- Extend E_RareEventActionType with new action types per project
+- CooldownAfterFire allows events to repeat within a session without being once-only
+
+---
+
+*Specification based on Master Section 13, line 3422.*
--- a/docs/blueprints/14-data-assets/126_DA_RoomMutation.md
+++ b/docs/blueprints/14-data-assets/126_DA_RoomMutation.md
@@ -0,0 +1,48 @@
+# DA_RoomMutation — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_AdaptiveEnvironmentDirector`](../10-adaptive/)
+**Purpose:** Defines room mutation rules — environment changes triggered by narrative progression, fear state, or adaptive difficulty.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `MutationTag` | `FGameplayTag` | Unique mutation identifier |
+| `RoomFilter` | `FGameplayTag` | Which rooms this mutation applies to |
+| `MutationType` | `EMutationType` | Geometry, Lighting, Audio, EnemyPlacement, LootPlacement |
+| `RequiredNarrativeFlags` | `TArray<FGameplayTag>` | Flags required for mutation to activate |
+| `RequiredFearThreshold` | `EFearThreshold` | Minimum fear tier needed |
+| `CooldownSeconds` | `float` | Min time between mutations |
+| `MutationChance` | `float` | 0.0-1.0 probability per eligible room |
+| `bCanRevert` | `bool` | Can room return to original state |
+| `RevertCondition` | `FGameplayTag` | Narrative flag that triggers revert |
+
+---
+
+## Gameplay Tags
+- Namespace: `RoomMutation.<Type>.<Name>` (e.g., `RoomMutation.Geometry.WallShift`)
+
+---
+
+## Validation Rules
+- `MutationTag` must be unique
+- `MutationChance` must be 0.0-1.0
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| MutationTag | `RoomMutation.Geometry.CeilingDrop` |
+| MutationType | Geometry |
+| RequiredFearThreshold | Afraid |
+| MutationChance | 0.3 |
+
+---
+
+## Consumed By
+- [`BPC_AdaptiveEnvironmentDirector`](../10-adaptive/)
--- a/docs/blueprints/14-data-assets/127_DA_ScareEvent.md
+++ b/docs/blueprints/14-data-assets/127_DA_ScareEvent.md
@@ -0,0 +1,54 @@
+# DA_ScareEvent — Data Asset
+
+**Parent Class:** `UDataAsset`
+**Dependencies:** [`BPC_ScareEventSystem`](../10-adaptive/)
+**Purpose:** Defines scare event configurations — trigger conditions, visual/audio effects, and intensity scaling.
+
+---
+
+## Variables / Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ScareTag` | `FGameplayTag` | Unique scare event identifier |
+| `ScareType` | `EScareType` | JumpScare, Ambient, Scripted, Environmental |
+| `TriggerCondition` | `FGameplayTag` | Narrative or world condition tag |
+| `VisualEffectKey` | `FName` | Screen effect preset for WBP_ScreenEffectController |
+| `AudioEffectKey` | `FName` | Audio cue for AudioAtmosphereController |
+| `Intensity` | `float` | 0.0-1.0 scare intensity |
+| `CooldownSeconds` | `float` | Min time between triggers |
+| `bRequiresDarkness` | `bool` | Only trigger in dark areas |
+| `bOncePerSession` | `bool` | Only trigger once per play session |
+| `MaxTriggersPerRun` | `int32` | Max total triggers (-1 = unlimited) |
+
+---
+
+## Gameplay Tags
+- Namespace: `Scare.<Type>.<Name>` (e.g., `Scare.JumpScare.ClosetMonster`)
+
+---
+
+## Validation Rules
+- `ScareTag` must be unique
+- `Intensity` must be 0.0-1.0
+
+---
+
+## Example Data
+
+| Field | Value |
+|-------|-------|
+| ScareTag | `Scare.JumpScare.MirrorReflection` |
+| ScareType | JumpScare |
+| Intensity | 0.8 |
+| CooldownSeconds | 120.0 |
+| bOncePerSession | true |
+
+---
+
+## Consumed By
+- [`BPC_ScareEventSystem`](../10-adaptive/)
+
+## Reuse Notes
+- Scare events are data-driven; designers add new events without code changes
+- Cooldown system prevents scare spam
--- a/docs/blueprints/14-data-assets/129_DA_InputMappingProfile.md
+++ b/docs/blueprints/14-data-assets/129_DA_InputMappingProfile.md
@@ -0,0 +1,220 @@
+# 129 — Input Mapping Profile (`DA_InputMappingProfile`)
+
+## Purpose
+Primary Data Asset that defines all Enhanced Input bindings across three platforms (PC/Mouse, Xbox, PS5 DualSense). Single source of truth for: which Input Actions map to which keys per platform, which Input Mapping Contexts each action belongs to, context priority defaults, and all modifier configurations (Negate, Swizzle, Dead Zone, Chord). Loaded by [`SS_EnhancedInputManager`](docs/blueprints/15-input/128_SS_EnhancedInputManager.md) at initialization.
+
+## Dependencies
+- **Requires:** None (self-contained Data Asset)
+- **Required By:** [`SS_EnhancedInputManager`](docs/blueprints/15-input/128_SS_EnhancedInputManager.md) (loads and caches this), [`SS_SettingsSystem`](docs/blueprints/12-settings/105_SS_SettingsSystem.md) (references for key rebinding)
+- **Engine/Plugin Requirements:** Enhanced Input Plugin, `UInputMappingContext`, `UInputAction`
+
+## Class Info
+| Property | Value |
+|----------|-------|
+| **Parent Class** | `UPrimaryDataAsset` |
+| **Class Type** | Data Asset |
+| **Asset Path** | `Content/Framework/DataAssets/DA_InputMappingProfile` |
+| **Implements Interfaces** | None |
+
+---
+
+## 1. Enums
+
+*No enums are defined by this Data Asset. Uses `E_InputContext` and `E_InputPlatform` from [`SS_EnhancedInputManager`](docs/blueprints/15-input/128_SS_EnhancedInputManager.md).*
+
+---
+
+## 2. Structs
+
+### `S_PlatformActionBinding`
+| Field | Type | Description |
+|-------|------|-------------|
+| `Action` | `UInputAction*` | Reference to the IA_ Input Action asset |
+| `ContextType` | `E_InputContext` | Which IMC this action belongs to |
+| `PrimaryKey` | `FKey` | Primary key/button |
+| `SecondaryKey` | `FKey` | Secondary key/button (optional) |
+| `bIsHold` | `Bool` | Whether this is a hold-triggered action (vs tap) |
+| `HoldDuration` | `Float` | Seconds to hold before triggering (0.0 = instant) |
+| `Modifiers` | `TArray<UInputModifier*>` | Array of modifier instances (Negate, Swizzle, DeadZone, etc.) |
+| `Triggers` | `TArray<UInputTrigger*>` | Array of trigger instances (Pressed, Released, Hold, Tap, Chord) |
+
+### `S_PlatformProfile`
+| Field | Type | Description |
+|-------|------|-------------|
+| `Platform` | `E_InputPlatform` | Which platform this profile is for |
+| `Bindings` | `TArray<S_PlatformActionBinding>` | All action bindings for this platform |
+| `ControllerGlyphSet` | `FName` | Which glyph set to display ("Xbox", "PS5", "Keyboard") |
+| `DeadZoneThreshold` | `Float` | Analog stick dead zone for this platform |
+| `MouseSensitivity` | `Float` | Default mouse sensitivity (PC only, 1.0 = baseline) |
+| `ControllerSensitivity` | `Float` | Default controller sensitivity |
+
+### `S_ContextDefinition`
+| Field | Type | Description |
+|-------|------|-------------|
+| `ContextType` | `E_InputContext` | Which context this defines |
+| `MappingContext` | `UInputMappingContext*` | Reference to the IMC_ asset for this context |
+| `DefaultPriority` | `Int32` | Default priority when pushed |
+| `bBlockLowerContexts` | `Bool` | Whether this context consumes input (prevents passthrough) |
+| `Description` | `FText` | Human-readable description for debugging |
+
+---
+
+## 3. Variables
+
+### Configuration (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `PlatformProfiles` | `TArray<S_PlatformProfile>` | `Empty` | `Profiles` | One profile per platform (3 total) |
+| `ContextDefinitions` | `TArray<S_ContextDefinition>` | `Empty` | `Contexts` | IMC asset references and defaults |
+| `GlobalDeadZone` | `Float` | `0.15` | `Global` | Fallback analog stick dead zone |
+| `bEnableControllerRumble` | `Bool` | `true` | `Global` | Master toggle for force feedback |
+| `bSwapSticksForLeftHanded` | `Bool` | `false` | `Accessibility` | Swap left/right stick for accessibility |
+| `AxisInvertSettings` | `TMap<FName, Bool>` | `Empty` | `Accessibility` | Per-action axis inversion (e.g., "IA_Look" = InvertY) |
+
+---
+
+## 4. Functions
+
+*This Data Asset has no Blueprint functions. All data retrieval is performed by [`SS_EnhancedInputManager`](docs/blueprints/15-input/128_SS_EnhancedInputManager.md) reading the struct arrays directly.*
+
+---
+
+## 5. Event Dispatchers
+
+*None. Data Assets do not have event dispatchers.*
+
+---
+
+## 6. Overridden Events / Custom Events
+
+*None.*
+
+---
+
+## 7. Complete Binding Table
+
+### IMC_Default (Priority 0) — Core Gameplay
+
+| Input Action | PC Keyboard/Mouse | Xbox | PS5 DualSense | Modifiers |
+|:---|:---|:---|:---|:---|
+| `IA_Move` | W (Y=1), S (Y=-1, Negate), D (X=1, Swizzle), A (X=-1, Swizzle+Negate) | Left Stick | Left Stick | DeadZone 0.15 |
+| `IA_Look` | Mouse XY | Right Stick | Right Stick | InvertY optional |
+| `IA_Interact` | E / Left Click | X (Face Left) | Square | Tap/Hold trigger |
+| `IA_PrimaryAction` | Left Mouse Button | RT (Right Trigger) | R2 | — |
+| `IA_SecondaryAction` | Right Mouse Button | LT (Left Trigger) | L2 | — |
+| `IA_Sprint` | Left Shift | LS Click (L3) | L3 | Hold trigger |
+| `IA_Crouch` | C / Left Ctrl | B (Face Right) | Circle | Toggle or Hold |
+| `IA_Vault_Climb` | Spacebar | A (Face Bottom) | Cross | Contextual |
+| `IA_Jump` | Spacebar | A (Face Bottom) | Cross | Passthrough when no vault context |
+| `IA_Flashlight` | F | D-Pad Up | D-Pad Up | Toggle |
+| `IA_QuickHeal` | Q / H | D-Pad Down | D-Pad Down | Instant |
+| `IA_Reload` | R | Y (Face Top) | Triangle | — |
+| `IA_OpenWatch` | Tab / I | View Button | Touchpad Click | — |
+| `IA_PauseMenu` | Esc / P | Menu Button | Options Button | — |
+| `IA_QuickSlotScroll` | Scroll Wheel Up/Down | — | — | Axis1D |
+| `IA_QuickSlot1` | 1 | — | — | Digital |
+| `IA_QuickSlot2` | 2 | — | — | Digital |
+| `IA_QuickSlot3` | 3 | — | — | Digital |
+| `IA_QuickSlot4` | 4 | — | — | Digital |
+| `IA_QuickSlot5` | 5 | — | — | Digital |
+| `IA_QuickSlot6` | 6 | — | — | Digital |
+| `IA_QuickSlot7` | 7 | — | — | Digital |
+| `IA_QuickSlot8` | 8 | — | — | Digital |
+| `IA_SkipCutscene` | Spacebar (Hold) | A/Cross (Hold) | Cross (Hold) | Hold 2.0s trigger |
+
+### IMC_Hiding (Priority 5) — Hiding Spots
+
+| Input Action | PC Keyboard/Mouse | Xbox | PS5 DualSense | Notes |
+|:---|:---|:---|:---|:---|
+| `IA_Hide_Look` | Mouse XY (clamped ±45°) | Right Stick (clamped) | Right Stick (clamped) | Axis2D |
+| `IA_Hide_Peek` | W/S | Left Stick Y | Left Stick Y | Axis1D |
+| `IA_Hide_HoldBreath` | Spacebar (Hold) | LT + RT (Hold) | L2 + R2 (Hold) | Hold trigger |
+| `IA_Exit_Hide` | C / Esc | B (Face Right) | Circle | — |
+
+### IMC_WristwatchUI (Priority 10) — Inventory Screen
+
+| Input Action | PC Keyboard/Mouse | Xbox | PS5 DualSense | Notes |
+|:---|:---|:---|:---|:---|
+| `IA_UI_Navigate` | W/A/S/D or Arrow Keys | D-Pad / Left Stick | D-Pad / Left Stick | Axis2D |
+| `IA_UI_Select` | E / Enter | A (Face Bottom) | Cross | — |
+| `IA_UI_Combine` | C | X (Face Left) | Square | — |
+| `IA_UI_DropItem` | X | Y (Face Top) | Triangle | — |
+| `IA_CloseWatch` | Tab / Esc | B / View Button | Circle / Touchpad | — |
+
+### IMC_Inspection (Priority 20) — 3D Item Inspection
+
+| Input Action | PC Keyboard/Mouse | Xbox | PS5 DualSense | Notes |
+|:---|:---|:---|:---|:---|
+| `IA_Inspect_Rotate` | Mouse XY | Right Stick | Right Stick | Axis2D |
+| `IA_Inspect_Zoom` | Scroll Wheel | LT / RT | L2 / R2 | Axis1D |
+| `IA_Inspect_Flip` | F | Y (Face Top) | Triangle | — |
+| `IA_Cancel_Drop` | Right Click / Esc | B (Face Right) | Circle | — |
+
+### IMC_UI (Priority 100) — Full-Screen Menus and Pause
+
+| Input Action | PC Keyboard/Mouse | Xbox | PS5 DualSense | Notes |
+|:---|:---|:---|:---|:---|
+| `IA_UI_Navigate` | W/A/S/D or Arrow Keys | D-Pad / Left Stick | D-Pad / Left Stick | Axis2D (reused from WristwatchUI) |
+| `IA_UI_Select` | E / Enter | A (Face Bottom) | Cross | (reused) |
+| `IA_UI_Back` | Esc / Backspace | B (Face Right) | Circle | Universal back |
+| `IA_ToggleAccessibility` | F6 | View+Menu (Chord) | Touchpad Long Press | Accessibility quick toggle |
+| `IA_PauseMenu` | Esc / P | Menu Button | Options Button | Close pause = pop context |
+
+---
+
+## 8. Modifier Configuration Reference
+
+### W/A/S/D Key Swizzle Setup
+For `IA_Move` on PC:
+- **W** = `Input Action Value.Y = 1.0` (default, no modifier)
+- **S** = Add **Negate** modifier → `Input Action Value.Y = -1.0`
+- **D** = Add **Swizzle Input Axis Values** modifier (Order: YXZ) + default → `Input Action Value.X = 1.0`
+- **A** = Add **Swizzle Input Axis Values** modifier (Order: YXZ) + **Negate** → `Input Action Value.X = -1.0`
+
+### Hold Trigger Configuration
+| Action | Hold Duration | Trigger Type |
+|--------|---------------|--------------|
+| `IA_Interact` (physics drag) | 0.3s | Hold + Release |
+| `IA_Sprint` | 0.0s (instant) | Hold (continuous while pressed) |
+| `IA_Crouch` (if toggle off) | 0.0s | Hold |
+| `IA_Hide_HoldBreath` | 0.0s | Hold (continuous) |
+| `IA_SkipCutscene` | 2.0s | Hold (trigger on completion) |
+
+### Chord Actions
+| Action | Chord Combination | Description |
+|--------|-------------------|-------------|
+| `IA_ToggleAccessibility` (Xbox) | View + Menu (simultaneous) | Two-button chord for rare action |
+| `IA_Hide_HoldBreath` (Xbox/PS5) | LT + RT / L2 + R2 | Both triggers held simultaneously |
+
+---
+
+## 9. Validation / Testing Checklist
+
+- [ ] All 30+ Input Actions are referenced in at least one platform binding
+- [ ] Every `E_InputContext` has a corresponding `S_ContextDefinition` with `MappingContext` assigned
+- [ ] W/A/S/D modifiers (Negate, Swizzle) produce correct axis values
+- [ ] Analog stick dead zones prevent drift on all three platforms
+- [ ] Hold actions correctly distinguish tap vs hold (Interact: tap=pickup, hold=drag)
+- [ ] `IA_Vault_Climb` and `IA_Jump` coexist correctly (contextual vs general)
+- [ ] Quick slots 1–8 are keyboard-only; console uses scroll
+- [ ] `IA_UI_Back` vs `IA_Cancel_Drop` have separate bindings (back ≠ cancel)
+- [ ] Chord actions (HoldBreath on controller, Accessibility toggle) work as two-button combos
+- [ ] Controller glyph set switches correctly on platform hot-swap
+- [ ] Edge case: No duplicate keys within the same IMC for mutually exclusive actions
+- [ ] Edge case: Dead zone on Scroll Wheel (IA_QuickSlotScroll) prevents accidental scrolling
+
+---
+
+## 10. Reuse Notes
+
+- This Data Asset is the **single source of truth** for ALL input bindings. No other system hardcodes key references.
+- When adding a new Input Action: 1) Create the IA_ asset, 2) Add it to this DA under the correct context/platform, 3) The IMC asset references this DA — update the IMC accordingly.
+- Platform profiles can be authored in the Content Browser; designers don't need to touch Blueprint graphs.
+- For accessibility: `AxisInvertSettings` allows per-player Y-axis inversion without modifying the core bindings.
+- `bBlockLowerContexts` on `S_ContextDefinition` controls whether IMC_Hiding passes through `IA_Move` to IMC_Default (it blocks) vs whether IMC_UI allows `IA_QuickSlotScroll` passthrough (it doesn't).
+- Console-specific glyphs (Xbox ABXY vs PS5 Cross/Circle/Square/Triangle) are handled by `ControllerGlyphSet` for dynamic UI updates.
+
+---
+
+*Blueprint Spec: Input Mapping Profile Data Asset. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework, INPUT layer.*
--- a/docs/blueprints/14-data-assets/134_DA_AudioSettings.md
+++ b/docs/blueprints/14-data-assets/134_DA_AudioSettings.md
@@ -0,0 +1,234 @@
+# 134 — Audio Settings Data Asset (`DA_AudioSettings`)
+
+## Purpose
+Central configuration Data Asset for the MetaSounds Audio System. Holds all default bus configurations, volume defaults, pooling limits, ducking amounts, and accessibility settings. Loaded by `SS_AudioManager` on initialization to configure all 4 MetaSound buses.
+
+## Dependencies
+- **Requires:** `SS_AudioManager` (132 — loads this DA on init), MetaSound sources (`MS_MasterBus`, `MS_SFXBus`, `MS_AmbientBus`, `MS_MusicBus`, `MS_DialogueBus`)
+- **Required By:** `SS_AudioManager` (132 — direct consumer), Sound Design Team (primary editor target)
+- **Engine/Plugin Requirements:** MetaSounds plugin, GameplayTags plugin
+
+## Class Info
+| Property | Value |
+|----------|-------|
+| **Parent Class** | `PrimaryDataAsset` |
+| **Class Type** | Data Asset |
+| **Asset Path** | `Content/Framework/Audio/DA_AudioSettings.uasset` |
+| **Implements Interfaces** | *(none)* |
+
+---
+
+## 1. Enums
+
+*Uses E_AudioBusCategory from `SS_AudioManager` (132).*
+
+---
+
+## 2. Structs
+
+*Uses `S_AudioBusConfig` and `S_RoomAcousticProfile` from `SS_AudioManager` (132).*
+
+---
+
+## 3. Variables
+
+### Bus Configuration (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `SFXBusConfig` | `S_AudioBusConfig` | *(see defaults below)* | `Bus Config` | SFX bus configuration |
+| `AmbienceBusConfig` | `S_AudioBusConfig` | *(see defaults below)* | `Bus Config` | Ambience bus configuration |
+| `MusicBusConfig` | `S_AudioBusConfig` | *(see defaults below)* | `Bus Config` | Music bus configuration |
+| `DialogueBusConfig` | `S_AudioBusConfig` | *(see defaults below)* | `Bus Config` | Dialogue bus configuration |
+
+### Volume Defaults (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `DefaultMasterVolume` | `Float` | `1.0` | `Volume` | Default master volume (0–1) |
+| `DefaultSFXVolume` | `Float` | `0.85` | `Volume` | Default SFX volume (0–1) |
+| `DefaultMusicVolume` | `Float` | `0.80` | `Volume` | Default music volume (0–1) |
+| `DefaultAmbientVolume` | `Float` | `0.75` | `Volume` | Default ambient volume (0–1) |
+| `DefaultDialogueVolume` | `Float` | `1.0` | `Volume` | Default dialogue volume (0–1) |
+
+### Pool & Limits (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `SFXPoolSize` | `Integer` | `32` | `Pool` | Max concurrent SFX audio components |
+| `MaxConcurrentDialogue` | `Integer` | `2` | `Dialogue` | Max simultaneous dialogue lines |
+| `MaxWeaponFireVoices` | `Integer` | `8` | `SFX Sub-mix` | Max concurrent weapon fire sounds |
+| `MaxFootstepVoices` | `Integer` | `4` | `SFX Sub-mix` | Max concurrent footstep sounds |
+| `MaxImpactVoices` | `Integer` | `8` | `SFX Sub-mix` | Max concurrent impact sounds |
+
+### Ducking Configuration (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `DialogueDuckSFX` | `Float` | `0.5` | `Ducking` | SFX volume multiplier during dialogue (1.0 = no duck, 0.5 = -6dB) |
+| `DialogueDuckAmbience` | `Float` | `0.25` | `Ducking` | Ambience volume multiplier during dialogue (-12dB) |
+| `DialogueDuckMusic` | `Float` | `0.125` | `Ducking` | Music volume multiplier during dialogue (-18dB) |
+| `DuckTransitionTime` | `Float` | `0.3` | `Ducking` | Ducking fade-in/out time (seconds) |
+
+### Accessibility (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `bMonoAudioDefault` | `Boolean` | `false` | `Accessibility` | Default mono audio state |
+| `DefaultBalance` | `Float` | `0.0` | `Accessibility` | Default L/R balance (-1.0 = left, 0.0 = center, 1.0 = right) |
+| `bAudioCuesForUI` | `Boolean` | `false` | `Accessibility` | Play confirmation SFX on UI button presses |
+
+### MetaSound Source References (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `MasterBusSource` | `UMetaSoundSource` | `None` | `MetaSound Ref` | `MS_MasterBus` MetaSound patch |
+| `SFXBusSource` | `UMetaSoundSource` | `None` | `MetaSound Ref` | `MS_SFXBus` MetaSound patch |
+| `AmbientBusSource` | `UMetaSoundSource` | `None` | `MetaSound Ref` | `MS_AmbientBus` MetaSound patch |
+| `MusicBusSource` | `UMetaSoundSource` | `None` | `MetaSound Ref` | `MS_MusicBus` MetaSound patch |
+| `DialogueBusSource` | `UMetaSoundSource` | `None` | `MetaSound Ref` | `MS_DialogueBus` MetaSound patch |
+
+### Room Defaults (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `DefaultRoomPreset` | `DA_RoomAcousticPreset` | `DA_RP_Outdoor` | `Room` | Fallback room preset when no zone is active |
+| `RoomPresetList` | `Array<DA_RoomAcousticPreset>` | *(all presets)* | `Room` | All available room presets (populates SS_AudioManager.RoomPresets) |
+
+---
+
+## 4. Default Bus Configurations
+
+### SFX Bus Default Config
+| Field | Value |
+|-------|-------|
+| `BusCategory` | `SFX` |
+| `DefaultVolume` | `0.85` |
+| `MetaSoundSource` | `MS_SFXBus` |
+| `bSpatialized` | `true` |
+| `AttenuationSettings` | `ATT_DefaultSFX` |
+| `MaxConcurrentSounds` | `32` |
+| `DuckingPriority` | `10` |
+| `DuckAmount` | `0.5` |
+| `SettingsBindingTag` | `Settings.Audio.SFXVolume` |
+
+### Ambience Bus Default Config
+| Field | Value |
+|-------|-------|
+| `BusCategory` | `Ambience` |
+| `DefaultVolume` | `0.75` |
+| `MetaSoundSource` | `MS_AmbientBus` |
+| `bSpatialized` | `false` |
+| `AttenuationSettings` | *(none — stereo)* |
+| `MaxConcurrentSounds` | `1` |
+| `DuckingPriority` | `5` |
+| `DuckAmount` | `0.25` |
+| `SettingsBindingTag` | `Settings.Audio.AmbientVolume` |
+
+### Music Bus Default Config
+| Field | Value |
+|-------|-------|
+| `BusCategory` | `Music` |
+| `DefaultVolume` | `0.80` |
+| `MetaSoundSource` | `MS_MusicBus` |
+| `bSpatialized` | `false` |
+| `AttenuationSettings` | *(none — stereo)* |
+| `MaxConcurrentSounds` | `4` (layers) |
+| `DuckingPriority` | `20` |
+| `DuckAmount` | `0.125` |
+| `SettingsBindingTag` | `Settings.Audio.MusicVolume` |
+
+### Dialogue Bus Default Config
+| Field | Value |
+|-------|-------|
+| `BusCategory` | `Dialogue` |
+| `DefaultVolume` | `1.0` |
+| `MetaSoundSource` | `MS_DialogueBus` |
+| `bSpatialized` | `true` |
+| `AttenuationSettings` | `ATT_Dialogue` |
+| `MaxConcurrentSounds` | `2` |
+| `DuckingPriority` | `100` |
+| `DuckAmount` | `1.0` (ducks all other buses) |
+| `SettingsBindingTag` | `Settings.Audio.DialogueVolume` |
+
+---
+
+## 5. Functions
+
+### Public Functions
+
+#### `GetDefaultBusConfig` → `S_AudioBusConfig`
+- **Description:** Returns the bus config for a given category.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `Bus` | `E_AudioBusCategory` | Which bus to get config for |
+- **Blueprint Authority:** Any (Pure)
+
+#### `GetDefaultVolume` → `Float`
+- **Description:** Returns the default volume for a bus category.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `Bus` | `E_AudioBusCategory` | Which bus |
+- **Blueprint Authority:** Any (Pure)
+
+---
+
+## 6. Data Asset Edibility Notes
+
+### Sound Designer Workflow
+1. Open `DA_AudioSettings` in the Content Browser
+2. Assign MetaSound source references to each bus
+3. Adjust default volumes per bus
+4. Configure ducking amounts for dialogue priority
+5. Set SFX pool size and sub-mix voice limits
+6. Assign default room preset
+7. Changes take effect on next game launch (no recompile needed)
+
+### Platform-Specific Variants
+- Maintain separate `DA_AudioSettings` Data Assets per platform if needed:
+  - `DA_AudioSettings_PC` — Higher pool size (32), full spatialization
+  - `DA_AudioSettings_Console` — Reduced pool (24), optimized attenuation
+  - `DA_AudioSettings_Mobile` — Minimal pool (16), simplified reverb
+
+---
+
+## 7. Communication Matrix
+
+| Who Talks | How | What Is Sent |
+|-----------|-----|-------------|
+| `SS_AudioManager` (132) | `Direct: Load Data Asset` on Initialize | Reads all bus configs, volumes, pool settings |
+| `SS_AudioManager` (132) | `Function Call: GetDefaultBusConfig` | Queries `S_AudioBusConfig` per category |
+| Sound Design Team | Data Asset Editor | Edits bus configs, MetaSound refs, ducking params |
+
+---
+
+## 8. Validation / Testing Checklist
+
+- [ ] All 4 `BusConfig` structs have non-null `MetaSoundSource` references
+- [ ] SFX `bSpatialized = true`, Ambience/Music `bSpatialized = false`
+- [ ] Dialogue `DuckingPriority = 100` (highest)
+- [ ] Dialogue ducking multipliers: SFX > Ambience > Music (more duck for music)
+- [ ] `SFXPoolSize` between 16–64 (reasonable range)
+- [ ] `MaxConcurrentDialogue <= 2` (prevents overlapping VO chaos)
+- [ ] Volume defaults between 0.0 and 1.0
+- [ ] `DialogueDuck*` multipliers between 0.0 and 1.0
+- [ ] `DefaultRoomPreset` not null
+- [ ] `RoomPresetList` contains all expected room presets
+- [ ] Platform variants have appropriate pool sizes for target hardware
+- [ ] Edge case: Null MetaSound source → SS_AudioManager logs warning and disables that bus
+
+---
+
+## 9. Reuse Notes
+
+- This Data Asset is the **sound designer's control panel** for the entire audio system.
+- `S_AudioBusConfig` fields are exposed directly — no blueprint access required to tune bus behavior.
+- The `SettingsBindingTag` on each bus config maps to the persistent settings key, enabling the settings UI to discover available audio sliders automatically.
+- Ducking amounts use multiplicative volume (not additive dB) for simplicity — a value of 0.5 means "reduce to 50% volume when dialogue is active."
+- Voice limiting per sub-mix (WeaponFire=8, Footsteps=4, Impacts=8) prevents a single audio category from drowning out others.
+
+---
+
+*Blueprint Spec: DA_AudioSettings — Central configuration for MetaSounds audio buses. Architecture document: [`metasounds-audio-system.md`](../../architecture/metasounds-audio-system.md)*
--- a/docs/blueprints/14-data-assets/135_DA_RoomAcousticPreset.md
+++ b/docs/blueprints/14-data-assets/135_DA_RoomAcousticPreset.md
@@ -0,0 +1,305 @@
+# 135 — Room Acoustic Preset Data Asset (`DA_RoomAcousticPreset`)
+
+## Purpose
+Data Asset that defines the acoustic properties of a room or environment. Contains reverb parameters (density, decay time, wet/dry mix), occlusion settings, and per-bus application flags. Used by `BP_RoomAudioZone` and `SS_AudioManager` to configure room reverb when the player enters a new acoustic zone.
+
+## Dependencies
+- **Requires:** `SS_AudioManager` (132 — applies reverb to buses), `BP_RoomAudioZone` (133 — assigns preset to zone volume)
+- **Required By:** `BP_RoomAudioZone` (133 — direct assignment), `SS_AudioManager` (132 — room transition interpolation), Sound Design Team (primary editor target)
+- **Engine/Plugin Requirements:** MetaSounds plugin (reverb parameters), GameplayTags plugin
+
+## Class Info
+| Property | Value |
+|----------|-------|
+| **Parent Class** | `PrimaryDataAsset` |
+| **Class Type** | Data Asset |
+| **Asset Path** | `Content/Framework/Audio/RoomPresets/DA_RoomAcousticPreset.uasset` |
+| **Implements Interfaces** | *(none)* |
+
+---
+
+## 1. Enums
+
+*Uses E_AudioBusCategory from `SS_AudioManager` (132).*
+
+---
+
+## 2. Structs
+
+*Uses `S_RoomAcousticProfile` from `SS_AudioManager` (132). Field reference:*
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `RoomPresetName` | `FName` | Identifier for this room preset |
+| `ReverbDensity` | `Float` (0–1) | How dense the reverb reflections are |
+| `ReverbDecayTime` | `Float` (seconds) | RT60 decay time |
+| `ReverbWetLevel` | `Float` (0–1) | Wet/dry mix for reverb |
+| `ReflectionsDelay` | `Float` (ms) | Pre-delay before reflections start |
+| `RoomSizeScale` | `Float` (0.5–3.0) | Perceived room size |
+| `OcclusionMultiplier` | `Float` (0–1) | How much walls occlude sound (0=open, 1=blocked) |
+| `LowPassCutoff` | `Float` (Hz) | Low-pass filter cutoff (simulates wall filtering) |
+| `bApplyToSFX` | `Boolean` | Apply reverb to SFX bus |
+| `bApplyToAmbience` | `Boolean` | Apply reverb to Ambience bus |
+| `bApplyToDialogue` | `Boolean` | Apply reverb to Dialogue bus |
+| `TransitionTime` | `Float` (seconds) | Crossfade time when entering this room |
+
+---
+
+## 3. Variables
+
+### Acoustic Profile (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `AcousticProfile` | `S_RoomAcousticProfile` | *(preset-specific)* | `Acoustic` | Complete acoustic profile struct (see below for per-preset values) |
+
+### Meta (Instance Editable)
+
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `PresetDisplayName` | `Text` | `"Unnamed Preset"` | `Meta` | Human-readable name shown in editor dropdowns |
+| `PresetDescription` | `Text` | `""` | `Meta` | Description of what this preset is for |
+| `bIsDefaultFallback` | `Boolean` | `false` | `Meta` | Is this the default/fallback preset? (Outdoor should be true) |
+
+---
+
+## 4. Default Preset Values
+
+### `DA_RP_Outdoor` (Default Fallback)
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `Outdoor` |
+| `ReverbDensity` | `0.05` |
+| `ReverbDecayTime` | `0.3` |
+| `ReverbWetLevel` | `0.05` |
+| `ReflectionsDelay` | `5.0` |
+| `RoomSizeScale` | `3.0` (max — open space) |
+| `OcclusionMultiplier` | `0.0` (no occlusion) |
+| `LowPassCutoff` | `20000` (no filtering) |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `1.0` |
+
+### `DA_RP_SmallRoom`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `SmallRoom` |
+| `ReverbDensity` | `0.4` |
+| `ReverbDecayTime` | `0.6` |
+| `ReverbWetLevel` | `0.25` |
+| `ReflectionsDelay` | `15.0` |
+| `RoomSizeScale` | `0.8` |
+| `OcclusionMultiplier` | `0.3` |
+| `LowPassCutoff` | `8000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `1.5` |
+
+### `DA_RP_LargeHall`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `LargeHall` |
+| `ReverbDensity` | `0.7` |
+| `ReverbDecayTime` | `3.0` |
+| `ReverbWetLevel` | `0.5` |
+| `ReflectionsDelay` | `40.0` |
+| `RoomSizeScale` | `2.5` |
+| `OcclusionMultiplier` | `0.1` |
+| `LowPassCutoff` | `10000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `2.0` |
+
+### `DA_RP_Cave`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `Cave` |
+| `ReverbDensity` | `0.8` |
+| `ReverbDecayTime` | `4.5` |
+| `ReverbWetLevel` | `0.65` |
+| `ReflectionsDelay` | `60.0` |
+| `RoomSizeScale` | `2.0` |
+| `OcclusionMultiplier` | `0.6` |
+| `LowPassCutoff` | `4000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `2.5` |
+
+### `DA_RP_VoidSpace`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `VoidSpace` |
+| `ReverbDensity` | `0.15` |
+| `ReverbDecayTime` | `8.0` |
+| `ReverbWetLevel` | `0.8` |
+| `ReflectionsDelay` | `120.0` |
+| `RoomSizeScale` | `3.0` |
+| `OcclusionMultiplier` | `0.0` (ethereal — no occlusion) |
+| `LowPassCutoff` | `3000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `3.0` (dramatic slow transition) |
+
+### `DA_RP_Industrial`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `Industrial` |
+| `ReverbDensity` | `0.6` |
+| `ReverbDecayTime` | `2.0` |
+| `ReverbWetLevel` | `0.4` |
+| `ReflectionsDelay` | `25.0` |
+| `RoomSizeScale` | `2.2` |
+| `OcclusionMultiplier` | `0.4` |
+| `LowPassCutoff` | `6000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `1.5` |
+
+### `DA_RP_Bathroom`
+| Field | Value |
+|-------|-------|
+| `RoomPresetName` | `Bathroom` |
+| `ReverbDensity` | `0.9` |
+| `ReverbDecayTime` | `1.2` |
+| `ReverbWetLevel` | `0.55` |
+| `ReflectionsDelay` | `8.0` |
+| `RoomSizeScale` | `0.6` |
+| `OcclusionMultiplier` | `0.7` |
+| `LowPassCutoff` | `7000` |
+| `bApplyToSFX` | `true` |
+| `bApplyToAmbience` | `true` |
+| `bApplyToDialogue` | `true` |
+| `TransitionTime` | `1.0` |
+
+---
+
+## 5. Functions
+
+### Public Functions
+
+#### `GetProfileName` → `FName`
+- **Description:** Returns the `RoomPresetName` from the acoustic profile. Used for debug display and logging.
+- **Parameters:** *(none)*
+- **Blueprint Authority:** Any (Pure)
+
+#### `GetTransitionTime` → `Float`
+- **Description:** Returns the crossfade duration. Used by `SS_AudioManager` for transition interpolation.
+- **Parameters:** *(none)*
+- **Blueprint Authority:** Any (Pure)
+
+#### `ShouldApplyToBus` → `Boolean`
+- **Description:** Returns whether this preset should apply reverb to a specific bus category.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `Bus` | `E_AudioBusCategory` | Which bus to check |
+- **Blueprint Authority:** Any (Pure)
+
+---
+
+## 6. Blueprint Graph Logic Flow
+
+### Room Preset Application (in SS_AudioManager)
+
+```mermaid
+flowchart TD
+    A[Enter Room Audio Zone] --> B[BP_RoomAudioZone.OnBeginOverlap]
+    B --> C[SS_AudioManager.SetRoomPreset: DA_RoomAcousticPreset]
+    C --> D[Read AcousticProfile fields]
+    D --> E{bApplyToSFX?}
+    E -->|Yes| F[Apply reverb to SFX Bus]
+    E -->|No| G[Skip SFX Bus]
+    F --> H{bApplyToAmbience?}
+    G --> H
+    H -->|Yes| I[Apply reverb to Ambience Bus]
+    H -->|No| J[Skip Ambience Bus]
+    I --> K{bApplyToDialogue?}
+    J --> K
+    K -->|Yes| L[Apply reverb to Dialogue Bus]
+    K -->|No| M[Skip Dialogue Bus]
+    L --> N[Begin crossfade over TransitionTime]
+    M --> N
+    N --> O[Room transition complete]
+```
+
+---
+
+## 7. Data Asset Edibility Notes
+
+### Sound Designer Workflow
+1. Create a new Data Asset: `Miscellaneous → Data Asset → DA_RoomAcousticPreset`
+2. Name it with the `DA_RP_` prefix (e.g., `DA_RP_ConcertHall`)
+3. Fill in the `AcousticProfile` struct with desired reverb values
+4. Set `PresetDisplayName` and `PresetDescription` for editor clarity
+5. Set `TransitionTime` based on how dramatic the room change should feel
+6. Assign the preset to `BP_RoomAudioZone.RoomPreset` in level
+
+### Creating a New Room Preset
+1. Duplicate the closest existing preset (e.g., copy `DA_RP_SmallRoom` for a closet)
+2. Adjust values:
+   - Smaller room → higher `ReverbDensity`, lower `ReverbDecayTime`, lower `RoomSizeScale`
+   - Larger room → lower `ReverbDensity`, higher `ReverbDecayTime`, higher `RoomSizeScale`
+   - Outdoor → near-zero `ReverbWetLevel`, minimal `ReflectionsDelay`
+   - Cave/underground → high `ReverbDecayTime`, high `OcclusionMultiplier`, low `LowPassCutoff`
+3. Use `bApplyToSFX` / `bApplyToAmbience` / `bApplyToDialogue` to selectively apply reverb (e.g., dialogue through a radio should NOT get room reverb)
+
+### Tuning Guidelines
+| Parameter | Small Room | Medium Room | Large Hall | Outdoor | Cave |
+|-----------|-----------|-------------|------------|---------|------|
+| `ReverbDensity` | 0.4–0.6 | 0.3–0.5 | 0.6–0.8 | 0.0–0.1 | 0.7–0.9 |
+| `ReverbDecayTime` | 0.3–0.8s | 0.8–2.0s | 2.0–4.0s | 0.1–0.5s | 3.0–6.0s |
+| `ReverbWetLevel` | 0.15–0.3 | 0.2–0.4 | 0.4–0.6 | 0.0–0.1 | 0.5–0.8 |
+| `ReflectionsDelay` | 5–20ms | 15–40ms | 30–60ms | 2–10ms | 40–80ms |
+| `RoomSizeScale` | 0.5–1.0 | 1.0–2.0 | 2.0–3.0 | 3.0 | 1.5–2.5 |
+| `LowPassCutoff` | 5000–10000Hz | 6000–12000Hz | 8000–16000Hz | 20000Hz | 2000–5000Hz |
+
+---
+
+## 8. Communication Matrix
+
+| Who Talks | How | What Is Sent |
+|-----------|-----|-------------|
+| `BP_RoomAudioZone` (133) | `Direct: Reference` | Holds a `DA_RoomAcousticPreset` as `RoomPreset` variable |
+| `SS_AudioManager` (132) | `Function Call: SetRoomPreset(Preset)` | Receives preset, interpolates reverb parameters |
+| `SS_AudioManager` (132) | `Function Call: PopRoomPreset()` | Restores previous preset from stack |
+| Sound Design Team | Data Asset Editor | Edits reverb profiles, transition times |
+
+---
+
+## 9. Validation / Testing Checklist
+
+- [ ] All 7 default presets exist in `Content/Framework/Audio/RoomPresets/`
+- [ ] Each preset has a unique `RoomPresetName`
+- [ ] `ReverbDensity`, `ReverbWetLevel`, `OcclusionMultiplier` values between 0.0 and 1.0
+- [ ] `ReverbDecayTime` > 0.1 (minimum audible)
+- [ ] `ReflectionsDelay` between 0 and 200ms
+- [ ] `RoomSizeScale` between 0.5 and 3.0
+- [ ] `LowPassCutoff` between 1000 and 20000 Hz
+- [ ] `TransitionTime` between 0.5 and 5.0 seconds
+- [ ] `bApplyToSFX` is true for all presets (SFX should always get room reverb)
+- [ ] `DA_RP_Outdoor` has `bIsDefaultFallback = true`
+- [ ] `DA_RP_VoidSpace` has longer `TransitionTime` (dramatic effect)
+- [ ] At least one preset has `bApplyToDialogue = false` (for testing isolated dialogue bus)
+- [ ] Edge case: Switching to a preset with `TransitionTime = 0` applies instantly
+- [ ] Edge case: `RoomSizeScale = 3.0` (Outdoor) — no audible "room" reflection artifacts
+- [ ] Edge case: `ReverbDecayTime = 8.0` (VoidSpace) — long tail sounds ethereal, not glitchy
+
+---
+
+## 10. Reuse Notes
+
+- Create as many presets as needed per level. Presets are small Data Assets — negligible memory cost.
+- `bApplyToAmbience = false` is useful for "music-only" zones (e.g., boss arenas where ambient reverb would muddy the music).
+- `bApplyToDialogue = false` is useful for radio/phone conversations — the EQ toggle on the Dialogue bus handles the "radio voice" effect, not room reverb.
+- The `TransitionTime` field should be tuned carefully: too fast sounds abrupt; too slow feels laggy. 1.0–1.5s is a safe default.
+- For open-world streaming, assign the outdoor preset as the global default and place room zones only around enclosed spaces — this minimizes active zone overlap.
+
+---
+
+*Blueprint Spec: DA_RoomAcousticPreset — Room acoustic profile Data Asset. Architecture document: [`metasounds-audio-system.md`](../../architecture/metasounds-audio-system.md)*