UE5-Modular-Game-Framework/docs/blueprints/10-adaptive/133_BP_RoomAudioZone.md

133 — Room Audio Zone (BP_RoomAudioZone)

Purpose

A trigger volume placed in the world that automatically switches the audio reverb/occlusion profile when the player enters. When the player exits, it restores the previous room preset via a push/pop stack in SS_AudioManager. Supports nested room zones (room within building within cave) with priority-based override.

Dependencies

• Requires: SS_AudioManager (132 — calls SetRoomPreset / PopRoomPreset on overlap), DA_RoomAcousticPreset (135 — assigned acoustic profile)
• Required By: Level Designers (placed in world)
• Engine/Plugin Requirements: MetaSounds plugin (for room reverb pipeline)

Class Info

Property	Value
Parent Class	TriggerVolume (or Actor with BoxComponent)
Class Type	Blueprint Actor
Asset Path	Content/Framework/Audio/BP_RoomAudioZone.uasset
Implements Interfaces	(none)

---

1. Enums

Uses enums defined elsewhere:

• E_AudioBusCategory — from SS_AudioManager (132)

---

2. Structs

Uses struct defined in SS_AudioManager (132):

• S_RoomAcousticProfile — acoustic profile fields (reverb density, decay time, wet level, etc.)

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
RoomPreset	DA_RoomAcousticPreset	None	Room Config	Acoustic profile for this room
TransitionTime	Float	1.5	Room Config	Crossfade duration on enter (seconds)
ExitTransitionTime	Float	1.0	Room Config	Crossfade duration on exit (seconds)
bOverrideOcclusion	Boolean	false	Room Config	Override occlusion settings in this zone
OcclusionTraceChannel	ETraceTypeQuery	Camera	Room Config	Trace channel for per-source occlusion
Priority	Integer	0	Room Config	Higher priority zones override lower (for nested rooms)
bIsActive	Boolean	true	State	Whether this room zone is actively processing
ZoneDebugColor	LinearColor	Cyan	Debug	Color of the trigger volume in editor for visual identification
bShowDebugInfo	Boolean	false	Debug	Print room zone enter/exit to log

Internal (Private)

Variable	Type	Default	Category	Description
bPlayerInside	Boolean	false	State	Whether the player is currently inside this zone

---

4. Functions

Public Functions

SetRoomAudioEnabled → void

• Description: Toggle room audio processing. Used for narrative lock, void space override.
• Parameters:

  Param	Type	Description
  bEnabled	Boolean	True to enable, false to disable zone processing

• Blueprint Authority: Any
• Flow:
  1. Set bIsActive = bEnabled
  2. If bEnabled == false and bPlayerInside: force PopRoomPreset on SS_AudioManager
  3. If bEnabled == true and bPlayerInside: re-apply SetRoomPreset

GetPriority → Integer

• Description: Returns the zone priority. Used by SS_AudioManager for nested zone resolution.
• Parameters: (none)
• Blueprint Authority: Any (Pure)

GetAcousticProfile → DA_RoomAcousticPreset

• Description: Returns the assigned room acoustic preset.
• Parameters: (none)
• Blueprint Authority: Any (Pure)

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnPlayerEnteredZone	ZoneName: FName	Public	Fired when player enters (for gameplay logic)
OnPlayerExitedZone	ZoneName: FName	Public	Fired when player exits
OnZoneEnabledChanged	bEnabled: Boolean	Public	Fired when SetRoomAudioEnabled is called

---

6. Overridden Events / Custom Events

Event: OnActorBeginOverlap

• Description: Detects player character entering the trigger volume → calls SS_AudioManager.SetRoomPreset().
• Flow:
  1. Validate OtherActor — is it the player character? (check tag Player or cast to BP_PlayerCharacter)
  2. If not player: return
  3. If !bIsActive: return
  4. Set bPlayerInside = true
  5. Get SS_AudioManager from Game Instance
  6. Call SS_AudioManager.SetRoomPreset(RoomPreset) with TransitionTime
  7. Fire OnPlayerEnteredZone
  8. If bShowDebugInfo: log zone name to console

Event: OnActorEndOverlap

• Description: Player exits → restore previous room preset via SS_AudioManager.PopRoomPreset().
• Flow:
  1. Validate OtherActor — is it the player?
  2. If not player: return
  3. If !bIsActive: return
  4. Set bPlayerInside = false
  5. Get SS_AudioManager from Game Instance
  6. Call SS_AudioManager.PopRoomPreset() (restores previous room from stack)
  7. Fire OnPlayerExitedZone
  8. If bShowDebugInfo: log to console

