Troubleshooting

Solutions to common issues with ElysMusicEngine.

General Debugging

Step 1: Use Console Commands

Open console (~ key) and try:

music.debug

This shows:

All active layers
Their priorities
Which ones are playing
Current master volume

Step 2: Check Output Log

Window → Developer Tools → Output Log

Look for:

ERP Music Subsystem Initialized (plugin loaded)
Pushed music layer: LayerName (layer added)
Started playing layer: LayerName (music started)
Warnings about missing assets or invalid states

Music Not Playing

Symptom

You call Push Music Layer but hear nothing.

Solutions

1. Check Plugin Enabled

Edit → Plugins → Search "Elys Music Engine"

(Success) Must be enabled
Restart editor if you just enabled it

2. Verify Music Asset

Double-click music asset in Content Browser
Does it play?
If not → Reimport or use different asset

3. Check Layer Already Active

Branch: Is Layer Active("YourLayerName")
  If TRUE: Layer already playing (Push ignored)
  If FALSE: Should work

Fix: Pop the layer first, or use different name.

4. Check Master Volume

Console: music.debug

Look for Master Volume: 0.0 → That's your problem!

Fix:

Set Master Music Volume
  - Volume: 1.0

5. Check Layer Volume

When pushing layer:

Volume Multiplier: Should be 1.0 (not 0.0)

6. Check Audio Settings

Edit → Project Settings → Audio

Master Volume: Should be > 0
Audio Device: Should be valid

Music Volume Not Triggering on Spawn

Symptom

You place a Music Volume in your level and set your Player Start inside it, but music doesn't play when the game starts. Walking into/out of the volume works fine.

Cause

Music Volumes (and Stinger Volumes) only trigger on overlap events — when actors enter or exit the volume. If an actor spawns inside, no overlap event fires.

Solution

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

Open your player Blueprint (e.g., BP_ThirdPersonCharacter, BP_FirstPersonCharacter)
Click Add Component
Search for ERP Music Volume Detector
Add it to your character

That's it! Now music volumes trigger correctly when:

Spawning at game start
Respawning after death
Joining multiplayer sessions
Teleporting into volumes

Advanced: Adjust Detection Timing

If volumes still don't trigger (very rare), increase the detection delay:

Select the ERP Music Volume Detector component
In Details panel → Check Delay: Change from 0.1 to 0.2 or 0.3

This gives the actor more time to fully initialize before checking for volumes. The detector performs a direct point-in-box geometry test (rotation-aware), so collision initialization delays are usually not an issue.

Music Stops Abruptly

Symptom

Music cuts off suddenly instead of fading.

Solutions

1. Increase Fade Times

When pushing layer:

Fade Out Time: Increase to 1.5 or 2.0 seconds
Fade In Time: Match the fade out time

2. Check Pop Timing

If you Pop a layer immediately after Push:

The fade might not complete
Add delay or check if already active first

3. Check Clear All Layers

Clear All Music Layers stops everything immediately:

Use Pop Music Layer for graceful fadeout

Wrong Music Playing

Symptom

Different music plays than expected.

Solutions

1. Check Priorities

Console: music.debug

Higher priority wins. Example:

Combat [10] Replace   ← This plays
Exploration [0]       ← This doesn't (lower priority)

Fix: Adjust priorities when pushing layers.

2. Check Layer Mode

Replace: Stops lower priority music
Additive: Adds on top (both may play)

If you want only combat music:

Mode: Replace
Priority: Higher than exploration (e.g., 10 vs 0)

3. Check Layer Names

Case-sensitive! These are different:

"Combat"
"combat"
"Combat " (trailing space)

Fix: Use consistent naming.

Music Won't Stop

Symptom

Pop Music Layer doesn't stop the music.

Solutions

1. Check Layer Name Matches

Push Music Layer
  - Layer Name: "Combat"  ← Must match exactly
  
Pop Music Layer
  - Layer Name: "Combat"  ← Same name!

Common mistake:

Push: "Combat"
Pop: "combat"  ← Wrong! Case-sensitive

