Project Structure

Project Structure

Understanding the file layout of the Dynamic Ambient System.

---

Core Files

dynamic_ambient.rpy

Required — The main system class.

Contains:

• DynamicAmbientSystem class
• Channel registration
• Volume management
• Timer handling
• Save/load support

# Automatically creates the ambient instance
default ambient = DynamicAmbientSystem()

audio_assets.yaml

Required — Track definitions.

Defines:

• All audio tracks (mandatory and random)
• Track parameters (volume, fade times, etc.)
• Main theme configuration

See: Audio-Assets-YAML

arrangements.yaml

Required — Arrangement definitions.

Defines:

• Audio scene presets
• Layer configurations
• Auto-transitions

See: Arrangements-YAML

---

Optional Files

ambient_auto_start.rpy

Automatic main menu integration.

Features:

• Starts ambient when main menu shows
• Stops ambient when leaving main menu
• Handles quit cleanup

screen main_menu():
    on "show" action Function(renpy.call_in_new_context, "start_main_menu_ambient")
    on "hide" action Function(store.ambient.stop_ambient)

ambient_integration.rpy

Settings UI screen.

Provides:

• Volume slider
• System status display
• Track information
• Control buttons (start/stop/pause/resume)
• Debug statistics

Access via: Settings → Ambient Settings

debug_ambient.rpy

Debug overlay screen.

Shows real-time:

• Active tracks and volumes
• Current arrangement
• Wave system state
• Timer counts

Toggle with: ambient debug ui

---

CDS Support

libs/rpda/02-rpda-cds.rpy

Creator-Defined Statements implementation.

Enables native Ren'Py commands:

ambient play "arrangement_name"
ambient stop
ambient layer "layer" on

Requires: Ren'Py 8.5.0+

See: CDS-Reference

---

Directory Layout

game/
├── audio/                        # Your audio files
│   ├── ambient_base.ogg
│   ├── effect1.ogg
│   ├── effect2.ogg
│   └── main_theme.mp3
│
├── libs/                         # Library extensions
│   └── rpda/
│       └── 02-rpda-cds.rpy       # CDS implementation
│
├── python-packages/              # Python dependencies
│   └── yaml/                     # PyYAML library
│       ├── __init__.py
│       ├── loader.py
│       └── ...
│
├── dynamic_ambient.rpy           # Core system (REQUIRED)
├── ambient_auto_start.rpy        # Auto-start (optional)
├── ambient_integration.rpy       # Settings UI (optional)
├── debug_ambient.rpy             # Debug overlay (optional)
│
├── audio_assets.yaml             # Track config (REQUIRED)
├── arrangements.yaml             # Arrangements (REQUIRED)
│
├── script.rpy                    # Your game script
├── screens.rpy                   # Your screens
└── ...

---

File Loading Order

Ren'Py loads files in this order:

1. init python early — CDS registration (02-rpda-cds.rpy)
2. init python — Channel registration, system class (dynamic_ambient.rpy)
3. default — Instance creation (ambient = DynamicAmbientSystem())
4. YAML loading — Configuration loaded in __init__

The 02- prefix ensures CDS loads before other init blocks.

---

Audio File Recommendations

Format

• OGG Vorbis — Recommended for all ambient tracks
• MP3 — Acceptable for main theme
• WAV — Not recommended (large file size)

Looping

• Mandatory tracks should be seamlessly loopable
• Random tracks can be one-shot or looping
• Use audio editing software to create clean loops

Naming Convention

audio/
├── amb_forest_base.ogg      # Mandatory base layer
├── amb_forest_birds.ogg     # Random effect
├── amb_forest_wind.ogg      # Random effect
├── amb_city_traffic.ogg     # Different location
├── sfx_thunder.ogg          # One-shot effect
└── mus_main_theme.mp3       # Main theme

---

Minimal Installation

For the smallest footprint, you only need:

game/
├── python-packages/yaml/
├── dynamic_ambient.rpy
├── audio_assets.yaml
├── arrangements.yaml
└── audio/your_tracks.ogg

Everything else is optional enhancement.