Configuration Reference

Configuration Reference

Complete reference for all configuration parameters in the Dynamic Ambient System.

---

audio_assets.yaml

defaults Section

Parameter	Type	Default	Description
fade_in	float	3.0	Default fade in time for all tracks
fade_out	float	3.0	Default fade out time for all tracks

tracks Section

Common Parameters (All Track Types)

Parameter	Type	Required	Default	Description
file	string	Yes*	—	Path to audio file
files	list	Yes*	—	List of audio files (random container)
type	string	Yes	—	"mandatory" or "random"
volume	float	No	1.0	Base volume (0.0-1.0)
fade_in	float	No	3.0	Fade in duration (seconds)
fade_out	float	No	3.0	Fade out duration (seconds)

*Either file or files is required, not both.

Random Track Parameters

Parameter	Type	Required	Default	Description
chance	float	No	0.5	Elevation probability (0.0-1.0)
interval	[min, max]	No	[30, 120]	Elevation duration range (seconds)

main_theme Section

Parameter	Type	Required	Default	Description
file	string	Yes	—	Path to theme audio file
duration	float	Yes	—	Playback duration (seconds)
volume	float	No	0.8	Volume level (0.0-1.0)
fade_in	float	No	2.0	Fade in duration
fade_out	float	No	3.0	Fade out duration
after_theme_arrangement	string	No	—	Arrangement to play after theme

---

arrangements.yaml

Arrangement Parameters

Parameter	Type	Required	Description
tracks	dict	Yes	Track configurations
layers	dict	No	Layer definitions
duration	float	No	Auto-transition delay (seconds)
auto_next	string	No	Next arrangement name

Track Configuration in Arrangements

Parameter	Type	Description
volume	float	Volume multiplier
type	string	Override track type
fade_in	float	Override fade in time
fade_out	float	Override fade out time
play_chance	float	Override chance (random tracks)
min_duration	float	Override min duration (random tracks)
max_duration	float	Override max duration (random tracks)

Layer Configuration

Layers use the same track configuration format as the main tracks section.

---

System Constants

Internal defaults in DynamicAmbientSystem class:

Volume Settings

Constant	Default	Description
base_volume	0.7	Master volume multiplier
minimum_volume	0.00	Volume for non-elevated random tracks
fade_duration	2.0	Default system fade duration

Wave System

Constant	Default	Description
initial_cooldown_time	15.0	Delay before first wave (seconds)
minimum_rest_time	10.0	Minimum rest between waves
maximum_rest_time	30.0	Maximum rest between waves
min_tracks_per_wave	1	Minimum tracks elevated per wave
max_tracks_per_wave	3	Maximum tracks elevated per wave

Timing

Constant	Default	Description
Volume update interval	0.1	Seconds between volume updates (10 Hz)

---

Audio Channel Configuration

The system automatically registers channels based on track count:

Channel	Purpose
main_theme	Main menu theme playback
ambient_1	Ambient track 1
ambient_2	Ambient track 2
ambient_N	Ambient track N

Channel count = number of tracks + 2 (buffer)

---

Value Ranges

Volume Values

• Range: 0.0 to 1.0
• 0.0 = silent
• 1.0 = full volume
• Values > 1.0 are allowed (amplification)

Probability Values (chance)

• Range: 0.0 to 1.0
• 0.0 = never elevates
• 1.0 = always elevates
• 0.5 = 50% chance

Time Values

• All time values are in seconds
• Minimum practical value: 0.1
• No maximum limit

---

File Path Format

# Correct
file: "audio/ambient/forest.ogg"
file: "audio/effects/bird.ogg"

# Also correct (forward slashes work on all platforms)
file: "audio/music/theme.mp3"

# Incorrect (backslashes)
file: "audio\\ambient\\forest.ogg"  # Don't use

Paths are relative to the game/ directory.

---

Supported Audio Formats

Any format supported by Ren'Py works:

Format	Extension	Notes
Ogg Vorbis	.ogg	Recommended (small size, good looping)
MP3	.mp3	Works fine
WAV	.wav	Large files, but works
FLAC	.flac	Lossless, larger files
OPUS	.opus	Modern, efficient

Use whatever format you have — the system doesn't care.

---

YAML Syntax Reference

Basic Track

track_id:
  file: "path/to/file.ogg"
  type: "mandatory"
  volume: 0.6

Inline Style

track_id: { file: "path.ogg", type: "mandatory", volume: 0.6 }

List (Random Container)

track_id:
  files:
    - "audio/var1.ogg"
    - "audio/var2.ogg"
  type: "random"

Nested (Layers)

arrangements:
  scene:
    tracks:
      base: { volume: 0.5 }
    layers:
      rain:
        rain_sound: { volume: 0.7 }

Comments

# This is a comment
tracks:
  my_track:  # Inline comment
    file: "audio/track.ogg"