Maestro

Music Definitions

Updated 2026-02-12

Music definitions describe what music should play and under which in-game conditions. Each definition is evaluated dynamically, and the one with the highest priority that matches the current game state is selected.

Basic Definition

JSON Example

1 {

2 "priority": 0,

3 "layer": "underscore",

4 "sound_event": "minecraft:music_disc.pigstep",

5 "cooldown_seconds": 0,

6 "occupy_layer_during_cooldown": true,

7 "reset_cooldown_on_reactivation": false,

8 "condition": {

9 "type": "maestro:always"

10 }

11 }

priority

Integer

Determines priority within the same layer. Higher values take precedence over lower ones.

layer

Enum

Target music layer. Supported values: underscore, encounter.

sound_event

Identifier

Reference to a sound event (namespace:path).

cooldown_seconds

Integer Optional

Time after the track finishes playing naturally before it can play again (in seconds). Defaults to 0.

occupy_layer_during_cooldown

Boolean Optional

Keeps the track valid during cooldown, occupying the layer with silence. Defaults to true.

reset_cooldown_on_reactivation

Boolean Optional

Resets the cooldown when the track becomes valid again after its condition was false. Defaults to false.

condition

MusicCondition

Defines when this music definition is considered valid.

Note
reset_cooldown_on_reactivation only works when occupy_layer_during_cooldown is enabled. If disabled, the track is not selected during cooldown, so it cannot be re-selected and the cooldown will never reset.

Example: Biome & Weather Based Definition

JSON Example

{
  "priority": 100,
  "layer": "underscore",
  "sound_event": "example:music.blizzard",
  "condition": {
    "type": "maestro:all_of",
    "terms": [
      {
        "type": "maestro:biome",
        "values": [ 
          "minecraft:snowy_beach",
          "minecraft:frozen_ocean" 
        ]
      },
      {
        "type": "maestro:weather",
        "is_snowing": true
      }
    ]
  }
}

This definition plays the custom blizzard music track when the player is located in either the Snowy Beach or Frozen Ocean biome and it is currently snowing.