Best Practices

Use the Debug Overlay During Development

Enable the debug_overlay option in the client config while developing your pack.

The debug overlay displays:

• Active tracks per layer
• Silence and suppression states
• Current track volume

This makes it much easier to understand why a track is (or isn’t) playing and helps diagnose priority, condition, or cooldown issues.

Use Namespaces Consistently

Always prefix your resources with your modpack namespace:

• ✅ "assets/my_pack/music"
• ❌ "assets/maestro/music"

Use Clear and Descriptive Naming

Choose file names that describe their purpose at a glance and naturally group related definitions together.

Prefer names that reflect what the music reacts to, not vague or generic concepts:

• ✅ "music/underscore/biome.frozen_ocean.json"
• ✅ "music/encounter/entity.wither.json"

Avoid names that hide intent or lump unrelated logic together:

• ❌ "music/some_biomes.json"
• ❌ "music/boss_music.json"