User Guide

Everything you need to build adaptive music: layers, volumes, stingers, configs, and persistence.

NOTE: Prerequisites Make sure you've completed the Getting Started guide first.

Music Volumes

The easiest way to add music to your game — no Blueprints needed.

Setup

Place Actor → Search ERP Music Volume → drag into your level
Resize the box collision to cover your area
Configure in the Details panel:
- Layer Name: "Dungeon" (unique name)
- Music: Select your music asset
- Priority: 5
- Layer Mode: Replace

When the player enters the volume → music plays. When they leave → previous music returns.

Spawning Inside Volumes

Issue: By default, volumes only trigger when actors enter or exit them. If a player spawns inside a volume, the music won't start automatically.

Solution: Add the ERP Music Volume Detector component to your player/pawn:

Open your player Blueprint (e.g., BP_ThirdPersonCharacter)
Click Add Component → Search ERP Music Volume Detector
Done!

Now music triggers correctly when spawning inside volumes (initial spawn, respawns, multiplayer joins, etc.).

How it works: The component performs a direct geometry check 0.1 seconds after spawn to detect any volumes the player is inside, then manually triggers them. This bypasses Unreal's overlap event system which may not fire when spawning inside a volume.

Nested Volumes

Music volumes work with the priority system. If the player enters a higher-priority volume inside a lower one:

[Forest Volume - Priority 5]
  └─ [Cave Volume - Priority 8]
       └─ Player is here → Cave music plays

Player walks out of cave → Forest music returns
Player walks out of forest → Previous music returns

Stingers

Short musical accents that play over your current music — perfect for achievements, discoveries, item pickups.

Event OnTreasureFound
  ↓
Play Stinger
  ├─ Sound: Achievement_Fanfare
  ├─ Duck Music: true        // Lower background music
  ├─ Duck Volume: 0.3        // Music at 30% during stinger
  └─ Restore Fade Time: 0.5  // Fade back after

Stingers don't interrupt the current music. They play on top, optionally ducking the background.

Stinger Volume

A placeable actor (ERP_StingerVolume) that plays a stinger when the player enters its box collision — like Music Volumes but for stingers. Yellow wireframe in editor.

Place Actor → Search ERP Stinger Volume → drag into your level
Resize the box collision to cover your trigger area
Configure in the Details panel:

Category	Property	Description
Stinger \| Sound	`Stinger Sound`	The stinger audio to play
Stinger \| Ducking	`bDuck Music`	Lower background music during stinger
Stinger \| Ducking	`Duck Volume`	Music volume during stinger (0.0–1.0)
Stinger \| Ducking	`Duck Fade Time`	Time to fade music down
Stinger \| Ducking	`Restore Fade Time`	Time to restore music after stinger
Stinger \| Timing	`Quantization`	Beat sync: None, Beat, or Bar
Stinger \| Behavior	`Actor Filter Tag`	Only trigger for actors with this tag
Stinger \| Behavior	`bTrigger Once`	Fire only on first overlap

Note: Like Music Volumes, stingers only trigger when entering/exiting by default. Add the ERP Music Volume Detector component to your player to trigger stingers when spawning inside them.

No Blueprints needed — place, configure, done.

Audio Ducking

Automatically lower music during important audio — dialogue, cutscenes, narration, SFX, etc.:

Event OnImportantAudio
  ↓
Spawn Sound 2D (your audio)
  ↓ [Audio Component output]
Enable Audio Ducking
  ├─ Audio Component: [from above]
  ├─ Duck Volume: 0.4   // Music at 40%
  └─ Fade Time: 0.3

Music automatically restores when the audio finishes. No cleanup needed. Perfect for dialogue, cinematic moments, voiceovers, or any sound that should be the focus.

Additive Layers

Use Additive mode to play sounds on top of your main music — tension strings, rain, wind, heartbeats.

// Base exploration music already playing (Replace, Priority 0)

Event OnEnemyNearby
  ↓
Push Music Layer
  ├─ Layer Name: "Tension"
  ├─ Music: Tension_Strings
  ├─ Priority: 5
  ├─ Layer Mode: Additive  // Plays ON TOP
  ├─ Volume: 0.6
  └─ Quantization: Next Beat

Event OnEnemyLeft
  ↓
Pop Music Layer
  ├─ Layer Name: "Tension"
  └─ Quantization: Next Bar

Rules:

Additive layers only play if their priority ≥ the current Replace layer
Multiple Additive layers can play simultaneously
Use Replace for main music, Additive for atmosphere

Music Presets

Save layer setups as reusable DataAssets — great for areas that need multiple layers at once.

