Sound Configuration

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

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

Field	Default	Description
`name`	(required)	The sound’s registered name.
`src`	(required)	Path to the audio file, relative to your mod’s folder (e.g. `assets/audio/effects/hit.mp3`). A leading `/` is tolerated and stripped, but writing the path without one is clearest — it is not an absolute filesystem path.
`preload`	`false`	Whether to fully decode the sound into memory at load time (see Preload vs Streaming below).
`category`	`sfx`	One of `music`, `creatures`, `ambient`, `sfx` — controls which volume slider affects it. Any other value is a load error.

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).

Volume Categories

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

Category	Use
`music`	Background music tracks.
`creatures`	Mob sounds (hurt, death, ambient noises).
`ambient`	Environmental/world ambience.
`sfx`	Everything else — UI, item use, block breaking, etc.

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