Music Configuration

Declare the music and ambience beds the music director chooses between, the boss-theme overrides scripts push, and the director's timing.

Background music and ambience are not started by scripts. The music director decides, moment to moment, what should play from where the player is and what is happening, and this catalog is what it chooses from: beds — long looping tracks keyed to a world, a layer, a biome, the weather or the player’s home — and overrides, boss themes a script pushes on top of everything else. It also holds the director’s timing settings.

Entries name sounds by their sound-config.md id and never name an audio file, so a track is still declared exactly once.

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

music-config: music-config.yaml

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/music-config.yaml

The file has three sections, each optional:

settings: { }   # the director's timing
beds: [ ]       # what plays on each channel
overrides: [ ]  # boss themes scripts push

Ids — and the sound, biome and weather names an entry refers to — are prefixed with your mod name unless you write one already containing a colon.

Minimal Example

beds:
  - id: my_surface_bed
    channel: music
    when: { world-type: Genesis, layer: surface }
    stems:
      - sound: my_surface_track

Channels

The director runs two channels at the same time, and each plays one bed at a time:

Changing from one bed to another crossfades: the old bed fades out and stops as the new one fades in.

Beds

when

Every key you write must match for the bed to play.

Choosing a Bed

Music channel, first match wins:

1. The active boss override.
2. A home: true bed, when the player is within home-radius of their respawn anchor, in the same world, and not in a fight.
3. The most specific matching bed.
4. Silence.

Ambient channel: the most specific matching ambient bed, or silence.

Specificity: biome beats weather beats layer beats world-type, and a combination beats its parts — so for ambience, biome + weather beats biome, which beats world-type + layer, which beats world-type. Of two equally specific beds, the one from the later mod wins.

A bed that is already playing is never restarted, so walking between two biomes that share a bed has no seam. A change of layer, biome or home must last settle-ms before the bed changes, so standing in a cave mouth or at the edge of the home radius does not flip between beds; moving to another world changes immediately.

Stems and Intensity

A bed is made of stems — separate recordings of the same piece, each switched on from an intensity level:

Every stem of a bed starts together and plays for the bed’s whole life; intensity only fades stems up and down. That is what lets a fight rise out of the exploration music instead of cutting to a different track.

Intensity is combat when the player loses health, or when a mob within combat-radius blocks of them does (tamed creatures excluded; a mob type can opt out with raises-music-intensity in mob-config.md). It holds combat for combat-hold-ms after the last hit, then tension for tension-hold-ms, then returns to explore. Stems fade in over rise-ms and out over fall-ms. Scripts can hold a level with music_raise_intensity — see lua-client-sounds.md.

Stems of one bed should be the same length, sample rate and start point. A stem naming a sound that is not registered is skipped with a warning, and a bed left with no stems is dropped.

Overrides

While an override plays, the music bed fades out and stops and the ambient channel ducks by override-ambient-duck-db. A second override started on top plays instead; when it stops, the one under it resumes. When the last one stops, the bed comes back from its beginning. Switching section crossfades over section-crossfade-ms.

A section naming a sound that is not registered keeps its place and plays silence, so the numbers a script uses never shift.

Settings

A later mod’s value replaces an earlier one’s, field by field.

underground-below-y exists because a surface world marks every block in a column with that column’s surface biome, all the way down — so without it, nothing under a surface world is ever underground:

settings:
  underground-below-y:
    Genesis: 0

Overriding

To replace a bed or override another mod declared, give your entry an override set to its full id. Your entry takes its place — and its position in load order, so it also wins ties.

beds:
  - id: my_rescore
    override: Creation:some_bed
    channel: music
    when: { world-type: Genesis, layer: surface }
    stems:
      - sound: my_track

Without override, declaring an id that already exists, or an id in another mod’s namespace, is a load error.

Load Errors

Each of these skips the entry it is in, with the reason in the log:

• An unknown or misspelled key.
• weather on a music bed, or home on an ambient bed.
• A loop-end that is not after loop-start, or a negative loop-start.
• A bed with no stems, or an override with no sections.
• A duplicate id, or an id in another mod’s namespace, without override.

A settings block with a bad value changes nothing.

Complete Example

The base game’s one entry, Wickermourn’s boss theme, plus beds showing the rest of the schema:

settings:
  underground-below-y:
    Genesis: 0

beds:
  - id: my_surface_bed
    channel: music
    when: { world-type: Genesis, layer: surface }
    volume: 60
    loop-start: 12.0
    stems:
      - sound: my_surface_base
      - sound: my_surface_tension
        from: tension
      - sound: my_surface_combat
        from: combat

  - id: my_home_bed
    channel: music
    when: { world-type: Genesis, home: true }
    stems:
      - sound: my_home_track

  - id: my_rain_ambience
    channel: ambient
    when: { biome: my_biome, weather: my_rain }
    stems:
      - sound: my_rain_loop

overrides:
  - id: wickermourn
    volume: 50
    sections:
      - wickermourn_boss_music

Last updated Sep 29, 2026