Toast

ss-gameforge-toast lets you display temporary, non-intrusive notifications in your game. It supports 5 predefined styles, 9 screen positions, stacking, custom themes, and animated icons.

Dependency

This addon requires ss-gameforge-singleton. Install and enable it first.

Installation

1. Download ss-gameforge-toast from the releases page.
2. Copy addons/ss-gameforge-toast/ into your project’s res://addons/.
3. Enable ss-gameforge-singleton and ss-gameforge-toast in Project Settings → Plugins.

Initialize ToastService

Add this to your main scene or autoload:

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

Quick start

# Show different toast types
ToastService.i.info("Server is under maintenance")
ToastService.i.success("Game saved successfully!")
ToastService.i.danger("Connection lost")
ToastService.i.loader("Loading data...")

# Custom options on any toast
ToastService.i.info("Custom notification", {
    "duration": 5.0,
    "font_size": 18,
    "position": ToastConstants.ToastPosition.TOP_CENTER,
    "background_color": Color("#FF6B6B"),
    "text_color": Color("#FFFFFF")
})

Toast types

Method	Style	Default color	Use for
info(text, overrides)	INFO	Blue #2D9CDB	General messages
success(text, overrides)	SUCCESS	Green #27AE60	Completed operations
danger(text, overrides)	DANGER	Red #EB5757	Errors and warnings
custom(text, overrides)	CUSTOM	Dark gray #333333	Custom styling
loader(text, overrides)	LOADER	Blue (spinning icon)	Async operations
show(text, style, overrides)	Any	—	Generic entry point

# Generic show() with explicit style
ToastService.i.show("Message", ToastConstants.ToastStyle.SUCCESS, {"duration": 3.0})

Positions

Nine positions are available via ToastConstants.ToastPosition:

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

ToastService.i.success("Top right", {
    "position": ToastConstants.ToastPosition.TOP_RIGHT
})

# Custom margin from screen edges
ToastService.i.info("With margin", {
    "position": ToastConstants.ToastPosition.TOP_RIGHT,
    "position_margin": Vector2(50, 50)
})

Override options

Pass any of these keys in the overrides dictionary:

Key	Type	Default	Description
background_color	Color	Style default	Toast background
text_color	Color	Style default	Text color
font_size	int	14	Font size in pixels
icon	Texture2D	Style default	Icon texture
icon_color	Color	Color.WHITE	Icon tint
icon_size	float	18.0	Icon size in pixels
icon_spin	bool	false	Enable icon rotation
icon_spin_speed	float	1.5	Rotation speed (rad/s)
padding	float	10.0	Internal padding
corner_radius	float	10.0	Corner radius
position	ToastPosition	BOTTOM_CENTER	Screen position
position_margin	Vector2	Vector2(16, 16)	Distance from screen edges
duration	float	2.0	Visible time in seconds

ToastService properties

@export var theme: ToastTheme          # Global visual theme
@export var max_queue: int = 50        # Maximum queued toasts
@export var stack_toasts: bool = true  # Stack vs. single mode
@export var max_visible: int = 4       # Maximum visible at once
@export var stack_spacing: float = 8.0 # Pixels between stacked toasts

Stacking

Stacked mode (default)

Multiple toasts are visible simultaneously, stacked at their position.

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")  # All visible at once

Stack direction follows position:

• TOP positions → stack downward
• BOTTOM positions → stack upward
• CENTER positions → stack downward

Each position maintains an independent stack:

# Each group stacks independently
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})

Single mode

One toast at a time. The next waits for the current to finish.

ToastService.i.stack_toasts = false

Themes

Define a reusable ToastTheme resource to style all toasts consistently.

Create a theme in the inspector

Right-click in the FileSystem → New Resource → select ToastTheme. Configure:

• Duration, font_size, icon_size, corner_radius, padding, position_margin
• Per-style: info_background_color, info_text_color, info_icon, and equivalents for success_, danger_, custom_, loader_

Create a theme by code

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")

Apply a theme globally

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

Advanced examples

Achievement notification

func unlock_achievement(name: String, description: String) -> void:
    ToastService.i.success("Achievement Unlocked!", {
        "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
    })

Combat feedback

func show_damage(amount: int, is_critical: bool) -> void:
    var msg := "%d damage" % amount
    var opts := { "position": ToastConstants.ToastPosition.CENTER, "duration": 1.5 }
    if is_critical:
        msg = "CRITICAL! " + 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,
    })

Autosave

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

Troubleshooting

Toasts don’t appear

• Confirm ensure_for(ToastService, ...) is called before any toast.
• Confirm both ss-gameforge-singleton and ss-gameforge-toast are enabled in Plugins.

Icons appear blank

• Check the icon file path and verify the .import file exists.
• Use assert(preload("res://...") != null) to catch missing resources early.

Performance with many toasts

• Keep max_visible between 3–5.
• Reduce max_queue if you don’t need large queues.
• Use shorter durations.