[DCME] Dynamic Contextual Music Engine

A contextual music engine for Minecraft 1.20.1 (Fabric)

DCME replaces Minecraft's vanilla music system with a fully dynamic, context-aware soundtrack. Music adapts in real time to what you're doing: exploring, fighting, caving, facing a boss, or watching the credits roll.

---

⚠️ Important: Resource Pack Required

DCME is a music engine and does not include music tracks by default.

• Usage: You must install a compatible Resource Pack to hear music in-game.
• Finding Packs: Search for the keyword [DCME] on CurseForge, Modrinth, or other platforms to find community-made soundtracks.
• For Creators: If you create a music pack, please add [DCME] to your project title so users can find it easily!

---

Contextual Music

The mod evaluates dozens of conditions every second and plays the right music for the moment:

• Overworld - Day, night, dawn, and dusk each have their own soundtrack
• Weather - Rain triggers a dedicated atmosphere
• Underground - Caves and the Deep Dark get unique music
• Dimensions - Nether and The End have distinct soundscapes
• Combat (PVE) - Dynamic music kicks in when hostile mobs target you
• Combat (PVP) - Music triggers for both attacker and victim, with team protection and configurable timeout
• Bosses - Wither, Ender Dragon, and Elder Guardian each have dedicated boss themes
• Screens - Main menu and credits have their own music

Smooth Transitions

• 3 transition modes - Crossfade (default: simultaneous fade), Gap (silence between tracks), or Hybrid (crossfade within same group, gap between groups)
• Combat overlay - Base music fades to near-silence while combat plays, then resumes exactly where it left off when the fight ends
• Boss fights - Base music is released during long boss encounters to free resources; a fresh track starts after the fight
• Dimension transitions - Audio state resets cleanly when entering portals, preventing zombie sounds or slot leaks
• End-of-track fade - Tracks fade out gracefully near the end instead of stopping abruptly

PVP Combat Detection

DCME tracks player-vs-player combat using a server-side attack tracker. When a player hits another player, both the attacker and victim receive the PVP combat music signal.

• Bidirectional - Both players get combat music, not just the attacker
• Team protection - Players on the same scoreboard team won't trigger PVP music against each other. Compatible with vanilla teams, PartyAddon, and any mod that uses Minecraft's scoreboard team system
• Configurable timeout - Music stays active for a configurable duration after the last hit (default: 5 seconds), preventing music from cutting in and out during pauses between swings
• Multiplayer-ready - Handles any number of simultaneous PVP fights correctly

Play Once (with Smart Groups)

Contexts can be set to play_once, which lets the current track finish before transitioning. This only applies within the same group - changing dimension or going from surface to underground always crossfades immediately, even if play_once is enabled.

Groups: overworld_surface, overworld_underground, nether, end, screen, combat, boss

Fully Configurable

• JSON config at config/dcme.json - master volume, fade durations, gap between tracks, combat radius, PVP timeout, team protection, per-context toggles, time thresholds, and more
• In-game config screen via Mod Menu - toggle every context on/off, adjust PVP settings, and change transition modes without editing files
• Per-context overrides - each context can define its own volume, fade times, and gap duration

100% Customizable via Resource Packs

Every aspect of the music system is data-driven:

• Replace tracks - Swap any OGG file via a resource pack
• Add new contexts - Create new JSON files to define entirely new music triggers
• Override existing contexts - Replace any default context with your own version
• Custom conditions - Biome, dimension, time of day, weather, altitude, sky light, combat, boss, structure, season, advancement, and more

No Java code changes needed. See the included example resource pack for a complete guide. Don't forget to search for the [DCME] tag to find new music packs!

Config Folder Overrides

For power users: drop context JSONs into config/dcme/contexts/ to override any context without a resource pack. Highest priority - overrides both JAR defaults and resource packs.

Third-Party Music Blocking

DCME automatically blocks other mods from playing their own music to prevent conflicts. By default, all non-DCME music is blocked. You can customize this per-namespace in config/dcme.json. Jukebox music (music discs) is never blocked.

---

Context Priority System

Higher priority contexts override lower ones. The override layer (combat/boss) runs independently from the base layer (biome/dimension).

Context	Priority	Layer	Group
Ender Dragon	100	Override	boss
Wither	95	Override	boss
Elder Guardian	90	Override	boss
Combat (Warden)	85	Override	combat
Combat (Generic)	80	Override	combat
Credits	70	Base	screen
Menu	60	Base	screen
Deep Dark	50	Base	overworld_underground
Underground	40	Base	overworld_underground
Rain	38	Base	overworld_surface
Dawn	22	Base	overworld_surface
Dusk	22	Base	overworld_surface
Night	20	Base	overworld_surface
Day / Nether / End	10	Base	(varies)

---

Technical Details

• Fabric mod for Minecraft 1.20.1 (Java 17)
• Requires Fabric API
• Optional: Mod Menu for in-game config screen
• Compatible with Serene Seasons / Fabric Seasons (season-based music)
• Compatible with Sound Physics Remastered, AmbientSounds, and other sound mods
• Compatible with PartyAddon and any team mod using scoreboard teams for PVP team protection
• Third-party music blocking via SoundManager mixin - prevents conflicts with mods like Aquamirae that play their own music
• Includes a Mixin to increase the streaming sound pool (+5 slots), preventing conflicts with mods that use many simultaneous sounds
• Smart streaming slot management: combat holds the base track for seamless resume; boss fights release the slot to prevent resource exhaustion
• PVP attack tracker - server-side event-driven detection using Fabric's AttackEntityCallback, no polling or stale state
• Optimized evaluation - context conditions evaluated once per second (20 ticks), not every tick. GameStateSnapshot avoids redundant world lookups
• OGG duration pre-caching - all track durations loaded async at startup and cached to disk for instant subsequent launches
• Structure detection cache persists to disk - previously explored structures are remembered across sessions
• Server component for aggro detection, PVP tracking, structure detection, advancement sync, and season detection
• Client-only music playback - no server lag

---

Requirements

• Minecraft 1.20.1
• Fabric Loader 0.15+
• Fabric API 0.92+
• (Optional) Mod Menu 7.x for config screen
• A compatible [DCME] Resource Pack