MusicManager

MusicManager es un singleton autoload que extiende a AudioStreamPlayer. Centraliza toda la selección de música de fondo y el estado de su reproducción, de modo que cualquier parte del juego cambia o pausa la música a través de una API única y consistente, en lugar de manipular los nodos de audio directamente.

Dado que MusicManager extiende a AudioStreamPlayer, el propio singleton es el reproductor de audio, no una envoltura de este. El propio nodo reproduce el stream.

Resumen de la clase

Al iniciar, MusicManager carga un recurso Playlist (playlist.tres) que asocia nombres de pistas de música con objetos AudioStream.

Inicialización

func _ready():
    _playlist.expected_type = TYPE_OBJECT
    _playlist.check_item_types()

Antes de que se reproduzca cualquier pista, _ready() valida que cada entrada de playlist.tres sea un Object válido (un AudioStream cargado). Las inconsistencias de tipos se notifican de inmediato en el arranque del juego.

Referencia de la API

`play_music(music_name: String) -> void`

Carga la pista indicada de la lista de reproducción y comienza a reproducirla inmediatamente.

music_name (String): El nombre de la pista tal como está registrada en playlist.tres. Sensible a mayúsculas y minúsculas.

`switch_music_playing(on = null) -> void`

Alterna, pausa o reanuda la reproducción dependiendo del argumento proporcionado.

on (bool | null): Controla el estado de pausa:
- null (por defecto): alterna stream_paused
- true: pausa la reproducción
- false: reanuda la reproducción

Modos de control

Alternar: MusicManager.switch_music_playing() invierte el estado de pausa actual.
Pausar: MusicManager.switch_music_playing(true) pausa sin descargar el stream de audio.
Reanudar: MusicManager.switch_music_playing(false) reanuda la pista desde el punto donde se pausó.

Patrones de uso

Reproducir música al cargar la escena

func _ready() -> void:
    MusicManager.play_music("battle")

Pausar al abrir un menú

func _on_pause_menu_opened() -> void:
    MusicManager.switch_music_playing(true)

func _on_pause_menu_closed() -> void:
    MusicManager.switch_music_playing(false)

El recurso Playlist

Todos los nombres de las pistas están definidos en playlist.tres. Abre este archivo en el Inspector de Godot para ver, añadir o renombrar pistas.

Los nombres de las pistas en playlist.tres son la única fuente de verdad para los argumentos válidos de play_music.

Añadir una nueva pista

Importa tu archivo de audio: Añade el archivo (.ogg, .mp3 o .wav) en res://assets/music/.
Abre playlist.tres en el Inspector: Busca playlist.tres y ábrelo.
Añade una nueva entrada: Añade un nuevo par clave-valor (nombre → AudioStream).
Verifica al iniciar: Ejecuta el proyecto para confirmar que no hay errores de tipo.
Reproduce la nueva pista: MusicManager.play_music("credits_theme").