Autoloads y singletons

Los autoloads de Godot son nodos que el motor instancia una sola vez al inicio y añade a la raíz del árbol de escenas. Cualquier otra escena y script puede acceder a ellos por su nombre, sin necesidad de importaciones ni de usar cadenas de get_parent().

Beast Card Clash registra seis autoloads en project.godot:

[autoload]
DialogueManager="*uid://c3rodes2l3gxb"
SceneManager="*res://autoload/scene_manager.gd"
MusicManager="*res://autoload/music_manager.gd"
FlagsManager="*res://autoload/flags_manager.gd"
GameConstants="*res://autoload/game_constants.gd"
PlayerStats="*res://autoload/player_stats.gd"

Los autoloads son accesibles desde cualquier script usando simplemente su nombre; por ejemplo, GameConstants.Elements.FIRE o SceneManager.change_to_scene("battle"). No necesitas obtener una referencia a ellos primero.

GameConstants

Archivo: autoload/game_constants.gd

GameConstants es un singleton de puros datos. Define los enums y constantes a los que hacen referencia todos los demás sistemas. Nunca deberías escribir en él en tiempo de ejecución.

Enums

Elements

Representa los seis tipos elementales que puede tener una carta.

enum Elements {
    NONE, AIR, EARTH, ENERGY, FIRE, WATER
}

Valor	Descripción
`NONE`	Sin afinidad elemental
`AIR`	Elemento aire
`EARTH`	Elemento tierra
`ENERGY`	Elemento energía
`FIRE`	Elemento fuego
`WATER`	Elemento agua

Consulta Elementos para ver cómo interactúan en batalla.

Teams

Las nueve facultades seleccionables como equipos, más un valor centinela.

enum Teams {
    NO_TEAM,
    ACETILES, ADN, INGENIOSOS_ELEMENTALES,
    PHOTO_AGROS, PLUMA_DORADA, RPC_TEAM, REAL_PINCEL,
    VA_GAMES, ZOOTECNICOS
}

NO_TEAM es el valor por defecto antes de que el jugador seleccione un equipo en el selector de personajes.

Species

Las cuatro especies de personajes jugables.

enum Species {
    BEAR, CONDOR, CHAMALEON, FROG
}

Cada especie tiene uno o más aspectos (skins) definidos en SKINS. Consulta Personajes para más detalles.

Constantes

Constante	Tipo	Valor	Descripción
`MAX_CARD_VAlUE`	`int`	`10`	Valor numérico máximo que puede tener una carta (nota: hay una errata en el código fuente — `VAlUE` en lugar de `VALUE`)
`TEAMS_MEMBERS`	`Dictionary[Teams, Array]`	—	Mapea cada equipo a un arreglo de miembros (todos vacíos en la versión actual)
`SKINS`	`Dictionary[Species, PackedStringArray]`	—	Mapea cada especie a sus nombres de aspectos disponibles

La constante está escrita como MAX_CARD_VAlUE (con ‘A’ mayúscula en VAlUE) en el archivo fuente, lo cual es un error tipográfico. Al hacer referencia a ella en el código, usa la ortografía exacta de game_constants.gd.

Referencia de SKINS

const SKINS: Dictionary[Species, PackedStringArray] = {
    Species.BEAR:      ["base", "andean", "black", "grizzly", "panda", "polar"],
    Species.CHAMALEON: ["base"],
    Species.CONDOR:    ["base"],
    Species.FROG:      ["base", "green", "perez"]
}

Ejemplo de uso

# Comprobar si un nombre de aspecto es válido para la especie actual del jugador
var valid_skins := GameConstants.SKINS[PlayerStats.species]
if PlayerStats.skin in valid_skins:
    print("El aspecto es válido")

# Comparar un elemento
if card.element == GameConstants.Elements.FIRE:
    apply_burn_effect(card)

PlayerStats

Archivo: autoload/player_stats.gd

PlayerStats almacena los datos mutables de la sesión para el jugador humano. Se escribe en él durante la selección de personajes y es leído por la escena de batalla para configurar al personaje del jugador.

Propiedades

Propiedad	Tipo	Por defecto	Descripción
`player_name`	`String`	`"Osorio"`	El nombre de pantalla del jugador
`team`	`GameConstants.Teams`	`GameConstants.Teams.NO_TEAM`	El equipo de facultad seleccionado
`species`	`GameConstants.Species`	`GameConstants.Species.BEAR`	La especie de personaje seleccionada
`skin`	`String`	Primer aspecto de la especie elegida	La variante de aspecto seleccionada

Código fuente

extends Node

var player_name: String = "Osorio"
var team: GameConstants.Teams = GameConstants.Teams.NO_TEAM
var species: GameConstants.Species = GameConstants.Species.BEAR
var skin: String = GameConstants.SKINS[species][0]

Ejemplo de uso

# En el selector de personajes: escribir las elecciones del jugador
PlayerStats.player_name = name_input.text
PlayerStats.team = GameConstants.Teams.ADN
PlayerStats.species = GameConstants.Species.FROG
PlayerStats.skin = "perez"

# En la escena de batalla: leer para configurar el personaje del jugador
var character_skin := PlayerStats.skin
var team_name := GameConstants.Teams.keys()[PlayerStats.team]

