ZoneAudio

ZoneAudio

ZoneAudio adds custom location-based music and ambience zones to Valheim.

Create zones in a YAML config file, drop audio files into the mod's audio folder, and ZoneAudio will fade tracks in and out as the player moves through those areas.

Features

• YAML-based zone configuration
• Live reload when zones.yaml is saved
• Smooth edge fading near zone boundaries
• Vanilla music suppression while ZoneAudio is active
• Volume follows Valheim's Music setting (in addition to zone and mod volume controls)
• Single-track zones or multi-track playlists
• Optional shuffle playback
• Optional day/night audio
• Optional biome and weather conditions
• Priority support for overlapping zones

Installation

Install with a -compatible mod manager, or install manually by placing the DLL in:

BepInEx/plugins/ZoneAudio/

On first launch, ZoneAudio creates:

BepInEx/config/ZoneAudio/

zones.yaml

audio/

Put your.ogg,.wav, or.mp3 files in the audio folder.

Basic Config

Only three fields are required:

zones:

• position: [1250, 34, -820]

radius: 20

audio: harbor.ogg

That creates one audio zone centered at x=1250, y=34, z=-820, with a radius of 20 meters.

Full Example

zones:

• name: Harbor Tavern

position: [1250, 34, -820]

radius: 20

audio: harbor.ogg

volume: 0.8

priority: 100

biome: Meadows

weather:

• Clear
• LightRain

onlyDay: false

onlyNight: false

loop: true

shuffle: false

edgeFade: 10

Playlists

Use a list under audio to queue multiple tracks:

zones:

• name: Market

position: [100, 30, -200]

radius: 35

audio:

• market_1.ogg
• market_2.ogg
• market_3.ogg

shuffle: true

loop: true

ZoneAudio also accepts simple bare entries under list fields:

audio:

market_1.ogg

market_2.ogg

With shuffle: true, ZoneAudio plays through the playlist in random order without repeating a track until the current shuffle set is used.

Day And Night Audio

Use dayAudio and nightAudio for different music by time of day:

zones:

• name: Village Square

position: [300, 40, -500]

radius: 45

audio: village_default.ogg

dayAudio:

• village_day.ogg

nightAudio:

• village_night.ogg

If dayAudio or nightAudio is missing, ZoneAudio falls back to audio.

Config Fields

Required:

• position: zone center as [x, y, z]
• radius: zone radius in meters
• audio: one file name or a list of file names

Optional:

• name: label used in logs
• volume: zone volume from 0.0 to 1.0, default 1.0
• priority: higher priority wins when zones overlap, default 0
• biome: only play in this biome
• weather: only play during listed weather names
• onlyDay: only play during day, default false
• onlyNight: only play during night, default false
• loop: loop playback, default true
• shuffle: shuffle playlist playback, default false
• edgeFade: fade distance in meters near the zone edge
• dayAudio: daytime-specific file or playlist
• nightAudio: nighttime-specific file or playlist

Notes

The YAML file reloads live while the game is running. If the file has a syntax error, ZoneAudio logs the problem and keeps the last working zone list active.

Audio files are loaded from:

BepInEx/config/ZoneAudio/audio/

The mod can migrate an older zones.json file into zones.yaml if no YAML file exists yet.