DCME (Dynamic Contextual Music Engine) - Resource Pack Guide

This is an example resource pack showing how to customize DCME. You can add your own music, create new contexts, or override existing ones - all without touching any code.

Quick Start

1. Copy this folder into .minecraft/resourcepacks/
2. Add your .ogg music files in assets/dcme/sounds/your_category/
3. Register them in assets/dcme/sounds.json
4. Create or edit context JSONs in assets/dcme/music_contexts/
5. Activate the resource pack in Minecraft

Folder Structure

My-Music-Pack/
├── pack.mcmeta
├── README.md
└── assets/
    └── dcme/
        ├── sounds.json                    ← Register sound events
        ├── sounds/
        │   └── my_category/
        │       ├── track_1.ogg            ← Your music files
        │       ├── track_2.ogg
        │       └── boss_theme.ogg
        └── music_contexts/
            ├── my_new_context.json         ← New context (adds to defaults)
            ├── overworld_day.json          ← Override (same id replaces default)
            └── EXAMPLE_*.json.disabled     ← Disabled examples (ignored by mod)

Step 1: Add Sound Files

Place .ogg files (Vorbis codec) anywhere under assets/dcme/sounds/. Subdirectories become part of the path:

assets/dcme/sounds/my_overworld/peaceful_1.ogg
assets/dcme/sounds/my_overworld/peaceful_2.ogg
assets/dcme/sounds/my_boss/dragon_theme.ogg

Requirements: OGG Vorbis format, any sample rate (44100 Hz recommended), mono or stereo.

Step 2: Register in sounds.json

Each sound needs an entry in sounds.json. The key becomes the sound event ID, and "stream": true is required for music (long files).

{
  "my_overworld.peaceful_1": {
    "sounds": [
      {
        "name": "dcme:my_overworld/peaceful_1",
        "stream": true
      }
    ]
  },
  "my_overworld.peaceful_2": {
    "sounds": [
      {
        "name": "dcme:my_overworld/peaceful_2",
        "stream": true
      }
    ]
  },
  "my_boss.dragon_theme": {
    "sounds": [
      {
        "name": "dcme:my_boss/dragon_theme",
        "stream": true
      }
    ]
  }
}

Key: my_overworld.peaceful_1 → referenced as dcme:my_overworld.peaceful_1 in contexts.
Name: dcme:my_overworld/peaceful_1 → file path under sounds/ (with / not .).

Step 3: Create Contexts

Adding a New Context

Create a new JSON file in music_contexts/. The filename doesn't matter - only the "id" inside matters.

{
  "id": "cherry_grove",
  "priority": 25,
  "enabled": true,
  "group": "overworld_surface",
  "conditions": {
    "dimension": "overworld",
    "biomes": ["minecraft:cherry_grove"]
  },
  "tracks": [
    { "sound": "dcme:my_overworld.peaceful_1", "weight": 2 },
    { "sound": "dcme:my_overworld.peaceful_2", "weight": 1 }
  ],
  "play_once": true,
  "volume": 0.7,
  "fade_in_ms": 5000
}

Overriding an Existing Context

To replace the default overworld_day, create a file with "id": "overworld_day". The resource pack version completely replaces the built-in one:

{
  "id": "overworld_day",
  "priority": 10,
  "enabled": true,
  "group": "overworld_surface",
  "conditions": {
    "dimension": "overworld",
    "can_see_sky": true,
    "time_of_day": { "min": 1000, "max": 11500 }
  },
  "tracks": [
    { "sound": "dcme:my_overworld.peaceful_1", "weight": 1 },
    { "sound": "dcme:my_overworld.peaceful_2", "weight": 1 }
  ]
}

Disabling an Existing Context

Override it with "enabled": false:

{
  "id": "rain",
  "enabled": false,
  "priority": 38,
  "conditions": {},
  "tracks": []
}

Available Conditions

All conditions are AND logic. Omit any field to match anything.

Context Fields Reference

Combat vs Boss: release_base

When an override (combat/boss) activates, the base music fades to near-silence. The release_base field controls what happens to the base track's streaming slot:

release_base: false (default) - for combat contexts
The base track is held at near-zero volume. When combat ends, the base music resumes exactly where it left off - seamless transition. A 60-second safety timeout releases the slot if combat runs unusually long.

{
  "id": "combat_custom",
  "interrupt": true,
  "conditions": { "in_combat": true },
  "tracks": [...]
}

release_base: true - for boss contexts
The base track's streaming slot is freed immediately after a quick 1-second fade. This prevents resource exhaustion during long boss fights in heavy dimensions like The End. When the boss fight ends, a fresh base track starts instead of resuming.

{
  "id": "boss_custom",
  "interrupt": true,
  "release_base": true,
  "conditions": { "in_combat": true, "combat_entity": "minecraft:warden" },
  "tracks": [...]
}

Rule of thumb: Use release_base: true for any override context that lasts more than a minute (bosses, raids). Leave it false for short fights where seamless resume sounds better.

Groups & Play Once

When play_once is true, the current track finishes before transitioning - but only within the same group. Changing group always crossfades immediately.

Examples:
- Dawn → Night (same group overworld_surface) → track finishes first ✓
- Day → Nether (different groups) → crossfade immediately ✓
- Underground → Surface (different groups) → crossfade immediately ✓

You can define your own group names for custom contexts.

Priority Guide

The mod picks the highest-priority matching context. Use this as a guide:

Track Weights

The weight field controls how likely a track is to be picked. Higher weight = more frequent:

"tracks": [
  { "sound": "dcme:my.common_track", "weight": 3 },
  { "sound": "dcme:my.rare_track", "weight": 1 }
]

Common track plays ~75% of the time, rare track ~25%.

Tips

• Test quickly: Use /time set to change time of day and trigger context switches
• Debug logging: Set "debugLogging": true in config/dcme.json to see which context is active
• Biome tags: Use #namespace:tag syntax (e.g., "#minecraft:is_forest") to match multiple biomes
• Resource pack priority: If multiple resource packs define the same context ID, the highest-priority pack wins
• Config folder: For personal overrides, use config/dcme/contexts/ instead of a resource pack - it has the highest priority
• Weather detail: "rain" excludes thunderstorms, "precipitation" includes both, "snow" detects snow biomes during rain

Transition Modes

DCME supports three transition modes between base contexts (configurable in config/dcme.json):

The override layer (combat/boss) always uses fast crossfade regardless of this setting.

Third-Party Music Blocking

DCME blocks other mods from playing their own music (category MUSIC) to prevent conflicts. This is configurable in config/dcme.json:

"blockedMusicNamespaces": ["*"],     // Block ALL non-DCME music (default)
"allowedMusicSounds": []             // Whitelist specific sounds

• ["*"] — blocks all non-DCME music (recommended)
• ["aquamirae", "alexsmobs"] — block specific mods only
• [] — block nothing (allow all mod music)
• Jukebox music (RECORD category) is never blocked