2. Check Fade Out Time

Music does fade out, it just takes time:

Default: 1.0 seconds
Wait for fade to complete

Console: music.debug will show (FADING OUT) status.

3. Force Stop

If stuck, use:

Clear All Music Layers

This immediately stops everything.

Music Volumes Not Triggering

Symptom

Walk into ERP_MusicVolume but music doesn't change.

Solutions

1. Check Collision Settings

Select the ERP_MusicVolume actor:

Details Panel:

Collision Enabled: ✅ Query and Physics
Generate Overlap Events: ✅ True

Note: Music Volumes use BrushComponent - shape it however you need (box, sphere, custom).

2. Check Player Collision

Your player character:

Must have collision enabled
Must generate overlap events

3. Check Content Configuration

Make sure content is properly configured:

Single Layer: Layer Name must be set, Music asset assigned
Single Preset: Music Preset must be assigned
Layer/Preset List: List must contain valid entries
By Tag: Tags must exist in the appropriate registry (Layer or Preset)

4. Check Actor Filter Tag

If Actor Filter Tag is set:

Player must implement IGameplayTagAssetInterface
Player must have that tag
Fix: Add tag to player or leave field empty

5. Check Trigger Once

If Trigger Once: true:

Volume only triggers first time
Fix: Set to false or reset (re-enter level)

5. Visualize Volume

Select volume → Show → Collision

Should see the box bounds
Make sure it's large enough to actually hit

6. Check Output Log

Look for:

Music Volume: Pushed layer 'VolumeName'

If not there → Volume not triggering overlap.

Music Stops Between Levels

Symptom

Music stops when loading new level.

Solutions

1. Enable Persistence

When pushing layer:

Push Music Layer
  - Persist Across Levels: (Success) TRUE

2. Check Level Streaming

If using Level Streaming:

Persistence should work automatically
If not, check Audio settings (Master Volume reset?)

3. Re-Push After Load

Alternative if persistence doesn't work:

Event BeginPlay (new level)
  ↓
Check: Is Layer Active("MenuMusic")
  If FALSE:
    Push Music Layer("MenuMusic", ...)

Stingers Not Working

Symptom

Call Play Stinger but nothing happens.

Solutions

1. Check Stinger Asset

Verify sound asset is valid
Double-click to preview
Should be short (1-5 seconds typical)

2. Check Music Ducking

If bDuckMusic: true but music too loud:

Increase Duck Volume (e.g., 0.2 = very quiet)

3. Check Stinger Volume

Stinger itself might be too quiet:

Check asset volume
Increase in Sound Cue/Wave settings

4. Check Simultaneous Stingers

Only one stinger at a time:

If already playing, new stinger ignored
Future: Queue system

Audio Ducking Not Working

Symptom

Music doesn't lower during important audio (dialogue, cutscenes, narration, etc.).

Solutions

1. Check Audio Component Valid

Spawn Sound 2D (your audio)
  ↓ Audio Component pin
Branch: Is Valid?
  If Valid:
    Enable Audio Ducking

2. Check Duck Volume

0.0 = complete silence
0.5 = half volume
1.0 = no ducking (no effect)

TIP: Use 0.3 - 0.5 for best results.

3. Check Audio Finishes

Ducking restores when audio finishes:

If audio loops forever → Music stays ducked
If audio component destroyed → No restore callback

Fix: Use non-looping audio or manually restore:

Set Master Music Volume
  - Volume: 1.0

Performance Issues

Symptom

FPS drop or stuttering when music changes.

Solutions

1. Use Smaller Audio Files

Large uncompressed WAV: Slow loading
Fix: Use compressed formats (OGG Vorbis)
Or compress in Sound Wave settings

2. Reduce Layer Count

10+ active layers: Check if all needed
Fix: Consolidate layers or Pop unused

3. Check Asset Streaming

Large music files:

Enable Streaming in Sound Wave asset settings
Reduces memory, improves load times (Performance tip)

4. Preload Critical Music