Event: BeginPlay

• Description: Register this zone with a global zone manager if one exists. Configure trigger volume collision settings.
• Flow:
  1. Configure trigger volume: SetCollisionResponseToChannel(ECC_Pawn, ECR_Overlap)
  2. Set Generate Overlap Events = true
  3. Optionally set trigger volume color from ZoneDebugColor
  4. If RoomPreset is null: log warning, set bIsActive = false

Event: EndPlay

• Description: Cleanup — if player is inside zone on destruction, force pop the room preset.
• Flow:
  1. If bPlayerInside: call SS_AudioManager.PopRoomPreset()
  2. Set bPlayerInside = false

---

7. Blueprint Graph Logic Flow

Nested Room Zone Stack

flowchart TD
    A[Enter Room A - SmallRoom] --> B[SS_AudioManager.SetRoomPreset: SmallRoom]
    B --> C[Enter Room B - Bathroom, Priority > A]
    C --> D[SS_AudioManager.SetRoomPreset: Bathroom]
    D --> E[Exit Room B]
    E --> F[SS_AudioManager.PopRoomPreset → Restore SmallRoom]
    F --> G[Exit Room A]
    G --> H[SS_AudioManager.PopRoomPreset → Restore Default/Outdoor]

---

8. Room Preset Reference

Included Room Presets (in Content/Framework/Audio/RoomPresets/)

Preset Asset	Description	Typical Use
DA_RoomAcousticPreset	Base class	Parent for all presets
DA_RP_SmallRoom	Small room reverb	Offices, bedrooms, closets
DA_RP_LargeHall	Large hall reverb	Auditoriums, churches, lobbies
DA_RP_Outdoor	Outdoor (minimal reverb)	Default fallback, streets, forests
DA_RP_Cave	Cave/underground reverb	Caves, tunnels, basements
DA_RP_VoidSpace	Void/alt death space reverb	Alt death space, dream sequences
DA_RP_Industrial	Industrial/factory reverb	Factories, warehouses, hangars
DA_RP_Bathroom	Small tile reverb	Bathrooms, tiled corridors

---

9. Communication Matrix

Who Talks	How	What Is Sent
BP_RoomAudioZone	SS_AudioManager.SetRoomPreset()	DA_RoomAcousticPreset, crossfade time
BP_RoomAudioZone	SS_AudioManager.PopRoomPreset()	(none — restores previous from stack)
BP_RoomAudioZone	Dispatcher: OnPlayerEnteredZone	FName ZoneName (for gameplay scripting)
BP_RoomAudioZone	Dispatcher: OnPlayerExitedZone	FName ZoneName
Level Designer	Direct placement in world	Adjusts RoomPreset, Priority, TransitionTime in Details Panel
Narrative System	SetRoomAudioEnabled(false)	Disables zone during cutscenes/void space

---

10. Validation / Testing Checklist

• Player entering zone triggers SetRoomPreset with correct preset
• Reverb parameters smoothly crossfade over TransitionTime
• Player exiting zone triggers PopRoomPreset restoring previous room
• Nested zones: entering inner room, exiting restores outer room
• Priority: higher priority zone overrides lower priority when overlapping
• SetRoomAudioEnabled(false) during overlap — zone is disabled
• SetRoomAudioEnabled(true) after disable — zone reapplies
• Non-player actors do NOT trigger zone overlap
• Zone with null RoomPreset logs warning and remains inactive
• bShowDebugInfo logs enter/exit to console
• Zone destroyed while player inside — PopRoomPreset still called
• Edge case: Rapid enter/exit (player on boundary) — no audio glitching
• Edge case: SS_AudioManager not found — zone gracefully handles missing subsystem
• Edge case: Multiple zones with same Priority — last-entered wins

---

11. Reuse Notes

• Place multiple BP_RoomAudioZone actors throughout a level to create realistic acoustic transitions.
• Use Priority to handle overlapping zones — higher values override. Example: a bathroom (Priority=5) inside a house (Priority=0).
• bOverrideOcclusion enables per-source occlusion line traces in this zone — useful for walls, doors.
• The OnPlayerEnteredZone / OnPlayerExitedZone dispatchers allow gameplay logic to react to room changes (e.g., "You've entered the forbidden wing" audio sting).
• Zone scaling: Box components can be scaled to any size. Use multiple zones for irregularly shaped rooms.
• Debug mode (bShowDebugInfo + ZoneDebugColor) helps level designers visualize acoustic boundaries.

---

Blueprint Spec: BP_RoomAudioZone — Trigger volume for automatic room acoustic switching. Architecture document: metasounds-audio-system.md Section 6.