v2.1.0: Independent Music & Ambient Channels

Major Audial Architecture Upgrade
This release completely decouples Music and Ambient audio streams, enabling independent control and mixing.

Key Features:
* Split Channel Architecture: Music mixer handles melodic tracks, Ambient mixer handles SFX loops. Users can now adjust volumes independently.
* Enhanced Configuration: audio_assets.yaml now supports 'music:' and 'ambient:' sections for logical separation. (Backward compatibility for 'tracks:' preserved).
* Granular CDS Commands: New syntax for 'ambient volume' and 'ambient stop' allows targeting specific categories (music/ambient) independently.
* UI Integration: Added native support for separate volume sliders and improved settings menu integration.

Documentation:
* Extensive Wiki updates covering the new independent channel architecture, updated API references, and migration guides.

Fixes:
* Resolved UI conflicts in integration scripts.
* Unified channel registration logic for better stability.

v2.1.0 - Save/Load Fix

Fixed TypeError: cannot pickle '_thread.lock' object when saving game.
Changed ambient system declaration from 'default' to 'define' to exclude threading objects from Ren'Py serialization.
Added state restoration callbacks for save/load compatibility.

Retry for example project

- **Demo Project Added**: The release archive now includes `RPDA_Demo…

…_Project` (located in the `example/` folder). It demonstrates how to integrate and configure the dynamic ambient system.

- **CI/CD Updated**: The release script has been updated to automatically include the example folder in the final zip archive.

- Core library files (`dynamic_ambient.rpy`, `ambient_integration.rpy`, etc.)
- `example/` folder with a ready-to-use project for learning.

1. Download the archive.
2. Extract it into your projects folder.
3. Check `example/RPDA_Demo_Project` for a quick start.

feat: Implement YAML configuration, Creator-Defined Statements, and a…

…n arrangement system for dynamic ambient audio, including a fix for the audio assets filename.

**What changed:** Complete migration from Python-based configuration …

…to YAML files.

**Before:**
```python
$ ambient.add_track("forest_wind", "audio/wind.ogg", "mandatory", 0.6)
$ ambient.add_track("birds", "audio/birds.ogg", "random", 0.4, 0.3)
```

**After:**
```yaml
tracks:
  forest_wind:
    file: "audio/wind.ogg"
    type: "mandatory"
    volume: 0.6

  birds:
    file: "audio/birds.ogg"
    type: "random"
    volume: 0.4
    chance: 0.3
```

**Benefits:**
- More readable configuration
- Easier to edit without Python knowledge
- Separation of data and logic
- Support for comments and structure

---

**What's new:** New commands for controlling ambient directly from Ren'Py scripts.

**File:** `libs/rpda/02-rpda-cds.rpy`

**Available commands:**

```renpy
ambient play "forest_morning"
ambient play "forest_night" fade 5.0

ambient stop
```

```renpy
ambient layer "rain" on

ambient layer "rain" off fade 2.0
```

```renpy
ambient volume 0.5

ambient pause
ambient resume
```

```renpy
ambient schedule "storm_approaching" in 60.0
```

```renpy
ambient debug info

ambient debug ui
```

**Benefits:**
- Cleaner and more readable script code
- No need for `$ python_code` blocks
- IDE autocompletion support
- Syntax checking at compile time

---

**What's new:** Concept of "arrangements" - preset audio scenes.

**File:** `arrangements.yaml`

**Example:**
```yaml
arrangements:
  forest_morning:
    tracks:
      forest_wind: { volume: 0.6 }
      birds: { volume: 0.8 }
      morning_insects: { volume: 0.3 }

    # Optional layers
    layers:
      rain:
        rain_light: { volume: 0.7 }
        rain_drops: { volume: 0.5 }

    # Automatic transition
    duration: 300  # 5 minutes
    auto_next: "forest_day"
```

**Features:**
- **Base tracks:** Main audio scene
- **Layers:** Additional elements that can be toggled on/off
- **Auto-transitions:** Automatic arrangement switching (Intro → Loop)
- **Parameter overrides:** Can change track type or parameters for specific arrangements

**Usage:**
```renpy
$ ambient.play_arrangement("forest_morning")
$ ambient.set_layer("rain", True, fade=3.0)

ambient play "forest_morning"
ambient layer "rain" on fade 3.0
```

---

**What improved:** Tracks not in current arrangement are automatically stopped.

**Before:** Tracks could "leak" between arrangements, creating overlaps.

**After:** System guarantees only tracks defined in active arrangement and its layers play.

**Example:**
```renpy
ambient play "forest_morning"

ambient play "cave_ambient"
```

---

**What's new:** Ability to specify multiple files for one track.

**Configuration:**
```yaml
tracks:
  random_birds:
    files:
      - "audio/bird1.ogg"
      - "audio/bird2.ogg"
      - "audio/bird3.ogg"
    type: "random"
    volume: 0.5
```

**Behavior:** Each time the track plays, one file is randomly selected.

**Benefits:**
- More variety
- Less repetition
- Single ID for group of similar sounds

---

**What changed:** System automatically loads configuration on creation.

**Before:**
```renpy
label start_main_menu_ambient:
    call setup_ambient
    call setup_main_theme
    $ ambient.start_with_main_theme()
```

