Installation

Installation

This guide covers installing the RenPy Dynamic Ambient System in your Ren'Py project.

---

Prerequisites

• Ren'Py SDK: Version 8.4 or higher
• Python knowledge: Basic understanding helpful but not required
• Audio files: OGG format recommended

---

Step 1: Install PyYAML

The system requires PyYAML for configuration parsing. Install it to your game's python-packages folder.

Using pip

pip install pyyaml -t game/python-packages

Using uv (recommended)

uv pip install pyyaml --target game/python-packages

Manual Installation

1. Download PyYAML from PyPI
2. Extract and copy the yaml folder to game/python-packages/

---

Step 2: Copy Core Files

Copy the following files to your game/ directory:

Required Files

File	Description
dynamic_ambient.rpy	Core system class
audio_assets.yaml	Track configuration
arrangements.yaml	Arrangement definitions

Optional Files

File	Description
ambient_auto_start.rpy	Auto-start in main menu
ambient_integration.rpy	Settings UI screen
debug_ambient.rpy	Debug overlay

CDS Support (Optional)

For Creator-Defined Statements support:

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

---

Step 3: Project Structure

After installation, your project should look like:

game/
├── audio/
│   ├── ambient_track1.ogg
│   ├── ambient_track2.ogg
│   └── main_theme.mp3
├── libs/
│   └── rpda/
│       └── 02-rpda-cds.rpy      # Optional: CDS support
├── python-packages/
│   └── yaml/                     # PyYAML library
├── dynamic_ambient.rpy           # Core system
├── ambient_auto_start.rpy        # Optional: Auto-start
├── ambient_integration.rpy       # Optional: Settings UI
├── audio_assets.yaml             # Track configuration
├── arrangements.yaml             # Arrangement configuration
└── script.rpy                    # Your game script

---

Step 4: Create Configuration Files

audio_assets.yaml

Create game/audio_assets.yaml:

defaults:
  fade_in: 2.0
  fade_out: 2.0

tracks:
  # Define your tracks here
  base_ambient:
    file: "audio/ambient_base.ogg"
    type: "mandatory"
    volume: 0.6
    fade_in: 4.0
    fade_out: 4.0

  random_effect:
    file: "audio/effect.ogg"
    type: "random"
    volume: 0.5
    chance: 0.3
    interval: [30, 120]
    fade_in: 3.0
    fade_out: 3.0

# Optional: Main menu theme
main_theme:
  file: "audio/main_theme.mp3"
  duration: 60
  volume: 0.8
  fade_in: 2.0
  fade_out: 4.0
  after_theme_arrangement: "main_menu"

arrangements.yaml

Create game/arrangements.yaml:

arrangements:
  main_menu:
    tracks:
      base_ambient: { volume: 0.6 }
      random_effect: { volume: 0.5 }

---

Step 5: Verify Installation

Test in Ren'Py

Add to your script.rpy:

label start:
    "Testing ambient system..."
    
    # Using CDS (if installed)
    ambient play "main_menu"
    
    # Or using Python API
    # $ ambient.play_arrangement("main_menu")
    
    "Ambient should be playing now."
    
    ambient stop
    
    "Test complete."
    return

Check Console Output

When Ren'Py starts, you should see:

DynamicAmbientSystem: Registering X ambient channels.
DynamicAmbientSystem: Configuration loaded successfully.

---

Troubleshooting Installation

"No module named 'yaml'"

• Ensure PyYAML is installed in game/python-packages/
• Check the folder structure: game/python-packages/yaml/__init__.py should exist

"Configuration loaded" but no sound

• Verify audio file paths in audio_assets.yaml
• Check that audio files exist in the specified locations
• Ensure files are in a supported format (OGG recommended)

CDS commands not recognized

• Verify libs/rpda/02-rpda-cds.rpy exists
• Ensure Ren'Py version is 8.5.0+ for CDS support
• Restart Ren'Py after adding CDS files

Channels not registering

• Check for errors in the console during startup
• Ensure dynamic_ambient.rpy is in the game/ folder

---

Next Steps

• Quick-Start — Get your first ambient scene running
• Audio-Assets-YAML — Learn track configuration
• Arrangements-YAML — Create complex audio scenes