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