Toast

ss-gameforge-toast permite mostrar notificaciones temporales no intrusivas en tu juego. Soporta 5 estilos predefinidos, 9 posiciones en pantalla, apilamiento, temas personalizados e íconos animados.

Dependencia

Este addon requiere ss-gameforge-singleton. Instálalo y actívalo primero.

Instalación

1. Descarga ss-gameforge-toast desde la página de releases.
2. Copia addons/ss-gameforge-toast/ dentro de res://addons/.
3. Activa ss-gameforge-singleton y ss-gameforge-toast en Project Settings → Plugins.

Inicializar ToastService

Añade esto a tu escena principal o autoload:

func _enter_tree() -> void:
    SingletonNode.ensure_for(ToastService, get_tree().root, "ToastService")

Inicio rápido

# Mostrar diferentes tipos de toast
ToastService.i.info("El servidor está en mantenimiento")
ToastService.i.success("¡Partida guardada correctamente!")
ToastService.i.danger("Conexión perdida")
ToastService.i.loader("Cargando datos...")

# Opciones personalizadas en cualquier toast
ToastService.i.info("Notificación personalizada", {
    "duration": 5.0,
    "font_size": 18,
    "position": ToastConstants.ToastPosition.TOP_CENTER,
    "background_color": Color("#FF6B6B"),
    "text_color": Color("#FFFFFF")
})

Tipos de toast

Método	Estilo	Color por defecto	Usar para
info(text, overrides)	INFO	Azul #2D9CDB	Mensajes generales
success(text, overrides)	SUCCESS	Verde #27AE60	Operaciones completadas
danger(text, overrides)	DANGER	Rojo #EB5757	Errores y advertencias
custom(text, overrides)	CUSTOM	Gris oscuro #333333	Estilo personalizado
loader(text, overrides)	LOADER	Azul (ícono giratorio)	Operaciones asíncronas
show(text, style, overrides)	Cualquiera	—	Punto de entrada genérico

# show() genérico con estilo explícito
ToastService.i.show("Mensaje", ToastConstants.ToastStyle.SUCCESS, {"duration": 3.0})

Posiciones

Nueve posiciones disponibles via ToastConstants.ToastPosition:

enum ToastPosition {
    TOP_LEFT,      TOP_CENTER,    TOP_RIGHT,
    CENTER_LEFT,   CENTER,        CENTER_RIGHT,
    BOTTOM_LEFT,   BOTTOM_CENTER, BOTTOM_RIGHT   # por defecto
}

ToastService.i.success("Arriba a la derecha", {
    "position": ToastConstants.ToastPosition.TOP_RIGHT
})

# Margen personalizado desde los bordes
ToastService.i.info("Con margen", {
    "position": ToastConstants.ToastPosition.TOP_RIGHT,
    "position_margin": Vector2(50, 50)
})

Opciones de personalización

Pasa cualquiera de estas claves en el diccionario de overrides:

Clave	Tipo	Valor por defecto	Descripción
background_color	Color	Según estilo	Fondo del toast
text_color	Color	Según estilo	Color del texto
font_size	int	14	Tamaño de fuente en píxeles
icon	Texture2D	Según estilo	Textura del ícono
icon_color	Color	Color.WHITE	Tinte del ícono
icon_size	float	18.0	Tamaño del ícono en píxeles
icon_spin	bool	false	Activar rotación del ícono
icon_spin_speed	float	1.5	Velocidad de rotación (rad/s)
padding	float	10.0	Espaciado interno
corner_radius	float	10.0	Radio de las esquinas
position	ToastPosition	BOTTOM_CENTER	Posición en pantalla
position_margin	Vector2	Vector2(16, 16)	Distancia desde los bordes
duration	float	2.0	Tiempo visible en segundos

Propiedades de ToastService

@export var theme: ToastTheme          # Tema visual global
@export var max_queue: int = 50        # Máximo de toasts en cola
@export var stack_toasts: bool = true  # Modo apilado vs. single
@export var max_visible: int = 4       # Máximo visibles a la vez
@export var stack_spacing: float = 8.0 # Píxeles entre toasts apilados

Apilamiento

Modo apilado (por defecto)

