Boss Music lets modpack creators control what players hear and when they hear it. Drop your own Ogg Vorbis files into the config folder, then connect them to bosses, phases, books, structures, world conditions, player state, commands, or server-side events.

The mod includes simple JSON files for common use cases, an advanced rule engine for complex soundscapes, an in-game Audio Studio, and tools for discovering how modded bosses represent their phases. It does not ship copyrighted songs and it does not generate speech: you provide the audio you have permission to distribute.

✨ Highlights

📦 Supported Versions and Loaders

Boss Music 2.1.0 has a separate build for each supported Minecraft and mod-loader combination. Choose exactly one file for your instance; the files are not universal or interchangeable.

• Fabric builds require Fabric API.
• NeoForge builds for 26.1 and 26.1.1 currently target beta NeoForge releases.
• The optional Configuration integration is not available in every combination; Boss Music's JSON files and Audio Studio still work without it.
• When using server-backed structure detection or server cues, install the same Minecraft, loader, and Boss Music build on both sides.

🚀 Quick Start

1. Install the Boss Music file matching your exact Minecraft version and loader.
2. For Fabric, install the matching Fabric API release.
3. Start Minecraft once to generate config/bossmusic/.
4. Place your Ogg Vorbis .ogg files in config/bossmusic/music/.
5. Open a world and press F8, or run /bossmusic studio.
6. Create or edit a rule, validate its audio paths, preview it, and save.
7. Run /bossmusic validate and test the result in a disposable world before shipping your pack.

Boss Music scans audio folders recursively, so large packs can keep their files organized:

config/bossmusic/
├── music/
│   ├── bosses/warden/intro.ogg
│   ├── bosses/warden/phase_1.ogg
│   ├── bosses/warden/phase_2.ogg
│   └── narration/ancient_city.ogg
├── tracks.json
├── books.json
├── structures.json
├── bossmusic-pack.schema.json
├── packs/
│   └── example.json
└── recordings/

Paths inside JSON are relative to the music/ directory, for example bosses/warden/phase_1.ogg. Boss Music creates a virtual resource pack at runtime, so users do not need to build a separate Minecraft resource pack for these files. Long tracks are streamed from disk.

⚙️ Configurations & Features

Simple Boss Configuration

The classic tracks.json format is the quickest way to add boss music, presentations, and phases:

{
  "tracks": [
    {
      "entity": "minecraft:warden",
      "music": [
        "bosses/warden/phase_1_a.ogg",
        "bosses/warden/phase_1_b.ogg"
      ],
      "voice": "bosses/warden/presentation.ogg",
      "radius": 48,
      "volume": 1.0,
      "category": "record",
      "music_mode": "loop",
      "voice_mode": "once",
      "fade_in": 40,
      "fade_out": 60,
      "mute_other_music": true,
      "require_line_of_sight": false,
      "phases": [
        {
          "health_below": 0.5,
          "music": "bosses/warden/phase_2.ogg",
          "voice": "bosses/warden/phase_2_intro.ogg"
        }
      ]
    }
  ]
}

The nearest matching living entity inside its configured radius controls the classic boss track. Optional line-of-sight detection can require the player to see the entity. A short grace period prevents teleporting or briefly unloaded bosses from cutting the music immediately.

music and voice accept either one path or a list of alternatives. Lists select an alternative for the encounter; they do not play every file simultaneously.

Detecting Boss Phases

Health-based phases use a fraction from 0.0 to 1.0. Many modded bosses also expose their real phase through Minecraft's synchronized entity data:

{
  "when": {
    "data_id": 17,
    "type": "int",
    "equals": "2"
  },
  "music": "bosses/example/final_phase.ogg",
  "voice": "bosses/example/final_phase_name.ogg"
}

There is no universal phase value shared by every Minecraft boss. Use the scanner or recorder to inspect the actual entity. Prefer stable booleans or integers and avoid animation counters that change continuously. Classic phases only advance during the same encounter; healing the boss does not move the soundtrack back to an earlier phase.

Book Narration

books.json matches written books by title, author, text, or a combination. Narration also works for books opened from a lectern.

{
  "books": [
    {
      "title": "The Lost Expedition",
      "author": "Archivist",
      "text_contains": "beneath the ancient city",
      "audio": "books/lost_expedition.ogg",
      "playback_mode": "once",
      "volume": 1.0,
      "category": "voice",
      "stop_on_close": true
    }
  ]
}

All supplied matchers must match. The mod plays a recording you provide; it is not a text-to-speech engine. Use /bossmusic book while holding a book to inspect its title, author, and page count.

Structure Music and Narration

structures.json can attach a soundtrack and a discovery narration to a registered structure:

{
  "structures": [
    {
      "structure": "minecraft:ancient_city",
      "music": "structures/ancient_city.ogg",
      "narration": "structures/ancient_city_discovery.ogg",
      "music_mode": "loop",
      "narration_mode": "once",
      "volume": 0.8,
      "fade_in": 40,
      "fade_out": 60,
      "mute_other_music": true
    }
  ]
}

Exact structure detection uses the structure's real bounds and requires Boss Music on the logical server and the client. The server sends structure IDs only; audio remains local to each player. Install the audio and JSON files in every client through your modpack.

Advanced Modular Rule Packs

