Migration from v1

Migration from v1.x

Guide for upgrading from Dynamic Ambient System v1.x to v2.0.0.

---

Overview of Changes

What's New in v2.0.0

Feature	v1.x	v2.0.0
Configuration	Python code	YAML files
Control	Python API only	CDS + Python API
Arrangements	❌	✅
Layers	❌	✅
Auto-transitions	❌	✅
Random Containers	❌	✅
Strict Isolation	Partial	Full
Auto-initialization	❌	✅

What's Removed

• ambient.add_track() — Use YAML configuration
• ambient.use_template() — Use arrangements
• ambient_config.rpy — Replaced by audio_assets.yaml
• ambient_templates.rpy — Replaced by arrangements.yaml
• Manual setup_ambient calls — Now automatic

---

Step-by-Step Migration

Step 1: Install PyYAML

pip install pyyaml -t game/python-packages
# or
uv pip install pyyaml --target game/python-packages

Step 2: Create audio_assets.yaml

Convert your ambient_config.rpy track definitions:

Before (v1.x):

label setup_ambient:
    $ ambient.add_track("forest_base", "audio/forest.ogg", "mandatory", 0.6)
    $ ambient.add_track("birds", "audio/birds.ogg", "random", 0.4, 0.3, 30, 90)
    $ ambient.add_track("wind", "audio/wind.ogg", "random", 0.5, 0.25, 45, 120)
    return

After (v2.0.0):

# game/audio_assets.yaml
tracks:
  forest_base:
    file: "audio/forest.ogg"
    type: "mandatory"
    volume: 0.6

  birds:
    file: "audio/birds.ogg"
    type: "random"
    volume: 0.4
    chance: 0.3
    interval: [30, 90]

  wind:
    file: "audio/wind.ogg"
    type: "random"
    volume: 0.5
    chance: 0.25
    interval: [45, 120]

Step 3: Create arrangements.yaml

Before (v1.x):

# No arrangement concept - tracks played directly
label forest_scene:
    $ ambient.stop_ambient()
    $ ambient.add_track("forest_base", ...)
    $ ambient.add_track("birds", ...)
    $ ambient.start_ambient()

After (v2.0.0):

# game/arrangements.yaml
arrangements:
  forest:
    tracks:
      forest_base: { volume: 0.6 }
      birds: { volume: 0.4 }
      wind: { volume: 0.5 }

label forest_scene:
    ambient play "forest"

Step 4: Convert Main Theme

Before (v1.x):

label setup_main_theme:
    $ ambient.set_main_theme("audio/theme.mp3", 60, 0.8, 2.0, 3.0)
    return

After (v2.0.0):

# In audio_assets.yaml
main_theme:
  file: "audio/theme.mp3"
  duration: 60
  volume: 0.8
  fade_in: 2.0
  fade_out: 3.0
  after_theme_arrangement: "main_menu"

Step 5: Update Script Code

Before (v1.x):

label start_main_menu_ambient:
    call setup_ambient
    call setup_main_theme
    $ ambient.start_with_main_theme()
    return

label forest_location:
    $ ambient.stop_ambient()
    $ ambient.add_track("forest_base", "audio/forest.ogg", "mandatory", 0.6)
    $ ambient.add_track("birds", "audio/birds.ogg", "random", 0.4, 0.3)
    $ ambient.start_ambient()

After (v2.0.0):

label start_main_menu_ambient:
    # Configuration is automatic
    $ ambient.start_with_main_theme()
    return

label forest_location:
    ambient play "forest"
    # Or: $ ambient.play_arrangement("forest")

Step 6: Convert Templates to Arrangements

Before (v1.x):

init python:
    ambient_templates = {
        "forest": [
            {"track_id": "forest_base", "filename": "audio/forest.ogg", ...},
            {"track_id": "birds", "filename": "audio/birds.ogg", ...},
        ],
        "city": [
            {"track_id": "traffic", "filename": "audio/traffic.ogg", ...},
        ],
    }

$ ambient.use_template("forest")

After (v2.0.0):

# arrangements.yaml
arrangements:
  forest:
    tracks:
      forest_base: { volume: 0.6 }
      birds: { volume: 0.4 }

  city:
    tracks:
      traffic: { volume: 0.5 }

ambient play "forest"
ambient play "city"

Step 7: Remove Obsolete Files

Delete or archive:

• ambient_config.rpy
• ambient_templates.rpy
• Any custom setup labels

Step 8: Install CDS (Optional)

For ambient command support:

game/
└── libs/
    └── rpda/
        └── 02-rpda-cds.rpy

---

API Changes

Removed Methods

v1.x Method	v2.0.0 Replacement
add_track()	YAML configuration
use_template()	play_arrangement()

Changed Methods

Method	Change
set_main_theme()	Still works, but prefer YAML
start_ambient()	Still works, but prefer arrangements

New Methods

Method	Description
play_arrangement()	Play a defined arrangement
set_layer()	Control arrangement layers
schedule_arrangement()	Schedule future transition
load_config()	Reload YAML configuration

---

Common Migration Issues

"No module named 'yaml'"

Install PyYAML:

pip install pyyaml -t game/python-packages

Tracks Not Playing

• Ensure tracks are defined in audio_assets.yaml
• Ensure tracks are included in arrangement
• Check file paths are correct

"Arrangement not found"

• Check arrangement is defined in arrangements.yaml
• Check spelling matches exactly
• Reload config if YAML was modified

Volume Differences

v2.0.0 uses volume multipliers in arrangements:

final_volume = track_volume × base_volume × arrangement_multiplier

Adjust arrangement volumes if sounds are too quiet/loud.

Random Tracks Behave Differently

v2.0.0 has stricter wave system. Random tracks:

• Start at minimum volume
• Only elevate during waves
• Respect strict isolation

---

Gradual Migration

You can migrate gradually:

Phase 1: Add YAML Files

Create audio_assets.yaml and arrangements.yaml alongside existing code.

Phase 2: Test New System

Test arrangements work correctly.

Phase 3: Update Scripts

Replace add_track() calls with play_arrangement().

Phase 4: Remove Old Code

Delete obsolete files and setup labels.

---

Keeping Python API

The Python API still works for complex scenarios:

# Still valid in v2.0.0
$ ambient.play_arrangement("forest")
$ ambient.set_layer("rain", True)
$ ambient.set_base_volume(0.5)
$ ambient.pause_ambient()
$ ambient.resume_ambient()
$ ambient.stop_ambient()

Use Python API when you need:

• Dynamic arrangement names
• Complex conditional logic
• Integration with game systems

Use CDS for:

• Simple, linear scripts
• Quick prototyping
• Cleaner script readability

---

Rollback Plan

If migration fails, you can temporarily revert:

1. Keep old ambient_config.rpy
2. Remove YAML files
3. Remove CDS files
4. System falls back to manual configuration

However, v2.0.0 features (arrangements, layers) won't be available.