Dynamic Battle Music - Complete Documentation

⚡ Quick Start Guide

Get dynamic battle music running in 5 minutes!

1 Enable the Plugin

Go to Edit → Plugins
Search for "Dynamic Battle Music"
Check Enabled and restart the editor

2 Add Component to Player

Open your Player Character Blueprint
Click Add Component
Search for "Battle Music Component"
Add it to your character

3 Assign Music Tracks

Select the Battle Music Component and in Details panel:

Calm Music — Your exploration/ambient track
Battle Music — Your combat/action track

4 Tag Your Enemies

Add the tag Enemy to all enemy actors:

Open Enemy Blueprint
Select the root component (Self)
In Details → Tags → Add "Enemy"

5 Play!

That's it! Music will automatically switch when enemies are nearby.

🎵 Calm Music

⟷

⚔️ Battle Music

💡 Auto-Start Enabled by Default

Music starts automatically when the game begins. Disable bAutoStart if you want manual control.

🔧 Component Setup

Basic Configuration

Property	Default	Description
Calm Music	None	Sound asset for exploration/peaceful state
Battle Music	None	Sound asset for combat state
Detection Radius	2000 cm (20m)	How far to detect enemies
Enemy Tag	"Enemy"	Tag used to identify enemies
Check Interval	0.5 sec	How often to scan for enemies
Fade Time	2.0 sec	Crossfade duration between tracks
State Cooldown	1.0 sec	Minimum time between state changes
Auto Start	True	Start music on BeginPlay
Initial Volume	1.0	Starting volume (0.0-1.0)

V2.0 Advanced Features

⭐ Priority System

Different music for Boss/Elite/Regular enemies. Higher priority overrides lower.

📊 Intensity Modulation

Volume scales with enemy count. More enemies = louder music.

💾 Music Memory

Resume tracks from last position instead of restarting.

💀 Dead Enemy Filtering

Automatically ignore dead enemies (requires "Dead" tag).

🔄 Music States

State Machine

State	Condition	Music Playing
Calm	No enemies in detection radius	Calm Music track
Battle	One or more enemies detected	Battle Music (or custom priority music)
Fading	Transitioning between states	Crossfading between tracks

Transition Flow

State Transition Logic

Calm State

Enemy Detected → Fading → Battle

Battle State

No Enemies → Fading → Calm

Cooldown prevents rapid state flickering

🎯 Enemy Detection

How Detection Works

Every CheckInterval seconds, performs sphere overlap
Finds all actors with EnemyTag within DetectionRadius
Filters out dead enemies (if bIgnoreDeadEnemies enabled)
Determines highest priority enemy (if priority system enabled)
Triggers state change if needed

Detection Settings

Property	Description
Detection Radius	Sphere radius in cm (2000 = 20 meters)
Enemy Tag	Tag to identify enemies (default: "Enemy")
Detection Channel	Collision channel for overlap (default: Visibility)
Check Interval	Seconds between scans (0.5 = twice per second)
Ignore Dead Enemies	Skip actors with "Dead" tag
Dead Enemy Tag	Tag identifying dead enemies (default: "Dead")

💡 Debug Visualization

Enable bShowDebug to see a colored sphere: Green = Calm, Red = Battle

⭐ Priority System

Play different music for different enemy types. Boss music overrides elite, elite overrides regular.

Priority Levels

Priority	Level	Use Case
Boss	Highest	Boss fights, major encounters
Elite	Medium	Mini-bosses, elite enemies
Regular	Lowest	Standard enemies (uses default Battle Music)

Setup Priority System

1 Enable Priority System

Check bUsePrioritySystem in component settings.

2 Configure Enemy Priorities

Add entries to EnemyPriorityConfigs array:

Enemy Tag	Priority	Custom Music
"Boss"	Boss	BossMusic_Cue
"Elite"	Elite	EliteMusic_Cue
"Enemy"	Regular	None (uses Battle Music)

3 Tag Your Enemies

Regular enemies: Tag = Enemy
Elite enemies: Tags = Enemy + Elite
Boss enemies: Tags = Enemy + Boss

📝 Priority Logic

If you're fighting 5 regular enemies and 1 boss enters, music immediately switches to boss music. When boss dies, returns to regular battle music.

📊 Intensity Modulation

Music volume scales dynamically based on how many enemies you're fighting.

Intensity Levels

Intensity	Enemy Count	Default Volume
Low	1-2 enemies	60%
Medium	3-5 enemies	80%
High	6+ enemies	100%

Configuration

Property	Default	Description
bUseIntensityModulation	false	Enable/disable feature
MinIntensityVolume	0.6	Volume at 1 enemy
MaxIntensityVolume	1.0	Volume at 6+ enemies

