Arrangements YAML

Arrangements YAML

The arrangements.yaml file defines audio scene presets with track configurations and optional layers.

---

File Location

game/arrangements.yaml

---

Basic Structure

arrangements:
  arrangement_name:
    tracks:
      track_id: { volume: 0.8 }
    
    # Optional
    layers:
      layer_name:
        track_id: { volume: 0.6 }
    
    # Optional
    duration: 60.0
    auto_next: "next_arrangement"

---

Arrangement Parameters

tracks (Required)

Dictionary of track configurations:

arrangements:
  my_scene:
    tracks:
      forest_base: { volume: 0.6 }
      birds: { volume: 0.5 }

Each track entry can have:

Parameter	Type	Description
volume	float	Volume multiplier (applied to base volume)
type	string	Override track type ("mandatory" or "random")
fade_in	float	Override fade in time
fade_out	float	Override fade out time
play_chance	float	Override chance (for random tracks)
min_duration	float	Override minimum duration
max_duration	float	Override maximum duration

layers (Optional)

Named groups of additional tracks:

arrangements:
  outdoor:
    tracks:
      base: { volume: 0.5 }
    
    layers:
      rain:
        rain_sound: { volume: 0.7 }
        thunder: { volume: 0.5 }

duration (Optional)

How long the arrangement plays before auto-transitioning:

arrangements:
  intro:
    duration: 30.0    # 30 seconds
    auto_next: "main"
    tracks:
      intro_music: { volume: 0.8 }

auto_next (Optional)

Arrangement to transition to after duration:

arrangements:
  intro:
    duration: 10.0
    auto_next: "loop"    # Switches to "loop" after 10 seconds

---

Track Configuration Options

Simple Volume

tracks:
  my_track: { volume: 0.8 }

Full Override

tracks:
  my_track:
    volume: 0.9
    type: "mandatory"      # Override type
    fade_in: 2.0           # Override fade in
    fade_out: 1.0          # Override fade out
    play_chance: 0.8       # Override chance (if random)
    min_duration: 20       # Override min duration
    max_duration: 60       # Override max duration

---

Layer Structure

Layers allow dynamic addition/removal of track groups:

arrangements:
  base_scene:
    tracks:
      ambient: { volume: 0.5 }
    
    layers:
      weather_rain:
        rain: { volume: 0.7 }
        rain_drops: { volume: 0.4 }
      
      weather_storm:
        thunder: { volume: 0.8 }
        heavy_rain: { volume: 0.9 }
        wind: { volume: 0.7, type: "mandatory" }
      
      tension:
        heartbeat: { volume: 0.3 }
        drone: { volume: 0.4 }

Layer Usage

ambient play "base_scene"

# Add rain
ambient layer "weather_rain" on

# Add storm (can have multiple layers)
ambient layer "weather_storm" on

# Remove rain
ambient layer "weather_rain" off fade 2.0

---

Auto-Transition Patterns

Intro → Loop

arrangements:
  music_intro:
    duration: 15.0
    auto_next: "music_loop"
    tracks:
      intro_track: { volume: 0.8 }

  music_loop:
    tracks:
      loop_track: { volume: 0.7 }

Sequence Chain

arrangements:
  phase_1:
    duration: 60.0
    auto_next: "phase_2"
    tracks:
      track_a: { volume: 0.5 }

  phase_2:
    duration: 60.0
    auto_next: "phase_3"
    tracks:
      track_b: { volume: 0.6 }

  phase_3:
    # No auto_next - stays here
    tracks:
      track_c: { volume: 0.7 }

Day Cycle

arrangements:
  dawn:
    duration: 300.0
    auto_next: "morning"
    tracks:
      dawn_birds: { volume: 0.4 }

  morning:
    duration: 300.0
    auto_next: "midday"
    tracks:
      morning_ambient: { volume: 0.6 }

  midday:
    duration: 300.0
    auto_next: "evening"
    tracks:
      cicadas: { volume: 0.5 }

  evening:
    duration: 300.0
    auto_next: "night"
    tracks:
      crickets: { volume: 0.4 }

  night:
    duration: 300.0
    auto_next: "dawn"
    tracks:
      night_ambient: { volume: 0.3 }

---

Complete Example

# arrangements.yaml

arrangements:
  # === MAIN MENU ===
  
  main_menu:
    tracks:
      menu_ambient: { volume: 0.5 }
      menu_atmosphere: { volume: 0.3 }

  # === FOREST LOCATION ===
  
  forest_intro:
    duration: 10.0
    auto_next: "forest_day"
    tracks:
      forest_base: { volume: 0.3 }

  forest_day:
    tracks:
      forest_base: { volume: 0.6 }
      birds: { volume: 0.5 }
      wind_leaves: { volume: 0.4 }
    
    layers:
      rain:
        rain_light: { volume: 0.6 }
        rain_drops: { volume: 0.4 }
      
      storm:
        thunder: { volume: 0.8 }
        heavy_rain: { volume: 0.9 }
        wind_leaves:
          volume: 1.0
          type: "mandatory"

  forest_night:
    tracks:
      forest_base: { volume: 0.4 }
      crickets: { volume: 0.5 }
      owl: { volume: 0.3 }

  # === CITY LOCATION ===
  
  city_street:
    tracks:
      traffic: { volume: 0.5 }
      crowd_murmur: { volume: 0.3 }
      car_horns: { volume: 0.4 }
    
    layers:
      busy:
        crowd_murmur: { volume: 0.6 }
        car_horns: { volume: 0.6 }
      
      quiet:
        traffic: { volume: 0.3 }
        # crowd_murmur not included - won't play

  city_night:
    tracks:
      traffic: { volume: 0.3 }
      distant_sirens: { volume: 0.4 }

  # === SPECIAL SCENES ===
  
  tension_building:
    tracks:
      drone: { volume: 0.4 }
      heartbeat: { volume: 0.3 }
    
    layers:
      high_tension:
        drone: { volume: 0.7 }
        heartbeat: { volume: 0.5 }
        stinger: { volume: 0.6 }

  combat:
    tracks:
      combat_music: { volume: 0.8, type: "mandatory" }
      impacts: { volume: 0.5 }

---

Best Practices

Naming Conventions

• Use descriptive names: forest_day, city_night
• Group related arrangements: forest_*, city_*
• Use clear layer names: rain, storm, tension

Track Selection

• Only include tracks relevant to the scene
• Use strict isolation to your advantage
• Don't include every track in every arrangement

Volume Balancing

• Test arrangements together
• Leave headroom for layers
• Consider the cumulative volume of all tracks

Layer Design

• Keep layers focused (weather, tension, etc.)
• Layers can override base track settings
• Multiple layers can be active simultaneously

---

Validation

Check console for errors:

DynamicAmbientSystem: Configuration loaded successfully.

Or errors like:

Arrangement 'invalid_name' not found.
Layer 'missing_layer' not found in arrangement 'scene'.