Files in config/bossmusic/packs/*.json provide the complete rule engine. They load in filename order and can contain any number of rules. Each pack has its own namespace and metadata, making it practical to distribute compatibility packs for different mods.

{
  "$schema": "../bossmusic-pack.schema.json",
  "pack": {
    "id": "my_pack",
    "name": "My Modpack Soundtrack",
    "author": "Pack Team",
    "version": "1.0.0",
    "license": "CC-BY-4.0",
    "enabled": true
  },
  "rules": [
    {
      "id": "warden_final_phase",
      "priority": 200,
      "exclusive_group": "main_music",
      "activation_delay_seconds": 1,
      "cooldown_seconds": 10,
      "minimum_active_seconds": 5,
      "when": {
        "all": [
          { "structure": "minecraft:ancient_city" },
          {
            "entity": "minecraft:warden",
            "radius": 48,
            "health_below": 0.5
          }
        ]
      },
      "audio": {
        "intro": "warden/phase_intro.ogg",
        "body": ["warden/final_a.ogg", "warden/final_b.ogg"],
        "stinger": "warden/phase_stinger.ogg",
        "outro": "warden/phase_outro.ogg",
        "mode": "loop",
        "shuffle": true,
        "fade_in": 40,
        "fade_out": 60,
        "volume": 1.0,
        "category": "record",
        "mute_other_music": true,
        "subtitle": "The Warden enters its final phase."
      }
    }
  ]
}

Available Conditions

Rules in the same exclusive_group compete by priority, while different groups can play as intentional layers. Activation delays filter flickering conditions, minimum-active windows prevent rapid switching, and cooldowns limit repeated activation.

Playback and Mixing

Supported Minecraft volume categories are master, music, record, weather, block, hostile, neutral, player, ambient, and voice. The record category is useful when you want custom music to have a slider independent of vanilla background music.

🎛️ Creator Tools

Audio Studio 2.1

Press F8 or run /bossmusic studio inside a world. The guided editor contains pages for:

• Pack identity, author, license, rule ID, priority, and group.
• Entity, detection radius, health threshold, and synchronized data.
• Intro, body, stinger, outro, playback mode, and interval.
• Volume, category, fades, music muting, and subtitles.

You can add and remove phase rules, validate IDs and paths, preview available audio, open the config folder, and save with the button or Ctrl+S. The editor may save an incomplete draft after warning you, which is useful while building a pack. Audio Studio configures playback; it is not a music-composition or waveform-editing application.

Boss Scanner and Encounter Recorder

Look directly at a boss and use these tools when its internal phase system is unknown:

/bossmusic debug scan
/bossmusic debug values
/bossmusic debug clear

/bossmusic record start
/bossmusic record mark
/bossmusic record status
/bossmusic record stop
/bossmusic record cancel

The manual scanner compares synchronized values before and after a visible transition. The recorder follows one entity through a fight and captures health, synchronized data, pose, effects, invulnerability, nearby sound events, nearby summons, and defeat or loss of tracking.

Stable changes are favored over noisy animation counters. A manual mark tells the analyzer when you observed a phase transition. Finishing a recording creates:

• config/bossmusic/packs/recording_<boss>_<date>.json
• config/bossmusic/recordings/recording_<boss>_<date>.md

The generated pack is deliberately disabled and uses placeholder audio paths. Review every detector, add real audio, validate the draft, and enable it yourself. The recorder suggests candidates; it cannot guarantee that an internal value represents a real gameplay phase. It records events and metadata, not microphone audio.

Commands

The record and phase-debug commands listed in the previous section are also client commands. A malformed modular pack is isolated so valid packs can continue loading; use /bossmusic validate to see all reported issues.

Server Cues and Modpack Scripting

With Boss Music installed on both the server and clients, permission-level-two commands can activate rule IDs for selected players:

/bossmusicserver play my_pack:quest_finale @a
/bossmusicserver play my_pack:danger @a[distance=..64]
/bossmusicserver stop my_pack:quest_finale @a

Command blocks, datapack functions, quest systems, KubeJS, CraftTweaker, or other scripting mods can invoke these commands without a direct code dependency on Boss Music. The exact method for executing a server command depends on the external scripting mod and Minecraft version.

A Java API is also available for server and client integrations. The server transmits a rule ID and shared start time; every client resolves the actual Ogg file from its local pack. Clients that do not expose the optional Boss Music network channel are skipped.

🔌 Optional Integrations

When a compatible release of the Configuration mod is installed, Boss Music can register a traditional configuration screen with classic slots for bosses, books, and structures. Modular files in packs/*.json remain independent and do not have that fixed slot count.

Note: Do not install a Configuration build made for another Minecraft version just to force this integration. Boss Music's JSON system and Audio Studio do not require Configuration.

🖥️ Client vs Server Installation

• Client only: local boss music, voice introductions, book narration, Audio Studio, scanning, recording, and client-side conditions.
• Client and server: exact registered-structure detection, synchronized server cues, and /bossmusicserver.

The network channel is optional for ordinary connections, but server-backed features require a compatible channel on both sides. Cross-loader networking has not been certified; use the same loader and build on the client and server for these features.

🛠️ Troubleshooting & Performance

Performance Recommendations

• Use practical entity radii, normally 32 to 64 blocks.
• Add activation delays to conditions that fluctuate rapidly.
• Avoid hundreds of unrestricted entity rules with very large radii.
• Use reasonable Ogg Vorbis bitrates; lossless-quality source audio is unnecessary for long background tracks.
• Keep layered groups at moderate volumes and use ducking for important narration.

📜 Modpack Use and Audio Licensing