In Level Blueprint:

Event BeginPlay
  ↓
Load Asset (async)
  - Asset: Your Music Asset
  ↓
(Cache in variable for later use)

Plugin Not Loading

Symptom

Plugin missing in menus or nodes not available.

Solutions

1. Check Plugin Enabled

Edit → Plugins → Search "Elys Music Engine"

If not found:

Plugin not in Plugins/ folder
Check file structure: Plugins/ElysMusicEngine/...

2. Regenerate Project Files

Right-click .uproject → Generate Visual Studio project files

3. Rebuild Project

Close editor
Build in Visual Studio (Development Editor configuration)
Reopen editor

4. Check Engine Version

Plugin requires Unreal Engine 5.0+:

Check .uplugin file: "EngineVersion": "5.0.0"
If older engine → Update or modify plugin for UE4

Audio Crackling / Distortion

Symptom

Music sounds distorted or crackly.

Solutions

1. Check Audio Device Settings

Edit → Project Settings → Platforms → Windows → Audio

Buffer Size: Increase if too low
Sample Rate: Match your music files

2. Check CPU Load

Too many layers playing?
Other systems causing hitches?

Fix: Reduce layer count or optimize other systems.

3. Check Music Asset Quality

Bitrate too low?
Compression artifacts?

Fix: Use higher quality source or adjust compression.

Preset Assets Not Working

Symptom

Push Music Preset doesn't play music.

Solutions

1. Check Preset Asset Valid

Open ERP_MusicLayerPreset asset:

At least one layer defined?
Music assets assigned?
Layer names set?

2. Check Clear Existing

Push Music Preset
  - Clear Existing: TRUE   ← Stops all current music
  - Clear Existing: FALSE  ← Adds on top of current

Choose based on your needs.

3. Check Layer Priorities

Preset layers still subject to priority rules:

Higher priority preset layers play first
Lower priority may be overridden by active layers

Blueprint Node Missing

Symptom

Can't find "Push Music Layer" or other nodes.

Solutions

1. Check Context-Sensitivity

Blueprint search is context-aware:

Disable "Context Sensitive" checkbox in search
Type: Push Music Layer

2. Check Category

All nodes in category: "ERP Music"

Search: category:ERP or category:Music

3. Refresh Nodes

Save and close Blueprint
Reopen
Try searching again

4. Check Plugin Compiled

If nodes missing after adding plugin:

Close editor
Rebuild project
Reopen editor

Common Mistakes

Mistake	Problem	Solution
Layer name typo	Pop doesn't work	Use exact same name (case-sensitive)
Priority too low	Combat doesn't override	Set combat priority higher (10 vs 0)
Replace vs Additive	Music behavior wrong	Use Replace for main, Additive for layers
Forget to Pop	Music plays forever	Always Pop when done
No Persist flag	Music stops on level load	Enable "Persist Across Levels"
Volume collision off	Volume doesn't trigger	Enable collision + overlap events

Still Need Help?

Check Other Documentation

Getting Started — Step-by-step setup
User Guide — Layers, volumes, configs
Advanced Features — MetaSound, Quartz, Tags
API Reference — All functions

Debug Checklist

Report a Bug

If you found a real bug:

Check FAB marketplace reviews/Q&A first
Provide:
- Unreal version
- Plugin version
- Minimal repro steps
- Output log excerpt
Contact support via FAB or email

Stinger Handles

Symptom: Stinger Handle is Invalid

You call Play Stinger With Handle but the returned handle is invalid or doesn't work.

Solutions

1. Check if handle is valid before using

FERP_StingerHandle Handle = MusicSys->PlayStingerWithHandle(...);

if (Handle.IsValid())  // Always check!
{
    // Safe to use
}
else
{
    // Sound may be null or loading failed
}

2. Verify the sound is loaded

if (!StingerSound || !StingerSound->IsValidLowLevel())
{
    UE_LOG(LogTemp, Error, TEXT("Stinger sound is null or invalid"));
    return;
}

3. Check stinger is still playing before controlling

