Debugging

Debugging

Tools and techniques for debugging the Dynamic Ambient System.

---

Debug Commands

CDS Debug Commands

ambient debug info      # Basic system state
ambient debug runtime   # Show runtime duration
ambient debug tracks    # Print all track states
ambient debug ui        # Toggle debug overlay

Python Debug Methods

# Check system state
$ print(f"Active: {ambient.is_active}")
$ print(f"Arrangement: {ambient.active_arrangement.name if ambient.active_arrangement else 'None'}")
$ print(f"Layers: {ambient.active_layers}")

# Check track states
python:
    for track_id, data in ambient.tracks.items():
        print(f"{track_id}: playing={data['is_playing']}, vol={data['current_volume']:.2f}")

---

Debug UI

The debug overlay shows real-time system information.

Enabling Debug UI

Using CDS:

ambient debug ui

Using Python:

$ toggle_ambient_debug()  # If defined in debug_ambient.rpy

Debug UI Information

The overlay displays:

• System status (active/inactive)
• Current arrangement name
• Active layers
• Runtime duration
• Track list with:
  • Playing status
  • Current/target volume
  • Track type
  • Elevation status (for random tracks)
• Wave system state:
  • Current wave progress
  • Elevated track count
  • Cooldown timer
• Timer counts

---

Console Output

The system prints debug information to the Ren'Py console.

Startup Messages

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

Runtime Messages

DEBUG: Track birds target_volume: 0.00 -> 0.35, type=random
DEBUG: Checking track wind. Playing: True, Channel: ambient_3, Fade: 3.0
DEBUG: max_fade_time = 4.0, scheduling stop in 4.5s
DEBUG: Force stopping all ambient channels

Error Messages

DynamicAmbientSystem: Error loading configuration: [details]
Arrangement 'invalid_name' not found.
Layer 'missing' not found in arrangement 'scene'.
Error: Track ID 'unknown' has no filename and is not in registry.

---

Common Debug Scenarios

Track Not Playing

Check:

1. Is the system active?

   $ print(ambient.is_active)

2. Is the track in the current arrangement?

   $ print(ambient.active_arrangement.tracks_config.keys())

3. Is the track configured correctly?

   $ print(ambient.tracks.get("track_id"))

4. Does the audio file exist?

   • Check file path in audio_assets.yaml
   • Verify file is in game/audio/ folder

Volume Issues

Check current volumes:

python:
    for tid, data in ambient.tracks.items():
        print(f"{tid}: current={data['current_volume']:.3f}, target={data['target_volume']:.3f}")

Check base volume:

$ print(f"Base volume: {ambient.base_volume}")

Check arrangement multipliers:

$ print(ambient.active_arrangement.tracks_config)

Random Tracks Not Elevating

Check wave system state:

python:
    print(f"Elevated count: {ambient.elevated_tracks_count}")
    print(f"Wave limit: {ambient.current_wave_limit}")
    print(f"Wave count: {ambient.wave_elevation_count}")
    print(f"Cooldown end: {ambient.global_cooldown_end_time}")
    print(f"Fading out: {ambient.tracks_fading_out}")

Check track configuration:

python:
    track = ambient.tracks.get("track_id")
    if track:
        print(f"Type: {track['type']}")
        print(f"Chance: {track['play_chance']}")
        print(f"Is elevated: {track.get('is_elevated', False)}")

Arrangement Not Switching

Check arrangement exists:

$ print("my_arrangement" in ambient.arrangements)
$ print(list(ambient.arrangements.keys()))

Check for errors in console after calling:

ambient play "my_arrangement"

---

Settings Screen Debug

The ambient_integration.rpy provides a settings screen with debug info:

Access: Settings → Ambient Settings

Shows:

• Volume slider
• System status
• Track information
• Control buttons
• System statistics

---

Logging Custom Events

Add your own debug logging:

init python:
    def log_ambient_event(event, details=""):
        if config.developer:
            print(f"[AMBIENT] {event}: {details}")

label some_scene:
    $ log_ambient_event("Playing arrangement", "forest_morning")
    ambient play "forest_morning"
    
    $ log_ambient_event("Enabling layer", "rain")
    ambient layer "rain" on

---

Troubleshooting Checklist

System Won't Start

• PyYAML installed in game/python-packages/?
• dynamic_ambient.rpy in game/ folder?
• audio_assets.yaml exists and is valid YAML?
• Check console for error messages

No Sound

• Audio files exist at specified paths?
• Files in supported format (OGG recommended)?
• System is active (ambient.is_active)?
• Volume not zero (ambient.base_volume)?
• Ren'Py music volume not muted?

CDS Commands Not Working

• libs/rpda/02-rpda-cds.rpy exists?
• Ren'Py version 8.5.0+?
• Restarted Ren'Py after adding CDS file?
• Correct syntax (quoted strings, keywords)?

Tracks Leaking Between Arrangements

• Using play_arrangement() not manual track control?
• Track defined in both arrangements?
• Check strict isolation is working (console output)

Save/Load Issues

• System state should auto-restore
• Check __getstate__ and __setstate__ in code
• Timers are recreated after load

---

Performance Debugging

Check Active Timers

python:
    print(f"Active timers: {len(ambient.active_timers)}")
    print(f"Track timers: {len(ambient.track_timers)}")

Check Channel Usage

python:
    used = sum(1 for t in ambient.tracks.values() if t.get('channel') and t['is_playing'])
    print(f"Channels used: {used}/{len(ambient.ambient_channels)}")

Monitor Update Loop

The volume update loop runs at 10 Hz (every 0.1 seconds). If performance issues occur:

• Reduce number of active tracks
• Check for timer accumulation
• Monitor console for excessive debug output

---

Resetting the System

If the system gets into a bad state:

# Hard reset
$ ambient.stop_ambient(fade_out=False)
$ ambient._cancel_all_timers()
$ ambient.load_config()

# Then restart
$ ambient.play_arrangement("default")

Or restart Ren'Py to reinitialize everything.