Create a Preset

Content Browser → Right-click → Miscellaneous → Data Asset
Choose ERP_MusicLayerPreset
Name it MC_DungeonAmbiance

Configure Layers

Preset Name: "Dungeon Ambiance"

Layers:
  [0] Layer Name: "DungeonBase"
      Music: Dungeon_Base_Loop
      Priority: 0
      Mode: Replace

  [1] Layer Name: "DungeonWind"
      Music: Dungeon_Wind
      Priority: 2
      Mode: Additive
      Volume: 0.6

Push It

Event OnEnterDungeon
  ↓
Push Music Preset
  ├─ Preset: MC_DungeonAmbiance
  ├─ Clear Existing: true
  └─ Quantization: Next Bar

All layers activate at once. Use Clear Existing: true to remove previous layers first.

Volume Control

Master Volume

Set Master Music Volume
  ├─ Volume: 0.5     // 50%
  └─ Fade Time: 1.0

Per-Layer Volume

Set when pushing:

Push Music Layer
  └─ Volume Multiplier: 0.8  // 80% of master

Or change at runtime:

Set Layer Volume
  ├─ Layer Name: "Combat"
  └─ Volume: 0.5

Quantization (Beat-Synchronized Transitions)

Make music transitions happen exactly on beat using the optional Quantization parameter. Perfect for smooth, musical changes that don't interrupt the rhythm.

How It Works

All Push and Pop functions now support an optional Quantization parameter:

Push Music Layer
  ├─ Layer Name: "Combat"
  ├─ Music: Combat_Theme
  ├─ Priority: 10
  └─ Quantization: Next Bar  ← Wait for next bar

Quantization Options

Option	Waits for	Best for
`None`	Nothing (immediate)	Default behavior, instant transitions
`Beat`	Next beat (1/4 note)	Quick, tight transitions
`HalfBar`	Next half bar (2 beats)	Medium transitions
`Bar`	Next full bar (4 beats)	Music changes, most common
`TwoBars`	2 full bars (8 beats)	Dramatic moments, section changes

When to Use Quantization

Use Next Bar for:

Combat music starting/ending
Area transitions (entering dungeons, boss arenas)
Musical mood changes
Preset transitions

Use Next Beat for:

Quick reactions (taking damage, pickups)
Additive layers that should blend quickly
Stingers that need beat alignment

Use None (default) for:

Sound effects
Non-musical audio
Immediate stops (game over, pause)

Example: Combat System

Event OnCombatStart
  ↓
Push Music Layer
  ├─ Layer: "Combat"
  ├─ Priority: 10
  └─ Quantization: Bar  ← Starts on next bar

Event OnCombatEnd
  ↓
Pop Music Layer
  ├─ Layer: "Combat"
  └─ Quantization: Bar  ← Stops on next bar

Tip: Quantization uses the Quartz clock (auto-created at 120 BPM). Change BPM with Set Music BPM — see Advanced Features.

Persistence

Keep music playing across level transitions:

Push Music Layer
  └─ Persist Across Levels: true

The music subsystem is a GameInstanceSubsystem — it lives as long as the game runs. Persistent layers survive level loads, streaming, and map transitions.

Use for: Menu music, world ambiance, anything that shouldn't restart on level change.

Best Practices

Priority Guidelines

Range	Use for	Examples
0	Base/default music	Exploration, menu
1-5	Volumes and areas	Dungeon, village, forest
5-10	Gameplay states	Combat, stealth
10-15	Important events	Boss fight, cutscene
15+	Critical moments	Final boss, game over

Do's and Don'ts

Do:

Name layers clearly: "Combat", "BossPhase2", "ForestAmbient"
Always pop layers when done
Use Replace for main music, Additive for atmosphere
Test with music.debug console command

Don't:

Push the same layer name twice (it's ignored)
Forget to pop layers (they stay in the stack)
Use very long fade times (>5s feels sluggish)
Use Additive for main music changes

Next Steps

Advanced Features — MetaSound, Quartz beat sync, GameplayTags
API Reference — All Blueprint functions
Troubleshooting — Common issues

Music Volumes​

Setup​

Spawning Inside Volumes​

Nested Volumes​

Stingers​

Stinger Volume​

Audio Ducking​

Additive Layers​

Music Presets​

Create a Preset​

Configure Layers​

Push It​

Volume Control​

Master Volume​

Per-Layer Volume​

Quantization (Beat-Synchronized Transitions)​

How It Works​

Quantization Options​

When to Use Quantization​

Example: Combat System​

Persistence​

Best Practices​

Priority Guidelines​

Do's and Don'ts​

Next Steps​