Múltiples toasts visibles simultáneamente, apilados en su posición.

ToastService.i.stack_toasts = true
ToastService.i.max_visible = 5
ToastService.i.stack_spacing = 10.0

ToastService.i.info("Toast 1")
ToastService.i.info("Toast 2")
ToastService.i.info("Toast 3")  # Todos visibles a la vez

Dirección del apilamiento según posición:

• Posiciones TOP → apilan hacia abajo
• Posiciones BOTTOM → apilan hacia arriba
• Posiciones CENTER → apilan hacia abajo

Cada posición mantiene un stack independiente:

# Cada grupo apila por separado
ToastService.i.info("Center 1",  {"position": ToastConstants.ToastPosition.CENTER})
ToastService.i.info("Center 2",  {"position": ToastConstants.ToastPosition.CENTER})
ToastService.i.success("Right 1", {"position": ToastConstants.ToastPosition.CENTER_RIGHT})

Modo single

Un toast a la vez. El siguiente espera a que termine el actual.

ToastService.i.stack_toasts = false

Temas

Define un recurso ToastTheme reutilizable para dar estilo coherente a todos los toasts.

Crear un tema en el inspector

Clic derecho en el FileSystem → New Resource → selecciona ToastTheme. Configura:

• Duration, font_size, icon_size, corner_radius, padding, position_margin
• Por estilo: info_background_color, info_text_color, info_icon, y equivalentes para success_, danger_, custom_, loader_

Crear un tema por código

var my_theme = ToastTheme.new()
my_theme.duration = 3.0
my_theme.font_size = 16
my_theme.corner_radius = 8.0
my_theme.position = ToastConstants.ToastPosition.TOP_CENTER

my_theme.info_background_color = Color("#3498DB")
my_theme.success_background_color = Color("#2ECC71")
my_theme.danger_background_color = Color("#E74C3C")

Aplicar un tema globalmente

func _ready() -> void:
    ToastService.i.theme = preload("res://themes/my_toast_theme.tres")

Ejemplos avanzados

Notificación de logro

func unlock_achievement(name: String, description: String) -> void:
    ToastService.i.success("¡Logro Desbloqueado!", {
        "duration": 5.0,
        "font_size": 18,
        "icon": preload("res://icons/trophy.svg"),
        "icon_color": Color.GOLD,
        "position": ToastConstants.ToastPosition.TOP_CENTER,
    })
    await get_tree().create_timer(0.5).timeout
    ToastService.i.info(description, {
        "duration": 4.0,
        "position": ToastConstants.ToastPosition.TOP_CENTER
    })

Feedback de combate

func show_damage(amount: int, is_critical: bool) -> void:
    var msg := "%d de daño" % amount
    var opts := { "position": ToastConstants.ToastPosition.CENTER, "duration": 1.5 }
    if is_critical:
        msg = "¡CRÍTICO! " + msg
        opts["background_color"] = Color("#FF0000")
        opts["text_color"] = Color.YELLOW
    ToastService.i.danger(msg, opts)

func show_heal(amount: int) -> void:
    ToastService.i.success("+%d HP" % amount, {
        "position": ToastConstants.ToastPosition.CENTER,
        "duration": 1.5,
        "font_size": 20,
    })

Guardado automático

func _on_autosave() -> void:
    ToastService.i.loader("Guardando...", {
        "position": ToastConstants.ToastPosition.BOTTOM_RIGHT,
        "duration": 1.0
    })
    await perform_save()
    ToastService.i.success("Partida guardada", {
        "position": ToastConstants.ToastPosition.BOTTOM_RIGHT
    })

Solución de problemas

Los toasts no aparecen

• Confirma que ensure_for(ToastService, ...) se llama antes de mostrar cualquier toast.
• Confirma que ss-gameforge-singleton y ss-gameforge-toast están activados en Plugins.

Los íconos aparecen en blanco

• Verifica que la ruta del ícono sea correcta y que exista el archivo .import.
• Usa assert(preload("res://...") != null) para detectar recursos faltantes.

Performance con muchos toasts

• Mantén max_visible entre 3–5.
• Reduce max_queue si no necesitas colas grandes.
• Usa duraciones más cortas.