PlayerStats persiste durante toda la sesión. Si el jugador vuelve al selector de personajes para cambiar sus opciones, asegúrate de sobrescribir los cuatro campos; de lo contrario, se arrastrarán los valores obsoletos de la partida anterior.

SceneManager

Archivo: autoload/scene_manager.gd

SceneManager es la única autoridad para las transiciones de escena. Carga escenas a partir de un recurso Scenes que mapea nombres de tipo cadena a escenas empaquetadas, de modo que el resto de la base de código nunca necesita rutas de escena estructuradas en duro.

API

func change_to_scene(scene_name: String) -> void

Realiza la transición inmediata a la escena indicada. El nombre debe coincidir con una clave en el recurso interno Scenes.

Ejemplo de uso

# Desde el selector de personajes, una vez que el jugador confirma sus opciones
SceneManager.change_to_scene("battle")

# Desde el botón de volver en la pantalla final
SceneManager.change_to_scene("start_menu")

Utiliza siempre SceneManager.change_to_scene() en lugar de llamar directamente a get_tree().change_scene_to_packed() o change_scene_to_file(). Esto mantiene todas las rutas de escena en un solo lugar y facilita la refactorización.

Consulta Gestor de escenas para ver la referencia de implementación completa.

MusicManager

Archivo: autoload/music_manager.gd

MusicManager extiende a AudioStreamPlayer y controla la música de fondo a lo largo del juego. Carga pistas desde un recurso Playlist indexado por nombre.

API

func play_music(music_name: String) -> void
func switch_music_playing(on = null) -> void

`play_music(music_name)`

Carga la pista indicada de la lista de reproducción y comienza a reproducirla de inmediato. Reemplaza cualquier pista que se esté reproduciendo actualmente.

`switch_music_playing(on)`

Alterna o establece el estado de pausa de la pista actual.

Argumento	Comportamiento
`null` (por defecto)	Alterna la pausa: pausa si se está reproduciendo, reanuda si está pausada
`true`	Pausa la música
`false`	Reanuda la música

Ejemplo de uso

# Reproducir el tema de batalla cuando se carga la escena de batalla
# (los nombres de las pistas son claves en playlist.tres; "battle" apunta a battle.ogg)
MusicManager.play_music("battle")

# Pausar durante una escena cinematográfica
MusicManager.switch_music_playing(true)

# Reanudar después de la escena cinematográfica
MusicManager.switch_music_playing(false)

# Alternar reproducción/pausa al presionar un botón
MusicManager.switch_music_playing()

Consulta Gestor de música para ver la referencia de implementación completa.

FlagsManager

Archivo: autoload/flags_manager.gd

FlagsManager es un almacén simple de banderas booleanas respaldado por un recurso Flags. Úsalo para rastrear eventos únicos como “¿se ha mostrado el tutorial?” o “¿el jugador ha ganado al menos una vez?” sin tener que añadir variables a los scripts de las escenas.

API

func get_flag(flag: String) -> bool
func set_flag(flag: String, value: bool) -> void

`get_flag(flag)`

Devuelve el valor actual de la bandera indicada. Devuelve false para cualquier bandera que no haya sido establecida explitamente.

`set_flag(flag, value)`

Establece la bandera indicada al valor value. Imprime un mensaje de depuración indicando si la bandera fue activada o desactivada.

Ejemplo de uso

# Comprobar antes de mostrar el tutorial
if not FlagsManager.get_flag("tutorial_shown"):
    SceneManager.change_to_scene("tutorial")
    FlagsManager.set_flag("tutorial_shown", true)

# Marcar que el jugador ha completado al menos una batalla
FlagsManager.set_flag("first_battle_completed", true)

Consulta Gestor de banderas para ver la referencia de implementación completa.

DialogueManager

Plugin: addons/dialogue_manager

DialogueManager es un plugin de Godot de terceros que maneja todos los diálogos y secuencias narrativas del juego. Se registra como un autoload automáticamente cuando se activa el plugin.

Los diálogos se encuentran en assets/dialogues/ en forma de archivos .dialogue:

Archivo	Utilizado para
`begin.dialogue`	Narración de apertura antes de una batalla
`pregame.dialogue`	Presentaciones de personajes antes del combate
`win.dialogue`	Secuencia de victoria
`lose.dialogue`	Secuencia de derrota

Ejemplo de uso

# Iniciar una secuencia de diálogo mediante su recurso y título inicial
var dialogue := load("res://assets/dialogues/win.dialogue")
DialogueManager.show_dialogue_balloon(dialogue, "start")

Consulta la documentación del plugin Dialogue Manager para ver la API completa. El nombre de autoload DialogueManager es provisto por el plugin y no se puede renombrar sin modificar el plugin mismo.

GameConstants

Enums

Elements

Teams

Species

Constantes

Referencia de SKINS

Ejemplo de uso

PlayerStats

Propiedades

Código fuente

Ejemplo de uso

SceneManager

API

Ejemplo de uso

MusicManager

API

play_music(music_name)

switch_music_playing(on)

Ejemplo de uso

FlagsManager

API

get_flag(flag)

set_flag(flag, value)

Ejemplo de uso

DialogueManager

Ejemplo de uso

Table of contents

`play_music(music_name)`

`switch_music_playing(on)`

`get_flag(flag)`

`set_flag(flag, value)`