Feature/v2.0.0 arrangement

[norz3n]

RenPy Dynamic Ambient System v2.0.0 - Release Notes

🎉 Major Changes

1. YAML Configuration

What changed: Complete migration from Python-based configuration to YAML files.

Before:

# ambient_config.rpy
$ ambient.add_track("forest_wind", "audio/wind.ogg", "mandatory", 0.6)
$ ambient.add_track("birds", "audio/birds.ogg", "random", 0.4, 0.3)

After:

# audio_assets.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

---

2. Creator-Defined Statements (CDS)

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

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

Available commands:

Arrangement Control

# Play arrangement
ambient play "forest_morning"
ambient play "forest_night" fade 5.0

# Stop system
ambient stop

Layer Control

# Enable layer
ambient layer "rain" on

# Disable layer with fade
ambient layer "rain" off fade 2.0

Volume and Control

# Set volume (0.0 - 1.0)
ambient volume 0.5

# Pause/Resume
ambient pause
ambient resume

Scheduling

# Schedule arrangement to start in N seconds
ambient schedule "storm_approaching" in 60.0

Debugging

# Show information
ambient debug info

# Toggle Debug UI
ambient debug ui

Benefits:

• Cleaner and more readable script code
• No need for $ python_code blocks
• IDE autocompletion support
• Syntax checking at compile time

---

3. Arrangement System

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

File: arrangements.yaml

Example:

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:

# Python API
$ ambient.play_arrangement("forest_morning")
$ ambient.set_layer("rain", True, fade=3.0)

# CDS
ambient play "forest_morning"
ambient layer "rain" on fade 3.0

---

4. Strict Track Isolation

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:

# Playing forest_morning (wind + birds)
ambient play "forest_morning"

# When switching to cave_ambient
ambient play "cave_ambient"
# wind and birds automatically stop
# Only cave_ambient tracks start playing

---

5. Random Containers

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

Configuration:

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

---

6. Automatic Initialization

What changed: System automatically loads configuration on creation.

Before:

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

After:

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

---

7. Enhanced Debugging

What's new: Extended debugging tools.

Debug UI:

# Toggle visual debug
ambient debug ui

Shows:

• Active tracks and their volume
• Current arrangement
• Active layers
• System runtime
• Wave system state

Debug commands:

ambient debug info      # Basic information
ambient debug runtime   # Runtime duration
ambient debug tracks    # All tracks state

---

📋 Migration from v1.x

Step 1: Install Dependencies

# Install PyYAML in game/python-packages
pip install pyyaml -t game/python-packages

Step 2: Create YAML Configurations

audio_assets.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:

arrangements:
  arrangement_name:
    tracks:
      track_id: { volume: 0.8 }
    
    layers:
      layer_name:
        layer_track_id: { volume: 0.6 }
    
    duration: 300
    auto_next: "next_arrangement"

Step 3: Remove Obsolete Files

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

Step 4: Update Code

Before:

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:

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

Step 5: Optional CDS Installation

If you need ambient command support:

Copy libs/rpda/ to game/libs/rpda/

---

🔧 Technical Details

File Structure

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)

Backward Compatibility

Python API preserved:

$ 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

---

🎯 Recommendations

For New Projects

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

For Existing Projects

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

---

📊 Version Comparison

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

---

🐛 Known Limitations

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.

---

📝 Changelog

Added

• ✅ 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

Changed

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

Removed

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

Fixed

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

---

🙏 Acknowledgments

Thanks to everyone who tested and provided feedback!

---

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