Sound Configuration

Register named sound effects and music tracks, controlling preload behavior and volume category.

Sounds are named audio clips your mod can play — sound effects, ambient loops, and music. This is the catalog file that registers them; everywhere else in the game (Lua scripts, item use, mob events) references a sound by its registered name.

File Location

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

sound-config: sound-config.yaml

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

mods/<YourMod>/sound-config.yaml

The file is a single list of sound entries:

sounds:
  - name: my_sound
    src: assets/audio/effects/my-sound.mp3

Sound names are automatically prefixed with your mod name unless you write one already containing a colon, so my_sound becomes YourMod:my_sound — this is the full name used anywhere the sound is played.

Minimal Example

sounds:
  - name: my_sound
    src: assets/audio/effects/my-sound.mp3
    preload: true
    category: sfx

Fields

Keys are validated strictly: a misspelled or unknown field (e.g. catagory, prelaod) or an unrecognized category value stops that sound from loading, with the offending key named in the log rather than being silently dropped — see Unknown Fields. Check your logs if an entry doesn’t register.

If src doesn’t resolve to a real file, the sound is still registered under its name (so nothing else fails to load because of it) but is silently skipped whenever something tries to play it — check your logs for a warning if a sound doesn’t seem to play.

Preload vs. Streaming

• preload: true — the file is fully decoded into memory when the mod loads. Costs load time and memory up front, but has no per-play decode delay. Use for short, frequently-triggered sounds (UI clicks, footsteps, hits).
• preload: false (default) — the file is streamed from disk each time it’s played. Cheaper to load, but not instant to start. Use for long tracks played rarely (music, ambient loops).

Overriding another mod’s sound

Adding a new sound for your own content needs nothing special — just register it and it becomes YourMod:your_sound. To instead replace a sound another mod (or the base game) already registered — a different hit sound, your own boss music — give your entry an override set to that sound’s full Mod:name id:

sounds:
  - name: my_ouch
    src: assets/audio/effects/my-ouch.mp3
    preload: true
    category: creatures
    override: Creation:ouch   # your file now plays wherever Creation:ouch is triggered

Your entry keeps its own src (the audio file that plays) but registers under the target id instead of YourMod:my_ouch, so anything that plays Creation:ouch now plays your clip. This mirrors the override field on texture configs.

• The target must be fully qualified (Creation:ouch, not ouch) — it is used verbatim, exactly as the sound is named where it’s played.
• Load order decides the winner. Mods load in alphabetical order and the last one to write a given id wins, so your mod must sort after the mod whose sound it overrides. Overriding a base-game (Creation:…) sound works from any mod that sorts after Creation.
• An override does not also register the sound under YourMod:my_ouch — it only claims the target id.

Volume Categories

Each category has its own volume slider in the audio settings menu, independent of the master volume:

Complete Example

Based on real shipped sounds:

sounds:
  - name: chest_open
    src: assets/audio/effects/chest-open.mp3
    preload: true
    category: sfx

  - name: ouch
    src: assets/audio/effects/ouch.mp3
    preload: true
    category: creatures

  - name: boss_music
    src: assets/audio/music/boss-music.mp3
    preload: false
    category: music

Last updated Aug 25, 2026