Skip to main content
MusicManager is an autoload singleton that extends AudioStreamPlayer. It centralizes all background music selection and playback state, so every part of the game changes or pauses music through a single, consistent API rather than manipulating audio nodes directly.
Because MusicManager extends AudioStreamPlayer, it is the audio player — it is not a wrapper around one. The node itself plays the stream.

​
Class overview

music_manager.gd
# extends AudioStreamPlayer (Autoload singleton)
At startup, MusicManager loads a Playlist resource (playlist.tres) that maps music track names to AudioStream objects.

​
Initialization

func _ready():
    _playlist.expected_type = TYPE_OBJECT
    _playlist.check_item_types()
Before any music plays, _ready() validates that every entry in playlist.tres is a proper Object (a loaded AudioStream). Type mismatches are reported immediately at startup rather than at the moment a track is first requested.

​
API reference

​
play_music(music_name: String) -> void

Loads the named track from the playlist and starts playback immediately, replacing any currently playing stream.
​
music_name
String
required
The track name as registered in playlist.tres. Case-sensitive. If the key is not found, _playlist.get_item() raises an error.
func play_music(music_name: String) -> void:
    stream = _playlist.get_item(music_name)
    play()

​
switch_music_playing(on = null) -> void

Toggles, pauses, or resumes playback depending on the argument passed.
​
on
bool | null
default:"null"
Controls the pause state:
  • null (default) — toggles stream_paused
  • true — pauses playback
  • false — resumes playback
Passing a non-boolean, non-null value calls push_error and returns without changing state.
func switch_music_playing(on = null) -> void:
    if on == null:
        stream_paused = not stream_paused
        return
    if not (on is bool):
        push_error("Tipo de dato incorrecto en MusicManager. Se espera un valor booleano")
    stream_paused = on
    return

Toggle

MusicManager.switch_music_playing()
Flips the current pause state.

Pause

MusicManager.switch_music_playing(true)
Pauses without unloading the stream.

Resume

MusicManager.switch_music_playing(false)
Resumes from where it paused.

​
Usage patterns

The most common pattern: start the appropriate track in _ready() of the scene’s root node.
# res://assets/battle/battle.gd (or any scene root)
# "battle" is the key in playlist.tres mapped to battle.ogg
func _ready() -> void:
    MusicManager.play_music("battle")

​
The Playlist resource

All track names are defined in playlist.tres. Open this file in the Godot Inspector to view, add, or rename tracks.
Track names in playlist.tres are the only source of truth for valid play_music arguments. Check the Inspector to see which names are registered before calling play_music.

​
Adding a new track

1

Import your audio file

Add the audio file (.ogg, .mp3, or .wav) to the project’s filesystem under res://assets/music/.
2

Open playlist.tres in the Inspector

Locate playlist.tres in the FileSystem dock and open it. You will see the existing name → AudioStream entries.
3

Add a new entry

Add a new key-value pair: the key is your track name string (e.g., "credits_theme"), and the value is the imported audio file.
4

Verify at startup

Run the project. If check_item_types() logs no errors in _ready(), your track is correctly registered.
5

Play the new track

MusicManager.play_music("credits_theme")

Autoloads

Overview of all autoload singletons and initialization order.

SceneManager

Transition between scenes — call play_music after change_to_scene.

FlagsManager

Use flags to determine which track to play (e.g., after tutorial completion).

Architecture overview

How autoloads fit into the overall project structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us