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/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)*