if (MusicSys->IsStingerPlaying(Handle))
{
    MusicSys->PauseStinger(Handle);  // Safe to pause
}
else
{
    // Stinger already finished - handle is now invalid
}

Symptom: Loop Events Not Firing

Looping stingers don't trigger OnStingerLoopCompleted event.

Solutions

1. Verify looping is enabled

FERP_EnhancedStingerParams Params;
Params.bLoop = true;           // Must be TRUE
Params.LoopCount = 3;          // Not 0 (infinite), not 1 (no loop)
Params.LoopDelay = 0.2f;       // Delay between repeats

2. Bind the event before playing

// WRONG: Bind after playing
FERP_StingerHandle Handle = MusicSys->PlayStingerEnhanced(Params);
MusicSys->OnStingerLoopCompleted.AddDynamic(this, &AMyClass::OnLoopComplete);

// CORRECT: Bind before (or in constructor/BeginPlay)
MusicSys->OnStingerLoopCompleted.AddDynamic(this, &AMyClass::OnLoopComplete);
FERP_StingerHandle Handle = MusicSys->PlayStingerEnhanced(Params);

3. Check the event signature

// Event handler must match exactly
UFUNCTION()
void OnLoopComplete(FERP_StingerHandle Handle, int32 LoopIndex)
{
    // Handle and LoopIndex parameters required
}

Migration Guide: PlayStinger → PlayStingerWithHandle

Upgrading from old PlayStinger() to new handle-based API.

Old Code (Still Works)

// Simple stinger, no control possible
MusicSys->PlayStinger(MyStingerSound, true, 0.3f, 0.2f, 0.5f);

// No way to pause, resume, or monitor after playing

New Code (Recommended)

// Play with handle for full control
FERP_StingerHandle Handle = MusicSys->PlayStingerWithHandle(
    MyStingerSound, true, 0.3f, 0.2f, 0.5f
);

if (Handle.IsValid())
{
    // Now you can control it
    MusicSys->PauseStinger(Handle);   // Later
    MusicSys->ResumeStinger(Handle);  // Later
    MusicSys->StopStinger(Handle);    // Later
    MusicSys->SetStingerVolume(Handle, 0.5f);
}

Enhanced Parameters (Looping + Network Sync)

// Old: No looping support
PlayStinger(...);

// New: Full control with looping and network sync
FERP_EnhancedStingerParams Params;
Params.StingerSound = MyStingerSound;
Params.bDuckMusic = true;
Params.bLoop = true;
Params.LoopCount = 3;
Params.LoopDelay = 0.2f;
Params.SyncMode = ERP_EStingerSyncMode::Synchronized2D;

FERP_StingerHandle Handle = MusicSys->PlayStingerEnhanced(Params);

Event Handling

// New: React to loop/completion events
MusicSys->OnStingerLoopCompleted.AddDynamic(this, &AMyClass::OnLoopEvent);
MusicSys->OnStingerCompleted.AddDynamic(this, &AMyClass::OnFinished);

void AMyClass::OnLoopEvent(FERP_StingerHandle Handle, int32 LoopIndex)
{
    UE_LOG(LogTemp, Log, TEXT("Loop %d complete"), LoopIndex);
}

void AMyClass::OnFinished(FERP_StingerHandle Handle)
{
    UE_LOG(LogTemp, Log, TEXT("Stinger finished"));
}

Network Synchronization

// Old: Sync via PlayContext actor (deprecated)
// AERP_MusicPlayContext* PlayContext = ...;
// MusicSys->PlayStinger(...);  // No network sync

// New: Sync via GameState component (recommended)
UERP_MusicSyncComponent* SyncComp = MusicSys->GetOrCreateSyncComponent();

FERP_EnhancedStingerParams Params;
Params.StingerSound = MyStingerSound;
Params.SyncMode = ERP_EStingerSyncMode::Synchronized2D;  // All clients

FERP_StingerHandle Handle = SyncComp->SyncPlayStinger(Params);