**After:**
```renpy
label start_main_menu_ambient:
    # Configuration loaded automatically from YAML
    $ ambient.start_with_main_theme()
```

**What happens automatically:**
- Loading `audio_assets.yaml`
- Loading `arrangements.yaml`
- Registering all tracks
- Setting up main menu theme

---

**What's new:** Extended debugging tools.

**Debug UI:**
```renpy
ambient debug ui
```

**Shows:**
- Active tracks and their volume
- Current arrangement
- Active layers
- System runtime
- Wave system state

**Debug commands:**
```renpy
ambient debug info      # Basic information
ambient debug runtime   # Runtime duration
ambient debug tracks    # All tracks state
```

---

```bash
pip install pyyaml -t game/python-packages
```

**audio_assets.yaml:**
```yaml
tracks:
  # Move all ambient.add_track() calls here
  track_id:
    file: "audio/file.ogg"
    type: "mandatory"  # or "random"
    volume: 0.7
    # For random tracks:
    chance: 0.3
    interval: [30, 120]
    fade_in: 3.0
    fade_out: 3.0

main_theme:
  file: "audio/theme.mp3"
  duration: 60
  volume: 0.8
  fade_in: 2.0
  fade_out: 3.0
  after_theme_arrangement: "main_menu_ambient"
```

**arrangements.yaml:**
```yaml
arrangements:
  arrangement_name:
    tracks:
      track_id: { volume: 0.8 }

    layers:
      layer_name:
        layer_track_id: { volume: 0.6 }

    duration: 300
    auto_next: "next_arrangement"
```

- ❌ `ambient_config.rpy` (replaced by `audio_assets.yaml`)
- ❌ `ambient_templates.rpy` (functionality moved to arrangements)
- ❌ Manual `setup_ambient` and `setup_main_theme` calls

**Before:**
```renpy
label forest_scene:
    $ ambient.stop_ambient()
    $ ambient.add_track("wind", "audio/wind.ogg", "mandatory", 0.6)
    $ ambient.add_track("birds", "audio/birds.ogg", "random", 0.4)
    $ ambient.start_ambient()
```

**After:**
```renpy
label forest_scene:
    # Tracks already defined in audio_assets.yaml
    # Arrangement defined in arrangements.yaml
    ambient play "forest_morning"
```

If you need `ambient` command support:
```
Copy libs/rpda/ to game/libs/rpda/
```

---

```
game/
├── dynamic_ambient.rpy          # Core system
├── ambient_auto_start.rpy       # Auto-start in main menu
├── ambient_integration.rpy      # Settings UI
├── debug_ambient.rpy            # Debug overlay
├── audio_assets.yaml            # Track configuration
├── arrangements.yaml            # Arrangement configuration
└── libs/
    └── rpda/
        └── 02-rpda-cds.rpy      # CDS implementation (optional)
```

**Python API preserved:**
```python
$ ambient.play_arrangement("name")
$ ambient.set_layer("layer", True)
$ ambient.set_base_volume(0.5)
$ ambient.pause_ambient()
$ ambient.resume_ambient()
```

**What's removed:**
- `ambient.add_track()` - now only via YAML
- `ambient.use_template()` - replaced by arrangements
- Manual initialization - now automatic

---

1. Use YAML configuration
2. Use CDS for control
3. Organize sounds via arrangements
4. Use layers for dynamic elements

1. Gradually migrate to YAML
2. Keep Python API for complex logic
3. Use CDS for simple switches
4. Test for compatibility

---

| Feature | v1.x | v2.0.0 |
|---------|------|--------|
| Configuration | Python | YAML |
| Control | Python API | CDS + Python API |
| Arrangements | ❌ | ✅ |
| Layers | ❌ | ✅ |
| Auto-transitions | ❌ | ✅ |
| Random Containers | ❌ | ✅ |
| Strict Isolation | ⚠️ | ✅ |
| Auto-initialization | ❌ | ✅ |
| Debug UI | Basic | Enhanced |

---

1. **Fade time in `ambient stop`:** Command `ambient stop fade X` ignores specific time, uses maximum from tracks.
2. **CDS Lint:** Arrangement names not checked at lint time (loaded from YAML at runtime).
3. **Debug UI variable:** `toggle_ambient_debug` must be defined in `debug_ambient.rpy` for `ambient debug ui` to work.

---

- ✅ YAML configuration (`audio_assets.yaml`, `arrangements.yaml`)
- ✅ Creator-Defined Statements (CDS)
- ✅ Arrangement system with layer support
- ✅ Automatic transitions between arrangements
- ✅ Random containers (multiple files per track)
- ✅ Automatic initialization from YAML
- ✅ Enhanced Debug UI

- 🔄 Strict track isolation between arrangements
- 🔄 Improved smooth transition system
- 🔄 Redesigned documentation (README.md)

- ❌ `ambient_config.rpy` (replaced by YAML)
- ❌ `ambient_templates.rpy` (replaced by arrangements)
- ❌ Manual initialization (`setup_ambient`, `setup_main_theme`)

- 🐛 Track leaks between arrangements
- 🐛 State synchronization issues after reload
- 🐛 Channel registration with `default ambient`

---

Thanks to everyone who tested and provided feedback!

---

**Version:** 2.0.0
**Release Date:** 2025-11-27
**License:** MIT