Main Theme

Main Theme

The main theme feature allows you to play an introductory music track before transitioning to ambient audio, perfect for main menu sequences.

---

Overview

The main theme system provides:

• Dedicated playback channel (main_theme)
• Configurable duration and volume
• Smooth fade in/out
• Automatic transition to ambient arrangement
• Loop monitoring (restarts if interrupted)

---

Configuration

Define the main theme in audio_assets.yaml:

main_theme:
  file: "audio/main_theme.mp3"
  duration: 60                        # Play for 60 seconds
  volume: 0.8                         # Volume level
  fade_in: 2.0                        # Fade in time
  fade_out: 4.0                       # Fade out time
  after_theme_arrangement: "main_menu" # Arrangement to play after

Parameters

Parameter	Type	Description
file	string	Path to audio file
duration	float	Playback duration in seconds
volume	float	Volume level (0.0-1.0)
fade_in	float	Fade in duration
fade_out	float	Fade out duration
after_theme_arrangement	string	Arrangement to transition to

---

Usage

Automatic (Main Menu)

If using ambient_auto_start.rpy, the main theme starts automatically when the main menu shows:

# This happens automatically:
# 1. Main menu appears
# 2. Main theme plays for 'duration' seconds
# 3. Theme fades out
# 4. 'after_theme_arrangement' starts playing

Manual Start

# Start the full sequence: theme → ambient
$ ambient.start_with_main_theme()

Python API

# Configure main theme programmatically
$ ambient.set_main_theme(
    filename="audio/theme.mp3",
    duration=45,
    volume=0.8,
    fade_in_time=2.0,
    fade_out_time=3.0,
    after_theme_arrangement="main_menu_ambient"
)

# Start the sequence
$ ambient.start_with_main_theme()

---

Behavior Timeline

Time:     0s      2s              56s     60s
          |-------|----------------|-------|
Phase:    Fade In  Playing         Fade Out
Volume:   0→0.8    0.8             0.8→0

At 60s: Ambient arrangement starts

Detailed Flow

1. Start — start_with_main_theme() called
2. Play — Theme starts with fade in
3. Monitor — System monitors playback, restarts if interrupted
4. Fade Start — At duration - fade_out, fade begins
5. Transition — At duration, theme stops, arrangement starts

---

Integration with Arrangements

The after_theme_arrangement connects the theme to your ambient system:

# audio_assets.yaml
main_theme:
  file: "audio/epic_intro.mp3"
  duration: 45
  after_theme_arrangement: "menu_ambient"

# arrangements.yaml
arrangements:
  menu_ambient:
    tracks:
      menu_base: { volume: 0.5 }
      menu_atmosphere: { volume: 0.3 }

Without after_theme_arrangement

If not specified, the system falls back to start_ambient() which starts all tracks without a specific arrangement context.

---

Main Menu Integration

ambient_auto_start.rpy

This file overrides the main menu screen to handle ambient:

screen main_menu():
    tag menu
    
    # Start ambient when menu shows
    on "show" action Function(renpy.call_in_new_context, "start_main_menu_ambient")
    
    # Stop ambient when leaving menu
    on "hide" action Function(store.ambient.stop_ambient)
    
    # ... rest of main menu screen

The start_main_menu_ambient Label

label start_main_menu_ambient:
    # Prevent double-start
    if ambient.is_active or ambient.main_theme['is_playing']:
        return
    
    # Sync volume with settings
    $ ambient.set_base_volume(ambient_volume_setting)
    
    # Start sequence
    $ ambient.start_with_main_theme()
    return

---

Skipping the Theme

If you want ambient without the theme:

# Skip theme, go straight to ambient
$ ambient.start_ambient()

# Or play a specific arrangement directly
$ ambient.play_arrangement("main_menu")

---

Disabling Auto-Start

To disable automatic main menu ambient:

Option 1: Remove the file

Don't include ambient_auto_start.rpy in your project.

Option 2: Comment out actions

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

---

Tips

Theme Duration

• Match duration to a natural break point in your music
• Account for fade_out time (fade starts at duration - fade_out)

Seamless Transition

• Design your theme's ending to blend with ambient
• Use similar tonal qualities between theme and ambient
• Consider a longer fade_out for smoother transition

Multiple Themes

The system supports one main theme at a time. For different themes:

# Before showing a different menu/screen
$ ambient.set_main_theme("audio/different_theme.mp3", ...)
$ ambient.start_with_main_theme()