Audio

Introduction

Controlling audio within games can often be tedious as multiple scripts all want to influence the same resource: the player's audio playback device. To make audio control simpler, ProtoJam provides an AudioManager autoload which consolidates this logic into one place. Additionally, a GlobalMusicPlayer node is provided to make background music playback as simple as dropping a node into a scene.

Using AudioManager

The AudioManager autoload provides several core functions:

• Loading music tracks asynchronously
• Transitioning to/from music tracks
• Validating music tracks are properly configured to loop
• Synchronizing audio bus volume with user settings

Configuring the manager to perform these functions requires only a few steps:

1. Creating a Music bus in the Godot editor
   • Alternatively, making a call to AudioManager.set_music_bus(bus_name) to use a different bus for audio playback.
2. Creating AudioBusVolumeRangeSetting resources for busses with user volume control
   • See the Settings page for more details on the ProtoJam settings framework
3. Registering your bus volume settings with the manager using AudioManager.sync_bus_volume(bus_setting)
4. (optional) Adjusting how many beats long fades between music tracks will last with a call to AudioManager.set_music_fade_beats(fade_beats)

That's it! Now you can smoothly transition between background music tracks with a call to AudioManager.play_music_loop(audio_stream_path) or via the GlobalMusicPlayer node.

Note

It's recommended to perform this setup from your main scene's script to ensure the audio system is reset when the current scene is reloaded.

Using GlobalMusicPlayer

To make integration with the AudioManager's music system more convenient, the GlobalMusicPlayer node will automatically request a track change from the audio manager when it is added to the scene tree or when its music_path parameter is changed. Use this node exactly how you would an AudioStreamPlayer.

Examples

Example 1 - Initializing the manager

This example showcases the typical setup process of the AudioManager from the main scene.

Settings

default_bus_layout.tres

main.gd

class_name Main
extends Node

# Fetch the user bus volume settings by path or UID
const _MASTER_VOLUME_SETTING: AudioBusVolumeRangeSetting = preload("res://resources/settings/master_volume_setting.tres")
const _MUSIC_VOLUME_SETTING: AudioBusVolumeRangeSetting = preload("res://resources/settings/music_volume_setting.tres")
const _SFX_VOLUME_SETTING: AudioBusVolumeRangeSetting = preload("res://resources/settings/sfx_volume_setting.tres")

func _ready() -> void:
	# Configure audio manager to sync volume settings
	AudioManager.sync_bus_volume(_MASTER_VOLUME_SETTING)
	AudioManager.sync_bus_volume(_MUSIC_VOLUME_SETTING)
	AudioManager.sync_bus_volume(_SFX_VOLUME_SETTING)
	
	# (optional) Only required if your music bus is not named "Music"
	AudioManager.set_music_bus(_MUSIC_VOLUME_SETTING.bus_name)
	
	# (optional) If you desire a different music fade duration
	AudioManager.set_music_fade_beats(2.0)

Example 2 - Changing music tracks with code

This example demonstrates how to change the global music track with code.

my_level.gd

# Get the path (or UID) to the .ogg file to play
# Preloading is not required or recommended since AudioManager will load the stream in the background when played
const _MUSIC_LOOP_PATH: String = "res://track_1.ogg"

func _ready() -> void:
	# Transition to the new track
	AudioManager.play_music_loop(_MUSIC_LOOP_PATH)