💡 Use Case

Creates tension that builds as more enemies join the fight. A single enemy feels like a skirmish, a horde feels epic!

📘 Blueprint Functions

Playback Control

Start Music

Begin music playback. Called automatically if bAutoStart is true.

Exec

Stop Music

Stop all music playback.

Force Battle Music

Immediately switch to battle music (ignores detection).

Force Calm Music

Immediately switch to calm music (ignores detection).

Set Music Volume

Change music volume. Useful for cutscenes or dialogue.

New Volume (0.0-1.0)

State Queries

Get Current Music State

State (EMusicState)

Get Detected Enemy Count

Count (int)

Get Current Enemy Priority

Priority (EEnemyPriority)

Get Current Intensity

Intensity (EMusicIntensity)

Utility

Reset First Enemy Flag

Reset OnFirstEnemyDetected event. Use when restarting level.

📡 Events (Delegates)

On Music State Changed

Fires when music state changes (Calm ↔ Battle).

New State (EMusicState)

Old State (EMusicState)

Use for UI updates, visual effects, gameplay changes

On First Enemy Detected

Fires ONCE when first enemy is detected (per session).

First Enemy (Actor)

Great for tutorials, achievements, first-time effects

On Music Intensity Changed

Fires when intensity level changes (Low/Medium/High).

New Intensity (EMusicIntensity)

Enemy Count

Use for visual intensity effects, screen shake, etc.

📖 How To Guides

How to: Show Combat UI When Battle Starts

Bind to On Music State Changed

New State

Switch on EMusicState →

Battle: Show Combat HUD

Calm: Hide Combat HUD

How to: Dim Music During Dialogue

Dialogue Started

Battle Music Component → Set Music Volume (0.3)

Dialogue Ended

Battle Music Component → Set Music Volume (1.0)

How to: Play Boss Music

Enable bUsePrioritySystem
Add to EnemyPriorityConfigs: Tag="Boss", Priority=Boss, CustomMusic=YourBossTrack
Add tags to boss actor: "Enemy" + "Boss"
When boss is nearby, boss music plays automatically!

How to: Mark Enemy as Dead

Enemy Death Event

Self → Tags → Add ("Dead")

Component will stop counting this enemy immediately

How to: Manual Control (Scripted Sequences)

Cutscene Start

Force Calm Music →

Set Music Volume (0.5) →

Cutscene End (Boss Appears)

Force Battle Music →

Set Music Volume (1.0) →

📚 Quick Reference

Enumerations

Enum	Values
EMusicState	Calm, Battle, Fading
EEnemyPriority	Regular, Elite, Boss
EMusicIntensity	Low (1-2), Medium (3-5), High (6+)

Read-Only State Properties

Property	Type	Description
CurrentMusicState	EMusicState	Current state (Calm/Battle/Fading)
bMusicSystemActive	bool	Is music system running
DetectedEnemyCount	int32	Number of enemies in range
CurrentEnemyPriority	EEnemyPriority	Highest priority enemy detected
CurrentIntensity	EMusicIntensity	Current intensity level
bEverDetectedEnemy	bool	Has any enemy ever been detected

FEnemyPriorityConfig Structure

Field	Type	Description
EnemyTag	FName	Tag to identify this enemy type
Priority	EEnemyPriority	Priority level (Regular/Elite/Boss)
CustomMusic	USoundBase*	Custom music for this priority (optional)

🛠️ Troubleshooting

Music doesn't play at all

Is bAutoStart enabled? Or did you call StartMusic()?
Are Calm Music and Battle Music assigned?
Is the sound asset valid? Try playing it directly in Content Browser
Check volume is > 0 (InitialVolume)

Music doesn't switch to battle

Does your enemy have the Enemy tag?
Is enemy within DetectionRadius? (default 2000cm = 20m)
Enable bShowDebug to visualize detection sphere
If using dead filtering, make sure enemy doesn't have "Dead" tag

Music switches too fast/slow

Adjust StateCooldown to prevent rapid switching
Adjust FadeTime for longer/shorter transitions
Adjust CheckInterval for detection frequency

Priority music not playing

Is bUsePrioritySystem enabled?
Is EnemyPriorityConfigs array configured?
Does your boss/elite have BOTH tags? ("Enemy" + "Boss")
Is CustomMusic assigned in the priority config?

Intensity modulation not working

Is bUseIntensityModulation enabled?
Check MinIntensityVolume and MaxIntensityVolume values
Are multiple enemies actually in detection range?

💡 Debug Tips

Enable bShowDebug for visual feedback
Bind to events and Print the values
Check DetectedEnemyCount in Details panel during play