Most issues are simple configuration problems. Use music.debug first!

General Debugging​

Step 1: Use Console Commands​

Step 2: Check Output Log​

Music Not Playing​

Symptom​

Solutions​

1. Check Plugin Enabled​

2. Verify Music Asset​

3. Check Layer Already Active​

4. Check Master Volume​

5. Check Layer Volume​

6. Check Audio Settings​

Music Volume Not Triggering on Spawn​

Symptom​

Cause​

Solution​

Advanced: Adjust Detection Timing​

Music Stops Abruptly​

Symptom​

Solutions​

1. Increase Fade Times​

2. Check Pop Timing​

3. Check Clear All Layers​

Wrong Music Playing​

Symptom​

Solutions​

1. Check Priorities​

2. Check Layer Mode​

3. Check Layer Names​

Music Won't Stop​

Symptom​

Solutions​

1. Check Layer Name Matches​

2. Check Fade Out Time​

3. Force Stop​

Music Volumes Not Triggering​

Symptom​

Solutions​

1. Check Collision Settings​

2. Check Player Collision​

3. Check Content Configuration​

4. Check Actor Filter Tag​

5. Check Trigger Once​

5. Visualize Volume​

6. Check Output Log​

Music Stops Between Levels​

Symptom​

Solutions​

1. Enable Persistence​

2. Check Level Streaming​

3. Re-Push After Load​

Stingers Not Working​

Symptom​

Solutions​

1. Check Stinger Asset​

2. Check Music Ducking​

3. Check Stinger Volume​

4. Check Simultaneous Stingers​

Audio Ducking Not Working​

Symptom​

Solutions​

1. Check Audio Component Valid​

2. Check Duck Volume​

3. Check Audio Finishes​

Performance Issues​

Symptom​

Solutions​

1. Use Smaller Audio Files​

2. Reduce Layer Count​

3. Check Asset Streaming​

4. Preload Critical Music​

Plugin Not Loading​

Symptom​

Solutions​

1. Check Plugin Enabled​

2. Regenerate Project Files​

3. Rebuild Project​

4. Check Engine Version​

Audio Crackling / Distortion​

Symptom​

General Debugging

Step 1: Use Console Commands

Step 2: Check Output Log

Music Not Playing

Symptom

Solutions

1. Check Plugin Enabled

2. Verify Music Asset

3. Check Layer Already Active

4. Check Master Volume

5. Check Layer Volume

6. Check Audio Settings

Music Volume Not Triggering on Spawn

Symptom

Cause

Solution

Advanced: Adjust Detection Timing

Music Stops Abruptly

Symptom

Solutions

1. Increase Fade Times

2. Check Pop Timing

3. Check Clear All Layers

Wrong Music Playing

Symptom

Solutions

1. Check Priorities

2. Check Layer Mode

3. Check Layer Names

Music Won't Stop

Symptom

Solutions

1. Check Layer Name Matches

2. Check Fade Out Time

3. Force Stop

Music Volumes Not Triggering

Symptom

Solutions

1. Check Collision Settings

2. Check Player Collision

3. Check Content Configuration

4. Check Actor Filter Tag

5. Check Trigger Once

5. Visualize Volume

6. Check Output Log

Music Stops Between Levels

Symptom

Solutions

1. Enable Persistence

2. Check Level Streaming

3. Re-Push After Load

Stingers Not Working

Symptom

Solutions

1. Check Stinger Asset

2. Check Music Ducking

3. Check Stinger Volume

4. Check Simultaneous Stingers

Audio Ducking Not Working

Symptom

Solutions

1. Check Audio Component Valid

2. Check Duck Volume

3. Check Audio Finishes

Performance Issues

Symptom

Solutions

1. Use Smaller Audio Files

2. Reduce Layer Count

3. Check Asset Streaming

4. Preload Critical Music

Plugin Not Loading

Symptom

Solutions

1. Check Plugin Enabled

2. Regenerate Project Files

3. Rebuild Project

4. Check Engine Version

Audio Crackling / Distortion

Symptom