Dialogue

ss-gameforge-dialogue provides a dialogue orchestration system decoupled from its visual presentation. Configure the content and behavior as a DialogueResource, display it with a DialogueView node, and style it with a DialogueTheme resource.

Installation

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

Core classes

Class	Description
DialogueResource	Holds dialogue lines, timing, and behavior settings.
DialogueView	UI node that renders and animates the dialogue.
DialogueTheme	Visual theme resource for the dialogue box.

DialogueResource

Create a new DialogueResource via New Resource in the inspector.

Properties

Property	Type	Default	Description
dialogues	Array[String]	[]	Lines of dialogue (text or translation keys).
use_translation	bool	true	If true, values are used as translation keys via tr().
auto_start	bool	false	Start playing automatically when the view is ready.
allow_skip	bool	true	Allow the player to skip the typewriter animation.
advance_mode	AdvanceMode	HYBRID	How the player advances through lines.
text_speed	float	0.075	Seconds per character in the typewriter effect.
time_to_start	float	0.25	Delay before the first line starts.
hold_after_line	float	0.75	Pause after a line finishes before auto-advancing.
open_time	float	0.55	Open animation duration.
open_transition	Tween.TransitionType	TRANS_ELASTIC	Easing type for the open animation.
close_time	float	0.20	Close animation duration.

Advance modes

enum AdvanceMode {
    AUTO,    # Lines advance automatically after hold_after_line
    MANUAL,  # Waits for ui_accept input
    HYBRID,  # Either input or timer advances
}

DialogueView

Add a DialogueView node to your scene (or instance the provided scene).

Properties

Property	Type	Description
resource	DialogueResource	Dialogue to play. Can be set before calling play().
dialogue_theme	DialogueTheme	Visual theme.
skip_action	StringName	Input action that advances dialogue (default: "ui_accept").

Signals

signal dialogue_started
signal line_changed(index: int)   # Fires when a new line begins (0-based)
signal dialogue_finished

Methods

func play(res: DialogueResource) -> void  # Start a dialogue sequence
func stop() -> void                        # Cancel immediately
func apply_theme() -> void                 # Re-apply theme after runtime changes

DialogueTheme

Create via New Resource → DialogueTheme.

Property	Type	Description
background_color	Color	Box fill color.
border_color	Color	Box border color.
border_width	int	Border width in pixels.
corner_radius	float	Corner radius.
padding	Vector2	Horizontal and vertical padding.
font_color	Color	Text color.
font_size	int	Font size.
font	Font	Custom font. Leave null to use the project default.
position_margin	Vector2	Distance from screen edges.

Quick start

1. Create a DialogueResource

Right-click in the FileSystem → New Resource → DialogueResource.

Set dialogues to your lines:

["Welcome, traveler.", "The path ahead is dangerous.", "Are you ready?"]

Set advance_mode to HYBRID (player input or timer advances).

2. Add a DialogueView to your scene

Instance addons/ss-gameforge-dialogue/scenes/dialogue_view.tscn, or add a Control node and attach a DialogueView script.

3. Play the dialogue

@onready var dialogue_view: DialogueView = $DialogueView

func _ready() -> void:
    dialogue_view.dialogue_finished.connect(_on_dialogue_done)
    dialogue_view.play(preload("res://dialogues/intro.tres"))

func _on_dialogue_done() -> void:
    print("Dialogue finished")

BBCode support

Dialogue lines support Godot BBCode tags. The typewriter effect correctly counts only visible characters:

"The [b]dragon[/b] awakens..."
"Your health is [color=green]full[/color]."
"[wave]Loading...[/wave]"

The built-in BBCodeParser utility handles visible character counting so skipping and advance timing work correctly with formatted text.

Translation integration

With use_translation = true, each string in dialogues is treated as a translation key:

# In the DialogueResource
dialogues = ["INTRO_LINE_1", "INTRO_LINE_2"]
use_translation = true

The view calls tr("INTRO_LINE_1") automatically before displaying each line.

Advanced example — NPC dialogue trigger

extends Area2D

@export var dialogue_resource: DialogueResource
@onready var dialogue_view: DialogueView = $DialogueView

var _player_inside := false

func _ready() -> void:
    body_entered.connect(_on_body_entered)
    body_exited.connect(_on_body_exited)
    dialogue_view.dialogue_finished.connect(_on_dialogue_finished)

func _on_body_entered(body: Node) -> void:
    if body.is_in_group("player"):
        _player_inside = true

func _unhandled_input(event: InputEvent) -> void:
    if _player_inside and event.is_action_pressed("ui_accept"):
        dialogue_view.play(dialogue_resource)

func _on_body_exited(body: Node) -> void:
    if body.is_in_group("player"):
        _player_inside = false
        dialogue_view.stop()

func _on_dialogue_finished() -> void:
    print("NPC dialogue done")