UE5-Modular-Game-Framework/docs/blueprints/14-data-assets/135_DA_RoomAcousticPreset.md

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