---
name: dialogic
description: Dialogic 2 addon for Godot 4 — a dialog system with timelines, events, characters, subsystems, styles, layouts, variables, save/load, and text effects. Use when working with dialog trees, visual novel scenes, character portraits, branching conversations, or any Dialogic-related code in this project.
---

# Dialogic 2 Skill

Dialogic is a Godot 4 addon (`addons/dialogic/`) providing a full dialog and visual novel system. It is an autoload (`Dialogic`) with a modular subsystem/event architecture.

> **Official docs:** https://docs.dialogic.pro/
> **Class Reference:** https://docs.dialogic.pro/class_index.html

## Architecture Overview

```
DialogicGameHandler (autoload "Dialogic")
├── Subsystems (modular, extendable)
│   ├── Animations    — tweening/transition helpers
│   ├── Audio         — sound effects, music, channels
│   ├── Backgrounds   — background images/scenes with transitions
│   ├── Choices       — branching choice menus
│   ├── Expressions   — expression/variable evaluation
│   ├── Glossary      — hover-to-inspect word definitions
│   ├── History       — conversation log
│   ├── Inputs        — keyboard/mouse input handling
│   ├── Jump          — label navigation & jump/return logic
│   ├── PortraitContainers — layout slots for portraits
│   ├── Portraits     — character portrait display & animation
│   ├── Save          — built-in save/load system
│   ├── Settings      — runtime settings
│   ├── Styles        — UI layout/style management
│   ├── Text          — text display with BBCode effects
│   ├── TextInput     — player text input prompts
│   ├── VAR           — variable storage & manipulation
│   └── Voice         — voice/audio per character line
```

## Core Files

| File | Purpose |
|------|---------|
| `addons/dialogic/Core/DialogicGameHandler.gd` | Autoload: manages state, timeline execution, subsystems |
| `addons/dialogic/Core/DialogicUtil.gd` | Static helpers (filesystem, variables, conversions, suggestions) |
| `addons/dialogic/Core/DialogicResourceUtil.gd` | Resource directory management, caches, lookups |
| `addons/dialogic/Core/Dialogic_Subsystem.gd` | Base class for all subsystems |
| `addons/dialogic/Resources/event.gd` | Base class for all events |
| `addons/dialogic/Resources/timeline.gd` | Timeline resource |
| `addons/dialogic/Resources/character.gd` | Character resource |
| `addons/dialogic/Resources/dialogic_style.gd` | Style resource |
| `addons/dialogic/Resources/dialogic_layout_base.gd` | Layout resource |
| `addons/dialogic/Resources/dialogic_layout_layer.gd` | Layout layer resource |
| `addons/dialogic/Resources/dialogic_style_layer.gd` | Style layer resource |

## DialogicGameHandler API (`Dialogic` autoload)

Access via `Dialogic` (global autoload name) or `DialogicUtil.autoload()`.

### States (enum `States`)

- `IDLE` — awaiting input to advance
- `REVEALING_TEXT` — currently revealing text
- `ANIMATING` — an animation is playing
- `AWAITING_CHOICE` — awaiting choice selection
- `WAITING` — awaiting something (e.g., timer)

`current_state` property; `state_changed(new_state)` signal.

### Pausing

```gdscript
Dialogic.paused = true   # pauses all subsystems (not the scene tree)
Dialogic.paused = false  # resumes
```

Signals: `dialogic_paused`, `dialogic_resumed`

### Starting/Ending Timelines

```gdscript
# Start a timeline AND load a layout scene (use for first dialog)
var layout_node = Dialogic.start(timeline, label_or_idx)
# timeline: DialogicTimeline resource OR string path OR identifier name
# label_or_idx: optional label (string) or event index (int) to jump to

# Start without loading layout (use when layout already exists)
Dialogic.start_timeline(timeline, label_or_idx)

# Preload (prepare without playing)
var preloaded = Dialogic.preload_timeline(timeline_resource)

# End the current timeline
Dialogic.end_timeline(skip_ending:=false)

# Check if timeline exists
if Dialogic.timeline_exists(timeline): ...

# Only start dialog if none is active
if Dialogic.current_timeline == null:
    Dialogic.start("my_timeline")
```

Signals: `timeline_started`, `timeline_ended`, `event_handled(resource)`

### Timeline Properties

```gdscript
Dialogic.current_timeline          # DialogicTimeline resource
Dialogic.current_timeline_events   # Array of event resources
Dialogic.current_event_idx         # int
Dialogic.current_state_info        # Dictionary of state info
```

### Clear States (enum `ClearFlags`)

```gdscript
Dialogic.clear(Dialogic.ClearFlags.FULL_CLEAR)         # clear everything
Dialogic.clear(Dialogic.ClearFlags.KEEP_VARIABLES)      # keep variables
Dialogic.clear(Dialogic.ClearFlags.TIMELINE_INFO_ONLY)  # only clear timeline/index
```

### Save/Load Full State

```gdscript
var state = Dialogic.get_full_state()   # returns Dictionary
Dialogic.load_full_state(state)         # restores full dialog state
```

### Event Handling

```gdscript
Dialogic.handle_next_event()            # advance to next event
Dialogic.handle_event(event_index)      # jump to specific event index
```

### Subsystem Access

All subsystems are accessible as properties:

```gdscript
Dialogic.Animations
Dialogic.Audio
Dialogic.Backgrounds
Dialogic.Choices
Dialogic.Expressions
Dialogic.History
Dialogic.Inputs
Dialogic.Jump
Dialogic.PortraitContainers
Dialogic.Portraits
Dialogic.Save
Dialogic.Settings
Dialogic.Styles
Dialogic.Text
Dialogic.TextInput
Dialogic.VAR
Dialogic.Voice
Dialogic.Glossary
```

Check existence: `Dialogic.has_subsystem("SubsystemName")`

## Timeline Events

Events are scripts in `addons/dialogic/Modules/<Module>/event_<name>.gd`. They extend `DialogicEvent` (base class in `Resources/event.gd`).

### Event Types

| Module | Event | Purpose |
|--------|-------|---------|
| Text | `event_text` | Display dialog text with character portrait |
| Character | `event_character` | Join/leave/update character portraits |
| Choice | `event_choice` | Present branching choices |
| Condition | `event_condition` | Branch based on variable conditions |
| Audio | `event_audio` | Play sound effects / music on channels |
| Background | `event_background` | Change background with transition |
| Jump | `event_jump` | Jump to a label |
| Jump | `event_label` | Define a label target |
| Jump | `event_return` | Return from a jump |
| Signal | `event_signal` | Emit custom signals |
| Variable | `event_variable` | Set/modify variables |
| Wait | `event_wait` | Wait for a duration |
| WaitInput | `event_wait_input` | Wait for player input |
| Clear | `event_clear` | Clear subsystems |
| Comment | `event_comment` | Editor-only comments |
| End | `event_end` | End the timeline |
| Save | `event_save` | Trigger save |
| Settings | `event_setting` | Change runtime settings |
| Style | `event_style` | Switch style/layout |
| Glossary | `event_glossary` | Manage glossary |
| History | `event_history` | Manage history |
| TextInput | `event_text_input` | Prompt player for text |
| Voice | `event_voice` | Play voice clip |
| Call | `event_call` | Call a method on an autoload |
| Core | `event_end_branch` | Internal branch-ending marker |

### Timeline Text Format

Timelines use the `.dtl` file extension and are saved in a human-readable text format. You can edit them in any text editor — Dialogic's built-in text editor provides autocompletion and syntax highlighting.

> To find all parameters available on each shortcode event, search for the event class name (e.g. `DialogicBackgroundEvent`) in the Godot Help or the [Dialogic documentation](https://docs.dialogic.pro/).

#### Indentation Rules

Timelines use **TAB indentation** to determine which events belong to a choice or condition block. Only changes in indentation matter — be consistent within one block, but the exact amount doesn't matter.

#### Custom-Syntax Events (bare text, no brackets)

Some events have a special syntax for easier writing:

**Text Event:**
```
# Plain text with no speaker — said by no one in particular
A simple line of narration or internal monologue.

# Speaker with optional portrait
CharacterName: Dialog text here.
CharacterName (portrait): Dialog text with a portrait change.

# Multi-line text — end a line with \ to include the next line
Emilio: This is a text event with \
multiple lines. Isn't that great? It is!
```
The `\` continuation joins the next line into the same text event. Trailing whitespace after `\` is ignored.

**Character Event:**
```
join CharacterName (portrait) position [animation="Bounce In"]
leave CharacterName [animation="Bounce Out" length="0.3"]
update CharacterName (portrait) position [animation="Tada" wait="true" repeat="3" move_time="0.3"]
```
Positions: `left`, `center`, `right`. The animation shortcode at the end contains optional parameters.

**Condition Event** (indentation-based blocks):
```
if {Player.Wisdom} > 3:
    # indented events run when condition is true
elif {Player.Health} <= 10:
    # another branch
else:
    # fallback — runs if no condition matched
```

**Choice Event** (each option starts with `-`):
```
- Yes, let's go!
    # indented events fire when this option is chosen
- No, not now. | [if {John.Relationship} > 23]
    # conditional choice — only shown if condition is true
- Maybe | [if {Stats.Charisma} > 10] [else="disable" alt_text="Maybe [too insecure]"]
```
The `|` separator attaches logic to the choice option. `[if]` controls visibility; `[else]` controls behavior when hidden (`disable` or `hide`).

**Set Variable Event:**
```
set {coins} = 20
set {Player.Health} += 10
set {Player.Shield} -= 5
set {Player.Damage} *= 1.5
set {Player.Speed} /= 2
set {player_name} = "Miko"
set Autoload.property = "Hello World"
```
Supported operators: `=`, `+=`, `-=`, `*=`, `/=`

**Comment Event** (editor-only, ignored at runtime):
```
# This is a comment — useful for notes and organization
```

**Label Event:**
```
label LabelIdentifier
label LabelIdentifier (Display Name)
```

**Jump Event:**
```
jump LabelIdentifier                 # jump to a label in the current timeline
jump TimelineName/LabelIdentifier    # jump to a label in another timeline
jump TimelineName/                   # jump to the beginning of another timeline
```

**Return Event:**
```
return
```
Returns from a previous `jump` to where the jump originated.

**Do/Call Event:**
```
do AutoloadName.method("argument")
```
Calls a method on any autoload singleton.

#### Shortcode Events (wrapped in `[...]`)

Most other events use a shortcode style. Parameters are separated by at least one space (order doesn't matter). All parameter values must be wrapped in double quotes, regardless of type:

```
[background path="res://icon.png" fade="1.0"]
[audio path="res://music.ogg" channel="music" fade="1.0"]
[signal arg="activate_something"]
[end_timeline]
[wait time=1.5]
[clear time=0.5]
[style name="MyStyle"]
[save slot="auto"]
[text_input text="What's your name?" var="player_name" placeholder="Enter..." default="Hero" allow_empty="false"]
```

#### Full Example Timeline

```
[background path="res://assets/backgrounds/dialogic_factory.png"]

join Jowan left
Jowan (excited): Hello and welcome to[portrait=confused]...[pause=0.5] Wait? What is this?

join Emilio (happy) right
Emilio: Well, this is the example timeline.

Jowan: I thought this was a cool new feature?

Emilio: Nah, sorry.

Jowan (sad): It's okay.

# Choices loop back to this label
label WhatAbout

Jowan (default): So what should this example be about?
- How to bake cookies
    Emilio (confused): Wait that hasn't to do with dialogic?!
    jump WhatAbout

- How to reach the moon | [if {Player.Name} == "NASA"]
    Jowan (angry): NASA! It's you again. This is for making dialogs!\
    Please ask someone else about the moon!

    jump WhatAbout

- How to write timelines in text format
    Jowan: Oh, well it's pretty intuitive.[pause=0.2][portrait=questioning] I hope.

    Emilio: Let's hope it's easy as well.

[end_timeline]
```

## Characters

Characters are `.dch` resources managed via `DialogicResourceUtil`:

```gdscript
var char = DialogicResourceUtil.get_character_resource("CharacterName")
var all_chars = DialogicResourceUtil.get_character_directory()
```

### Character Properties

- **Display Name**: Shown on name labels. Can contain `{variables}`.
- **Nicknames**: Used for autocolor names feature.
- **Default Portrait**: Used when no portrait is specified (Character join, `[portrait]` text effect). Does NOT affect Text events without a portrait.
- **Portraits**: Dictionary of portrait name → scene settings. A portrait is a scene (`.tscn`) instanced by Dialogic. The default portrait scene uses an image. Custom portraits extend `DialogicPortrait`.
- **Style**: Optional custom style used when this character speaks.
- **Sound Moods**: Random typing sounds per portrait.
- **Prefix/Suffix**: Text segments wrapped around each text section (e.g., quotation marks).
- **Scale, Offset, Mirror**: Per-character and per-portrait transform settings.

### Character lookup

Characters are found by identifier string in the `dch_directory`. The directory maps identifiers to file paths. By default, the identifier is derived from the filename (e.g., `Miko.dch` → `"Miko"`). The lookup is **case-sensitive** — ensure timeline text uses the exact same case as the `.dch` filename.

If a character is not found at runtime, Dialogic creates a temporary character with no portraits. Portraits won't display because `change_speaker()` skips characters with empty portraits.

## Character Event

The Character event controls how characters with portraits appear, move, and leave the scene. It has three modes: **Join**, **Leave**, and **Update**.

### Modes

| Mode | Keyword | Purpose |
|------|---------|--------|
| **Join** | `join` | Add a character to the scene. Requires a position/transform. Uses `In`-animations. |
| **Leave** | `leave` | Remove a character. Uses `Out`-animations. `--All--` removes all joined characters. |
| **Update** | `update` | Modify an existing character's portrait, position, mirroring, z-index, extra data, or play an animation. Only changes what is explicitly set — unspecified properties stay unchanged. |

### Text Syntax

```
# Basic join — character at a preset position
join MyCharacter center

# Join with portrait and animation
join MyCharacter (SomePortrait) center [animation="Bounce In"]

# Join a character whose name contains spaces (quoted) with a grouped portrait
join "My Character" (Special/Crazy) center

# Join with manual transform (position, size, rotation)
join MyCharacter pos=x0.5y1 size=y400px rot=20

# Basic leave
leave MyCharacter

# Leave with animation parameters
leave MyCharacter [animation="Fade Down"]

# Leave all characters at once
leave --All--

# Update: animate the character
update MyCharacter [animation="Tada" length="2" wait="true"]

# Update: move character with tween
update MyCharacter left [move_time="1" move_trans="Elastic" move_ease="In"]

# Update: change portrait with crossfade
update MyCharacter (OtherPortrait) [fade_time="0.5"]
```

### Main Settings

#### Character

The character identifier (from the `.dch` filename). If the name contains spaces, wrap it in double quotes: `"My Character"`. For `leave`, use `--All--` to remove all joined characters.

#### Portrait (optional)

The portrait to display, specified in parentheses after the character: `(portrait_name)`. Portraits in groups use the full path: `(Group/SubGroup/Portrait)`. The portrait can be an expression inside `{curly braces}`: `({PlayerPortrait})`.

- **Join**: Uses the character's default portrait if omitted.
- **Update**: Does NOT change the portrait unless one is given (gated by `set_portrait`).
- **Leave**: Ignored.

#### Position / Transform

Defines where the character appears. Two approaches:

**Preset positions** — reference a `PortraitContainer` defined in your style layer:
```
join MyCharacter left
join MyCharacter center
```
Default presets: `leftmost`, `left`, `center`, `right`, `rightmost`. Add more by creating a custom portrait layer.

**Manual transform commands** — precise control with `pos=`, `size=`, `rot=`:
```
join MyCharacter pos=x0.5y1 size=y400px rot=20
```
- `pos=x0.5 y1` — position (default: relative to viewport; x=1 is full width, y=1 is full height)
- `pos=x100px y1%` — can also use `px` or `%` units
- `size=x0.3y0.3` — size relative to viewport
- `rot=20` — rotation in degrees around the portrait origin (usually bottom center)

The position defines the ORIGIN of the portrait container. When joining, position/size/rotation defaults are copied from the first portrait preset found — so `pos=x0.3` alone is usually sufficient to vary along the x-axis.

### Animation Settings (shortcode)

All animation parameters go in the `[...]` shortcode at the end:

| Parameter | Shortcode | Description |
|-----------|-----------|-------------|
| Animation name | `animation="Bounce"` | Animation to play. Forgiving match: `Fade Up`, `fade up in`, `fade In Up` all resolve correctly. Join/Leave fall back to Settings defaults if omitted; Update plays nothing if omitted. |
| Length | `length="1"` | Animation duration in seconds. Default: `0.5`. |
| Wait | `wait="true"` | If true, pauses the timeline until the animation finishes. Default: `false`. |
| Repeat | `repeat="3"` | **Update only.** Number of times to repeat the animation. Default: `1`. |

### Fade Settings (shortcode, Update mode only)

Used when changing a portrait during an Update event:

| Parameter | Shortcode | Description |
|-----------|-----------|-------------|
| Fade animation | `fade="Fade"` | Crossfade animation for portrait transition. Falls back to the default crossfade in Settings if omitted. |
| Fade length | `fade_length="0.5"` | Crossfade duration in seconds. Default: `0.5`. |

### Move Settings (shortcode, Update mode only)

Used when changing position during an Update event to tween the movement:

| Parameter | Shortcode | Description |
|-----------|-----------|-------------|
| Move time | `move_time="0.8"` | Tween duration in seconds. If `0` (default), the change is instant. |
| Move transition | `move_trans="Elastic"` | Tween transition type. |
| Move easing | `move_ease="In Out"` | Tween easing direction. |

**Transition types:** `Linear`, `Sine`, `Quint`, `Quart`, `Quad`, `Expo`, `Elastic`, `Cubic`, `Circ`, `Bounce`, `Back`, `Spring`

**Easing types:** `In`, `Out`, `In Out`, `Out In`

Reference: [Godot Tween Cheat Sheet](https://raw.githubusercontent.com/godotengine/godot-docs/master/img/tween_cheatsheet.webp)

### Other Settings (shortcode)

| Parameter | Shortcode | Description |
|-----------|-----------|-------------|
| Z-Index | `z_index="2"` | Controls visual stacking order. Higher values appear in front. NOT Godot's native z_index — Dialogic sorts manually. |
| Mirrored | `mirrored="true"` | Flips the portrait horizontally. Applied on top of the portrait's and container's mirror settings. |
| Extra Data | `extra_data="something"` | Arbitrary string passed to the portrait scene. Handled by `_set_extra_data(data)` on custom portraits. |

### Portrait Expressions

The portrait field supports `{curly brace}` expressions evaluated at runtime:
```
join MyCharacter ({PlayerPortrait}) center
update MyCharacter ({CurrentMood})
```
Useful for dynamic portrait switching based on variables.

### Character with No Portraits

If a character has no portraits (empty `portraits` dictionary), the Character event editor hides portrait/position options. Timeline text using that character will still parse but no portrait will display.

## Jump, Label & Return Events

These three events work together to control timeline flow: **Label** defines anchor points, **Jump** changes the current position (within or across timelines), and **Return** goes back to the last jump origin. Jumps use a **stack** to track where you came from.

### Text Syntax

```
# Jump to the beginning of the current timeline (no target)
jump

# Jump to a label in the current timeline
jump LabelIdentifier

# Jump to a label in another timeline
jump TimelineName/LabelIdentifier

# Jump to the beginning of another timeline
jump TimelineName/

# Define a label (anchor point)
label LabelIdentifier

# Label with a display name (for debugging/history)
label LabelIdentifier (Display Name)

# Return to the last jump point
return
```

**Dynamic labels:** Labels can include `{variables}` for runtime resolution:
```
jump {day_phase}
```

### How the Jump Stack Works

1. When a **Jump** event executes, the current timeline + event index is **pushed** onto a stack.
2. Execution moves to the target (label, timeline start, etc.).
3. When a **Return** event executes, the stack is **popped** and execution resumes at the saved timeline + index.
4. If the stack is empty when a Return event is hit, the timeline ends (`dialogic.end_timeline()`).

This allows building reusable timeline "subroutines" — jump to a timeline, run it, and return to exactly where you left off.

### Subsystem API (`Dialogic.Jump`)

```gdscript
# Jump to a specific label in the current timeline (bypasses the stack)
Dialogic.Jump.jump_to_label("LabelIdentifier")

# Resume from the last jump (pops the stack)
Dialogic.Jump.resume_from_last_jump()

# Check if the jump stack is empty
if Dialogic.Jump.is_jump_stack_empty():
    print("No jump to return to")

# Start a timeline at a specific label
Dialogic.start(timeline, "LabelIdentifier")

# Get info about the last passed label
var label_id = Dialogic.Jump.get_last_label_identifier()
var label_name = Dialogic.Jump.get_last_label_name()
```

### Jump Signals

```gdscript
# Emitted when a Jump event switches to a different timeline
Dialogic.Jump.switched_timeline.connect(func(info):
    print("Switched from ", info.previous_timeline, " to ", info.timeline, " at ", info.label))
# info = {"previous_timeline": DialogicTimeline, "timeline": DialogicTimeline, "label": ""}

# Emitted when a Jump event jumps to a label (same or different timeline)
Dialogic.Jump.jumped_to_label.connect(func(info):
    print("Jumped to label ", info.label, " in ", info.timeline))
# info = {"timeline": DialogicTimeline, "label": "label_name"}

# Emitted when a Return event pops the stack
Dialogic.Jump.returned_from_jump.connect(func(info):
    print("Returned from ", info.sub_timeline, " to label ", info.label))
# info = {"sub_timeline": DialogicTimeline, "label": "label_name"}

# Emitted when a Label event is passed during execution
Dialogic.Jump.passed_label.connect(func(info):
    print("Passed label ", info.identifier, " (", info.display_name, ")"))
# info = {"identifier": "name", "display_name": "Name", "display_name_orig": "Name", "timeline": "timeline_id"}
```

## Variables

Dialogic has a built-in variable system with folders, types, and expression evaluation. Variables can also reference external autoload singletons.

### Storage Architecture

- **Default values** are stored in `ProjectSettings` under `dialogic/variables` as a nested Dictionary. This is where the Variables editor persists them.
- **Runtime values** are stored in `Dialogic.current_state_info['variables']` — a copy of the defaults merged with current state.
- **Folder grouping** is represented by nested Dictionaries. A dotted path like `Player.Health` maps to `{"Player": {"Health": 100}}`.
- On `Dialogic.VAR.reset()` or `Dialogic.clear(..., false)`, runtime values are reset to the defaults from ProjectSettings.

### Variable Editor

Set up variables in the Dialogic "Variables" tab. Each variable has a **name** and **default value**. Variables can be organized into **folders** (nested Dictionaries). Inside a folder, no two items (variable or subfolder) can share the same name.

**Variable types** (from `DialogicUtil.VarTypes` enum):
- `ANY` — auto-detected from default value
- `STRING` — text
- `FLOAT` — floating point number
- `INT` — integer
- `BOOL` — true/false

### Referencing Variables

**Dialogic variables** use dotted paths for folders; wrap in `{curly braces}`:
```
{coins}                          # root-level variable
{Player.Health}                  # variable inside a folder
{FolderA.FolderB.variable_name}  # nested folders
```

**Autoload variables** are referenced by `AutoloadName.property`:
```
{MySingleton.player_name}
{GameState.difficulty}
{MyAutoload.get_random_name()}   # method calls return their result
```

**Complex expressions** are supported:
```
{{Player.Health}/10.0+2}
```

**Important:** Dialogic variables (native, no autoload prefix) **must be pre-declared** in the Variables editor before they can be set by timeline `set` commands or referenced in text. Referencing an undeclared variable evaluates to `null` (empty string in text). Autoload variables do NOT need pre-declaration — they're accessed directly via the `Expression` class.

**Availability:** Variables are only accessible after the `Dialogic` autoload is `_ready()`. Do not read/write variables in `_ready()` of nodes that load before Dialogic.

### Using Variables in the Timeline

#### In Text Events

Insert variable values with curly braces:
```
You have {coins} coins remaining.
Hello, {PlayerName}!
Next level at {MyAutoload.xp_required} XP.
```

Variables can also be used in:
- **Character Display Names** — type `{MyVariableName}` in the character editor's display name field.
- **Glossary entries** — titles, texts, and extras all support the same `{curly braces}` syntax.

#### In Conditions

```
if {coins} >= 10:
    # indented events run when true
elif {Player.Health} <= 5:
    # another branch
else:
    # fallback
```

Conditions can also reference autoloads without curly braces (bare names are treated as autoload names by Godot's `Expression` class):
```
if GameState.difficulty == "hard":
if MyAutoload.check_info("Argument", false):
```

Use typical boolean operators: `==`, `!=`, `<`, `>`, `<=`, `>=`, `not`, `and`, `or`, and parentheses for grouping.

#### Set Variable Event

**Text syntax:**
```
# Dialogic variables (pre-declared)
set {coins} = 20
set {Player.Health} += 2
set {Player.Shield} -= 5
set {Player.Damage} *= 1.5
set {Player.Speed} /= 2

# String assignment
set {player_name} = "Miko"

# Autoload variables (no pre-declaration needed)
set Autoload.property = "Hello World"
set Autoload.health = {Player.Health} + 2

# Complex expressions
set {Player.Health} += range(10, 20).pick_random()
```

**Operations:** `=` (SET), `+=` (ADD), `-=` (SUBTRACT), `*=` (MULTIPLY), `/=` (DIVIDE)

String concatenation is supported with `+=` when both the variable and value are strings.

**Value types** (selectable in the visual editor):
| Type | Example | Description |
|------|---------|-------------|
| String | `"Hello"` | Quoted string literal |
| Number | `42` or `3.14` | Float or integer |
| Variable | `{OtherVar}` | Value of another variable |
| Bool | `true` / `false` | Boolean literal |
| Expression | `range(10,20).pick_random()` | Complex GDScript expression |
| Random Number | `range(0, 100).pick_random()` | Random integer in range |

#### Text Input Event

The Text Input event prompts the player to type text and stores the result in a dialogic variable:
```
[text_input text="What's your name?" var="player_name" placeholder="Enter name..." default="Hero" allow_empty="false"]
```
This is a specialized form of set variable that captures player keyboard input.

### Accessing Variables from Code

#### Using `Dialogic.VAR` Subsystem

```gdscript
# Direct property access (simple and preferred)
Dialogic.VAR.coins = 42
print(Dialogic.VAR.coins)
Dialogic.VAR.Player.Health = 100          # folder access
print(Dialogic.VAR.Player.Health)          # 100

# String-based access (useful for dynamic variable names)
Dialogic.VAR.set_variable("coins", 42)
print(Dialogic.VAR.get_variable("coins"))
Dialogic.VAR.set_variable("Player.Health", 100)

# Check existence
if Dialogic.VAR.has("coins"):
    print("coins exists")

# Reset to defaults
Dialogic.VAR.reset()                      # reset all variables
Dialogic.VAR.reset("Player.Health")       # reset one variable to its default

# Parse curly-brace expressions in strings
var result = Dialogic.VAR.parse_variables("You have {coins} coins.")
```

#### Using `DialogicUtil` (static helpers)

```gdscript
DialogicUtil.get_default_variables()       # returns the full default variable dict
DialogicUtil.list_variables(dict, path)    # flatten to array of dotted paths
DialogicUtil.get_variable_type(path, dict) # get VarTypes enum value
DialogicUtil.get_variable_value_type(value) # get type of a value
DialogicUtil.logical_convert(value)        # auto-convert string to int/float/bool
```

#### Variable Folders

When accessing via direct property access (`Dialogic.VAR.MyFolder`), folders return a `VariableFolder` object that supports:
- `folders()` — list all subfolders (as `VariableFolder` objects)
- `variables(absolute=false)` — list variable names in this folder
- `has(name)` — check if a variable or subfolder exists
- Direct property access to child variables: `Dialogic.VAR.Towns.TownA.Church`

Example:
```gdscript
# Pick a random location from nested folder structure
var location = Dialogic.VAR.Towns.folders().pick_random().variables().pick_random()
```

### Variable Signals

```gdscript
# Emitted whenever any Dialogic variable changes
Dialogic.VAR.variable_changed.connect(func(info):
    print(info.variable, " changed to ", info.new_value))
# info = {"variable": "variable_name", "new_value": new_value}

# Emitted specifically from Set Variable events (not direct code sets)
Dialogic.VAR.variable_was_set.connect(func(info):
    print(info.variable, ": ", info.orig_value, " -> ", info.new_value))
# info = {"variable": name, "orig_value": old, "new_value": result, "value": change_value, "value_str": raw_string}
```

## Writing Text

When writing text in Text events or Choice events, you can use four complementary systems: **BBCode**, **Variables/Expressions**, **Text Modifiers**, and **Text Effects**.

### BBCode (Styling)

Standard Godot BBCode tags work in Text events for visual styling. Full reference: [BBCode in RichTextLabel](https://docs.godotengine.org/en/stable/tutorials/ui/bbcode_in_richtextlabel.html).

Common tags:
```
[b]Bold[/b]  [i]Italic[/i]  [u]Underline[/u]  [s]Strikethrough[/s]
[color=#ff0000]Colored text[/color]  [color=red]Named color[/color]
[font=res://my_font.ttf]Custom font[/font]  [font_size=24]Bigger text[/font_size]
[img=32x32]res://icon.png[/img]                    # inline image
[url=https://example.com]Link[/url]                # clickable link
[wave amp=20 freq=2]Wave effect[/wave]             # animated wave
[tornado radius=10 freq=5]Tornado effect[/tornado]  # animated shake
[shake rate=10 level=15]Shake effect[/shake]        # animated shake
[fade start=4 length=20]Fade effect[/fade]          # fading characters
[rainbow freq=0.2 sat=1 val=1]Rainbow text[/rainbow] # color cycling
```

**Important:** BBCode tags must be properly paired with closing tags (`[/tag]`). This differs from Text Effects which have no closing tag.

**Choice buttons:** Standard choice buttons use `Label` (not `RichTextLabel`), so BBCode won't work there. To get BBCode on choices, use a custom choice button with `RichTextLabel`.

### Variables / Expressions in Text

Anything in `{curly braces}` inside text is treated as an expression and evaluated at display time. The result is inserted as text:

```
You have {coins} coins remaining.
Hello, {PlayerName}!
Current HP: {Player.Health}                         # folder path
Next level at {MyAutoload.xp_required} XP.           # autoload property
Your lucky number is {MySingleton.get_random_name()} # autoload method
Stat bonus: {{Player.Health}/10.0+2}                 # complex expression
```

- **Dialogic variables** — resolved by dotted path: `{coins}`, `{Player.Health}`, `{FolderA.FolderB.var}`
- **Autoload properties** — resolved via Godot's `Expression` class: `{MySingleton.some_property}`
- **Autoload methods** — called and result inserted: `{MyAutoload.get_random_name()}`
- **Complex expressions** — nested braces for calculations: `{{Player.Health}/10.0+2}`

**Important:** Dialogic-native variables must be pre-declared in the Variables editor. Referencing an undeclared variable evaluates to `null` and displays as an empty string. Autoload variables don't need pre-declaration.

### Text Modifiers (Preprocessors)

Text modifiers run **before** the text is displayed, transforming the text string. They work in both Text events and Choice events (most of them).

See the [Text Modifiers](#text-modifiers-preprocessors) section below for the full list.

### Text Effects (Reveal-Time Actions)

Text effects are tags that trigger an action when the text reveal reaches that position. They are NOT paired — there is no closing tag. They work only in Text events.

See the [Text Effects](#text-effects-inline-bbcode) section below for the full list.

### Text Speed System

Dialogic has three interacting speed controls:

| Control | Scope | Description |
|---------|-------|-------------|
| **Letter speed** | Per-event (via `[lspeed]`) | Time in seconds for each letter to reveal. Default set in Text Settings. |
| **Speed multiplier** | Per-event (via `[speed]`) | Multiplies letter speed and pause length. 1 = normal, 0 = instant, >1 = slower. Resets each Text event. |
| **Text Speed setting** | Global (via `Dialogic.Settings`) | Global multiplier; stored automatically. Use for in-game speed options: `Dialogic.Settings.text_speed = 0.5` |

All three multiply together: `actual_delay = letter_speed × speed_multiplier × text_speed_setting`

Adding `!` to `[lspeed=x!]` or `[pause=x!]` makes the value absolute (ignores both multipliers).

### Custom Text Modifiers

Custom modules can register text modifiers by implementing `_get_text_modifiers()`:

```gdscript
func _get_text_modifiers() -> Array[Dictionary]:
    return [
        {
            "subsystem": "MySubsystem",
            # or "node_path": "/root/MyAutoload",
            "method": "my_modifier_method",
            "mode": -1  # -1 = Text & Choice, 0 = Texts only, 1 = Choices only
        }
    ]
```

The modifier method receives a `String` and must return a `String`:

```gdscript
func my_modifier_method(text: String) -> String:
    # transform text here (regex, custom syntax, etc.)
    return text
```

## Text Effects (inline BBCode)

Text effects are tags within TextEvent text that trigger actions when reached during text reveal:

| Effect | Syntax | Purpose |
|--------|--------|---------|
| Speed | `[speed=x]` / `[speed]` | Set speed multiplier (1 = normal, 0 = instant). Resets per event. |
| Letter Speed | `[lspeed=x]` / `[lspeed]` / `[lspeed=x!]` | Set letter reveal time in seconds. Bare resets to default. `!` makes it absolute (ignores multipliers). |
| Pause | `[pause=x]` / `[pause=x!]` | Pause reveal for x seconds. `!` makes it absolute. |
| Portrait | `[portrait=name]` | Switch speaker's portrait mid-text. |
| Signal | `[signal=arg]` | Emit `Dialogic.text_signal` with argument. |
| Mood | `[mood=name]` | Change typing sound mood. |
| Extra Data | `[extra_data=value]` | Set extra data on speaker's portrait. |
| New Event | `[n]` / `[n+]` | Split text into manual-advance sections. `+` appends to previous without clearing. |
| Input | `[input]` | Await any input (can be skipped). |
| Auto-Advance | `[aa]` / `[aa=x]` / `[aa=x?]` | Enable auto-advance. `x` sets time. `?` sets time without enabling. |
| No Skip | `[ns]` / `[ns=x]` | Disable text skipping for this event. `x` sets auto-advance time. |

**Important:** Text effects are NOT paired — there is no `[/speed]` closing tag. Effects change behavior from that point until the next text event resets them. Writing `[/speed]` will appear as visible text.

## Text Modifiers (preprocessors)

Text modifiers run on text before display:

| Modifier | Syntax | Purpose |
|----------|--------|---------|
| Line Break | `[br]` | Insert line break (useful in choices or with "New Lines as New events") |
| Random Selection | `<Option1/Option2/Option3>` | Random variation for repeated text |
| Conditional Text | `[if {cond} Text if true./Text if false.]` | Inline conditional text |
| Autopauses | (automatic) | Insert `[pause]` after configured punctuation characters |

## Auto-Advance

Auto-Advance automatically progresses the timeline without user input — ideal for hands-free reading or visual novel "auto-forward" modes. It is managed through `Dialogic.Inputs.auto_advance`, a `DialogicAutoAdvance` object.

### Enable Flags (Stackable)

Auto-Advance uses three independent boolean flags — if **any** is `true`, Auto-Advance is active. This stacking allows multiple systems to enable it without conflicting:

| Flag | Set via | Stays enabled until |
|------|---------|---------------------|
| `enabled_until_user_input` | Player toggles Auto-Advance on | Player presses any Dialogic input action |
| `enabled_until_next_event` | `[aa]` text effect or code | The next text event begins |
| `enabled_forced` | Code: `auto_advance.enabled_forced = true` | Code: `auto_advance.enabled_forced = false` |

**Example:** If the player enables Auto-Advance AND a text event uses `[aa]`, disabling one flag won't stop it until all flags are cleared.

### Configuring from Code

```gdscript
# Enable Auto-Advance (player toggle)
Dialogic.Inputs.auto_advance.enabled_until_user_input = true

# Enable until next event (e.g., for a cutscene)
Dialogic.Inputs.auto_advance.enabled_until_next_event = true

# Force enable (script-controlled)
Dialogic.Inputs.auto_advance.enabled_forced = true

# Check if currently enabled
if Dialogic.Inputs.auto_advance.is_enabled():
    print("Auto-advancing")

# Check if currently waiting (timer active)
if Dialogic.Inputs.auto_advance.is_advancing():
    print("Timer running: ", Dialogic.Inputs.auto_advance.get_time_left())
```

### Delay Calculation

When Auto-Advance starts, the delay is calculated from the current text:

```
delay = (per_word_delay × word_count + per_character_delay × char_count) × delay_modifier + fixed_delay
```

| Property | Default | Description |
|----------|---------|-------------|
| `fixed_delay` | `1.0` | Base delay in seconds added after other calculations |
| `per_word_delay` | `0.0` | Extra seconds per whitespace-separated word |
| `per_character_delay` | `0.1` | Extra seconds per character (excluding ignored characters) |
| `delay_modifier` | `1.0` | Global multiplier on per-word + per-character delays (NOT on fixed_delay). Set via `Dialogic.Settings.autoadvance_delay_modifier` for player-configurable reading speed. |
| `await_playing_voice` | `true` | If true, waits for voice audio to finish before advancing |
| `ignored_characters_enabled` | `false` | If true, certain characters are excluded from the character count |
| `ignored_characters` | `{}` | Dictionary of characters to ignore when counting |

**Temporary override** per event via `[aa=x]`: sets `override_delay_for_current_event`, which replaces the entire calculation (but still respects `await_playing_voice`).

```gdscript
# Adjust delays dynamically (e.g., for different languages)
Dialogic.Inputs.auto_advance.per_word_delay = 0.3
Dialogic.Inputs.auto_advance.per_character_delay = 0.1

# Set a global reading speed modifier (player setting)
Dialogic.Settings.autoadvance_delay_modifier = 0.5   # 2x faster
```

### Text Effect: `[aa]`

| Syntax | Behavior |
|--------|----------|
| `[aa]` | Enables Auto-Advance until the next text event |
| `[aa=2]` | Enables Auto-Advance AND sets the delay to 2 seconds (absolute, ignores per_word/per_character) |
| `[aa=2?]` | Does NOT enable Auto-Advance, but sets the delay to 2 seconds IF already enabled |

### Signals

```gdscript
# Emitted when Auto-Advance should progress (triggers handle_next_event)
Dialogic.Inputs.auto_advance.autoadvance

# Emitted when Auto-Advance toggles on/off
Dialogic.Inputs.auto_advance.toggled.connect(func(enabled: bool):
    print("Auto-Advance ", "enabled" if enabled else "disabled"))

# Force an immediate advance
Dialogic.Inputs.auto_advance.autoadvance.emit()
```

### Querying Progress

```gdscript
# Timer progress from 0.0 to 1.0 (returns -1 if not advancing)
var progress = Dialogic.Inputs.auto_advance.get_progress()

# Time remaining before the next advance
var remaining = Dialogic.Inputs.auto_advance.get_time_left()
```

Useful for building an Auto-Advance indicator UI (progress bar or countdown) in your layout layer.

## Manual-Advance

Manual-Advance is the default way players progress through timelines — clicking or pressing the `dialogic_default_action` input to move forward event by event. It's managed through `Dialogic.Inputs.manual_advance`, a `DialogicManualAdvance` object.

### Controlling Manual-Advance

Two properties control whether the player can advance:

| Property | Type | Description |
|----------|------|-------------|
| `system_enabled` | `bool` (default `true`) | Master switch. When `false`, player input is completely ignored. |
| `disabled_until_next_event` | `bool` (default `false`) | Temporarily blocks input for the current event only. Overrides `system_enabled`. |

```gdscript
# Disable all player input (e.g., during a cutscene)
Dialogic.Inputs.manual_advance.system_enabled = false

# Block input just until the next event (e.g., [ns] text effect uses this)
Dialogic.Inputs.manual_advance.disabled_until_next_event = true

# Check if the player can currently advance
if Dialogic.Inputs.manual_advance.is_enabled():
    print("Player can advance")
# Equivalent to: system_enabled and not disabled_until_next_event
```

### Input Events

Dialogic listens for the input action configured in `dialogic/text/input_action` (default: `dialogic_default_action`). Input is handled via:
- **Keyboard/controller** → `_unhandled_input()` (non-mouse events)
- **Mouse** → `_input()` or `handle_node_gui_input()` (via InputCatcher/Textbox nodes)

**Blocking input temporarily:** Dialogic automatically blocks input for ~100ms after text finishes revealing to prevent accidental double-clicks. Call `Dialogic.Inputs.block_input(time)` to extend this.

```gdscript
# Block all input for 0.5 seconds
Dialogic.Inputs.block_input(0.5)

# Check if input is currently blocked
if Dialogic.Inputs.is_input_blocked():
    print("Input is blocked")
```

### Input Action Signals

```gdscript
# Priority signal — fires first. Set action_was_consumed = true to swallow the input
Dialogic.Inputs.dialogic_action_priority.connect(func():
    if some_condition:
        Dialogic.Inputs.action_was_consumed = true)

# Main action signal — fires if action_was_consumed is still false
Dialogic.Inputs.dialogic_action.connect(_on_dialogic_action)

# Check if the input came from a mouse
if Dialogic.Inputs.input_was_mouse_input:
    print("Mouse click")
```

## Auto-Skip

Auto-Skip rapidly advances through the timeline, bypassing animations, text reveal, and audio. It's useful for quickly navigating already-seen story branches or debugging. Managed through `Dialogic.Inputs.auto_skip`, a `DialogicAutoSkip` object.

### Core Settings

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | `bool` | `false` | Master toggle. Toggling it emits the `toggled` signal. |
| `time_per_event` | `float` | `0.1` | Maximum seconds each event may take. Events themselves must respect this — it's not enforced centrally. |
| `skip_voice` | `bool` | `true` | If true, voice audio is skipped instead of played. |

### Auto Disable/Enable Conditions

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disable_on_user_input` | `bool` | `true` | Disables Auto-Skip when the player presses any Dialogic input action. |
| `disable_on_unread_text` | `bool` | `false` | Disables when reaching a text event the player hasn't seen before. Requires History subsystem. |
| `enable_on_visited` | `bool` | `false` | Enables Auto-Skip when reaching a previously-visited text event. |

```gdscript
# Toggle auto-skip (e.g., from a button)
Dialogic.Inputs.auto_skip.enabled = !Dialogic.Inputs.auto_skip.enabled

# Debug mode: skip everything including unseen text
Dialogic.Inputs.auto_skip.disable_on_unread_text = false
Dialogic.Inputs.auto_skip.enabled = true

# Reduce time per event for faster skipping
Dialogic.Inputs.auto_skip.time_per_event = 0.05
```

### Auto-Skip Signal

```gdscript
Dialogic.Inputs.auto_skip.toggled.connect(func(is_enabled: bool):
    if is_enabled:
        print("Auto-Skip started")
    else:
        print("Auto-Skip stopped"))
```

### Implementing Auto-Skip in Custom Events

Auto-Skip behavior must be implemented per event. Two patterns:

**Capping time-based operations:**
```gdscript
var animation_length: float = 10.0

if Dialogic.Inputs.auto_skip.enabled:
    animation_length = min(Dialogic.Inputs.auto_skip.time_per_event, animation_length)
```

**Reacting to the toggle for signal-based events:**
```gdscript
func _execute() -> void:
    if Dialogic.Inputs.auto_skip.enabled:
        finish()  # skip instantly
        return
    # Normal execution path
    await some_signal
    finish()
```

### Summary: Three Ways to Advance

| Method | Trigger | Speed | Player Control |
|--------|---------|-------|----------------|
| **Manual-Advance** | Player input (`dialogic_default_action`) | Player-paced | Full |
| **Auto-Advance** | Timer after text reveal | Configurable delay (per-word/character) | Player toggles on/off |
| **Auto-Skip** | Timeline events auto-execute | Time-capped per event | Player toggles on/off; stops on unseen text |

## Styles & Layouts

Three systems work together to display timelines: **Dialogic Nodes**, **Layout Scenes**, and **Styles**.

### Concepts

- **Dialogic Nodes** (`DialogicNode_*`) — UI control nodes (DialogText, NameLabel, PortraitContainer, ChoiceButton, etc.) that are activated by Dialogic subsystems. They register themselves in groups (`dialogic_set_DialogText`, `dialogic_set_NameLabel`, etc.) so subsystems can find them.
- **Layout Scenes** — Reusable scenes containing Dialogic Nodes, other Godot Control nodes, and custom scripts. They provide self-contained UI parts (e.g. `VisualNovel Textbox Scene`, `Glossary Popup Scene`, `Centered Choices Scene`).
  - **Base layout** extends `DialogicLayoutBase` — the root scene that holds everything.
  - **Layer layouts** extend `DialogicLayoutLayer` — child scenes added as layers to the base.
- **Styles** (`.tres` resources of type `DialogicStyle`) — combine one base layout + list of layer layouts with overridable export settings. Styles can **inherit** from other styles (inherits scenes and default settings).

### Style Structure

A `DialogicStyle` resource contains:
- `name` — style identifier (used by `[style]` events, `load_style()`)
- `inherits` — optional parent style for inheritance
- `layer_list` — ordered array of layer IDs
- `layer_info` — Dictionary mapping layer ID (empty string `""` for the base) to `DialogicStyleLayer` resources, each holding:
  - `scene` — `PackedScene` reference
  - `overrides` — Dictionary of export variable overrides applied at runtime

### Style Inheritance

A style can inherit from another. The inheritance chain works as follows:
- `get_layer_inherited_list()` returns the **root ancestor's** layer list (layers are always defined by the root).
- `get_layer_inherited_info(id)` merges overrides walking **up** the chain — child overrides override ancestor overrides.
- `get_inheritance_root()` walks the chain to the topmost style.
- `realize_inheritance()` flattens inheritance into the local style, then detaches the parent.

### Style Editor (Dialogic UI)

In the Dialogic Style Editor tab you can:
- Add new styles (empty or from a premade template)
- Rename styles
- Add, replace, or remove layers (both premade and custom scenes)
- Override export settings on any scene in the style
- Make a premade layer or whole style **custom** (copies the scene into your project so you can edit it)
- Create inherited styles
- Change the default style

**Important:** When customizing a premade layout, make sub-resources (fonts, images, scripts) **unique** before modifying them. Resources still inside `addons/dialogic/` may be lost when updating Dialogic. Using "Make Custom" on the layer automatically handles the root script.

### Subsystem API (`Dialogic.Styles`)

```gdscript
# Load/switch styles
Dialogic.Styles.load_style("StyleName")       # load a fresh style (use before Dialogic.start() or select style before _ready)
Dialogic.Styles.change_style("StyleName")     # switch style mid-dialog, preserving current state (reloads dialog nodes)
Dialogic.Styles.preload_style("StyleName")    # preload scene resources in background

# Query current state
Dialogic.Styles.has_active_layout_node()       # bool: is a layout node present in the tree?
Dialogic.Styles.get_layout_node()              # returns the DialogicLayoutBase root node (null if none)
Dialogic.Styles.get_current_style()            # returns the current style name (empty string if none)

# Node lookup within the active layout
Dialogic.Styles.get_first_node_in_layout("group_name")  # like get_first_node_in_group() but scoped to the layout subtree

# Signals
Dialogic.Styles.style_changed.connect(_on_style_changed)  # emits info: {"style": name, "previous": prev_name}
```

`load_style()` vs `change_style()`:
- `load_style()` — use when no layout is active yet (e.g. before `Dialogic.start()`). Creates a fresh layout.
- `change_style()` — use mid-dialog. It calls `load_style()` with `state_reload=true`, which reloads the current dialog state into the new layout's nodes after the new scene is ready. This preserves text, portraits, choices, etc. across the style switch.

When `load_style()` detects the same scene setup (same inheritance root), it only applies new export overrides without recreating nodes — this is fast and non-disruptive.

### Changing Styles at Runtime

**Via timeline event:**
```gdscript
[style name="MyStyle"]
```
This calls `Dialogic.Styles.change_style()` and waits one frame for the layout to be ready before continuing.

**Via code (pre-start):**
```gdscript
Dialogic.Styles.load_style("MyStyle")
Dialogic.start("my_timeline")
```

**Per-character style:**
Assign a style to a `DialogicCharacter` resource (in the Character editor). When that character speaks, Dialogic temporarily switches to their style (non-base style), then reverts when another character speaks or the base style is restored.

### Creating Custom Layout Scenes

To create a custom layout scene from scratch:

1. Create a new scene with a root node extending `DialogicLayoutBase` (for a base) or `DialogicLayoutLayer` (for a layer).
2. Export variables on the root script — they automatically appear as settings in the Style Editor. Use `@export_group` and `@export_subgroup` for organization. Not all variable types are supported.
3. Override `_apply_export_overrides()` to apply exported settings to your nodes. This method is called:
   - When the style is first loaded
   - When switching to a different style that uses the same scene (only overrides are re-applied)

**Base layout** (`DialogicLayoutBase`) additionally provides:
- `add_layer(layer)` — add a `DialogicLayoutLayer` as a child
- `get_layers()` — get all layer children
- `get_global_setting(setting, default)` — retrieve a setting that layers can share (e.g. color themes)
- `_get_persistent_info()` / `_load_persistent_info(info)` — persist and restore data across style changes via `Engine` metadata

**Layer layout** (`DialogicLayoutLayer`) additionally provides:
- `disabled` export — if `true`, the layer is hidden and processing disabled
- `apply_overrides_on_ready` export — if `true`, `_apply_export_overrides()` runs on `_ready()` (automatically set when making a layer custom)
- `get_global_setting(setting, default)` — delegates to the parent base

**Adding custom scenes to a style:**
Use the Style Editor's **Add Layer** or **Replace Layer** buttons above the layer list. Your custom scene appears as an option.

### Creating Custom Dialogic Nodes

Each Dialogic Node is a normal Control node with a script that registers itself in a group. Subsystems find their nodes via groups. Customizing a Dialogic node means:
1. Duplicate the existing node scene and modify it.
2. Ensure it still registers itself in the expected group(s).
3. In most cases, reacting to Dialogic signals (or signals of existing nodes) is easier than creating a custom node from scratch.

### Preloading for Performance

To avoid lag when a style is first loaded, preload it during a loading screen:
```gdscript
# Request threaded preload
Dialogic.Styles.preload_style("MyStyle")

# Or call on the style resource directly
style_resource.prepare()
```

### Project Settings

Key settings under `dialogic/layout/`:
- `default_style` — path to the default style resource
- `end_behaviour` — 0=free (keep layout), 1=hide (hide on end), 2=keep layout visible
- `style_list` — array of all style resource paths
- `style_directory` — dictionary mapping style names → paths (built automatically)

### StyleEvent Timeline Shortcode

```gdscript
[style name="StyleName"]
```

### Key Troubleshooting

- **Style not found at runtime:** Ensure the style `.tres` file is listed in `dialogic/layout/style_list` in ProjectSettings. The `style_directory` is rebuilt by `DialogicStylesUtil.update_style_directory()`.
- **Changes lost on update:** After using "Make Custom", ensure sub-resources (fonts, images, shaders) are saved outside `addons/dialogic/`. Click "Make Unique" on any shared sub-resources.
- **Layout not appearing:** `Dialogic.start()` calls `load_style()` automatically if no layout is active. `Dialogic.start_timeline()` does NOT — you must call `Dialogic.Styles.load_style()` first.
- **Double layout nodes:** Guard with `if not Dialogic.Styles.has_active_layout_node():` before calling `load_style()`.

## Signals & Signal Events

### Signal Event

Emits `Dialogic.signal_event` with an argument:

```gdscript
Dialogic.signal_event.connect(_on_dialogic_signal)

func _on_dialogic_signal(argument: String):
    if argument == "activate_something":
        print("Activated!")
```

### Text Signal (via `[signal=arg]` text effect)

Emits `Dialogic.text_signal`:

```gdscript
Dialogic.text_signal.connect(_on_dialogic_text_signal)
```

### Timeline Start/End

```gdscript
Dialogic.timeline_started.connect(_on_timeline_started)
Dialogic.timeline_ended.connect(_on_timeline_ended)
```

### Key Subsystem Signals

```gdscript
Dialogic.Text.about_to_show_text(info: Dictionary)
Dialogic.Text.text_finished(info: Dictionary)
Dialogic.Text.speaker_updated(character: DialogicCharacter)
Dialogic.Text.textbox_visibility_changed(visible: bool)
Dialogic.Text.animation_textbox_new_text       # emitted when new text starts animating in
Dialogic.Text.animation_textbox_show           # emitted when textbox show animation starts
Dialogic.Text.animation_textbox_hide           # emitted when textbox hide animation starts
Dialogic.Portraits.character_joined(info: Dictionary)
Dialogic.Portraits.character_left(info: Dictionary)
Dialogic.Portraits.character_portrait_changed(info: Dictionary)
Dialogic.VAR.variable_changed(info: Dictionary)
Dialogic.VAR.variable_was_set(info: Dictionary)  # only from set variable events
```

## Saving & Loading

```gdscript
# Simple save/load (takes screenshots too)
Dialogic.Save.save("slot_name")
Dialogic.Save.load("slot_name")

# Save without screenshot
Dialogic.Save.save("slot_name", false, Dialogic.Save.ThumbnailMode.NONE)

# Save with extra info (date, custom data)
var extra = {"text": Dialogic.current_state_info["text"], "date": Time.get_datetime_string_from_system(false, true)}
Dialogic.Save.save("slot_name", false, Dialogic.Save.ThumbnailMode.STORE_ONLY, extra)

# Check if slot exists
if Dialogic.Save.has_slot("slot_name"):
    var info = Dialogic.Save.get_slot_info("slot_name")
```

Savegames store Dialogic's timeline state and variables. Extra info is stored per-slot but not loaded into Dialogic state.

### Global Data (Slot-Independent)

For data that should persist across all save slots (e.g., settings, preferences), use `Dialogic.Settings` or `Dialogic.Save` global info:

```gdscript
# Simple: store directly on Settings (auto-saved)
Dialogic.Settings.text_speed = 0.5

# Explicit: store arbitrary global key-value pairs
Dialogic.Save.set_global_info("player_name", "Miko")
var name = Dialogic.Save.get_global_info("player_name", "Unknown")
```

### Saving Visited Events History

Dialogic's History subsystem can persist which text events the player has already seen:

```gdscript
# Enable auto-saving visited history on every save
Dialogic.History.save_already_visited_history_on_save = true
Dialogic.History.save_already_visited_history_on_autosave = true

# Manual control
Dialogic.History.save_visited_history()
Dialogic.History.load_visited_history()
Dialogic.History.reset_already_visited_history()
```

### Slot Management

```gdscript
# Check if a slot exists
if Dialogic.Save.has_slot("slot_name"):
    Dialogic.Save.load("slot_name")

# Delete a slot
Dialogic.Save.delete_slot("slot_name")

# Create an empty slot
Dialogic.Save.add_empty_slot("slot_name")
```

### Manual Save/Load (Full State)

For custom save pipelines, capture and restore Dialogic's entire state:

```gdscript
var state: Dictionary = Dialogic.get_full_state()
# ... store/retrieve state however you want ...
Dialogic.load_full_state(state)
```

## Reference Manager

Dialogic's **Reference Manager** (toolbar Link button) handles unique identifiers for timelines and characters, and fixes broken references after renames.

### Unique Identifiers

Each `.dtl` timeline and `.dch` character gets a **unique identifier** string (initially derived from the filename, but editable). No two resources of the same type can share an identifier. These identifiers are what you use in timeline text (`CharacterName:`, `jump TimelineName/`).

In the Reference Manager's second tab, you can double-click any identifier to rename it. Renaming automatically adds an entry to the "Broken References" tab.

### Broken References

When you rename a resource, timelines referencing the old identifier break. The Reference Manager's first tab helps fix this:

1. Dialogic may auto-add renames. Review them.
2. Click **Check Selected** to scan all timelines for the references.
3. Review the results, uncheck any false positives.
4. Click **Replace** to apply.

> **Warning:** This is a destructive bulk operation on all affected timelines. Commit to version control first.

### Custom Replacements (Advanced)

Click the **Plus button** for manual replacements:
- **Pure Text** — custom string or regex. Use `(?<replace>something)` group to replace only a portion.
- **Variable / Portrait / Character / Timeline** — specialized regex for each type.
- Optionally **limit to a specific character** (useful for portrait renames).

## Glossary

Dialogic's built-in glossary auto-highlights defined terms in dialog text and shows a tooltip with the definition on hover.

### How It Works

A glossary is a `.tres` resource with an `entries` array of Dictionaries. Each entry has:
- `name` — the primary term
- `alternatives` — aliases that also trigger highlighting
- `text` — definition shown in the tooltip
- `extra` — additional data

When a glossary is loaded, Dialogic scans text for matching names/alternatives and applies highlighting automatically. Variables can be used in glossary titles, texts, and extras via `{curly braces}`.

### Accessing Glossaries from Code

```gdscript
# Get all glossary file paths
var paths: Array = ProjectSettings.get_setting('dialogic/glossary/glossary_files', [])

# Load and inspect a glossary
var glossary: DialogicGlossary = load(paths[0])
for entry in glossary.entries:
    print(entry.name, ": ", entry.text)
```

**Note:** Properties prefixed with `_` (like `_translation_id`, `_translation_keys`) are private — use the helper methods on `DialogicGlossary` instead.

### Translation

Glossary entries are translatable. Enable translation in Dialogic Settings, then use "Update CSV files". Entry names and alternatives must remain unique across translations, and may not start with `Glossary/`.

## Translation

Dialogic supports translating timelines, character names, and glossary entries via CSV files. It uses Godot's built-in `TranslationServer`.

### Setup

1. In Dialogic **Settings → Translation**, enable translation.
2. Choose a **default locale** (the language you write in — used as fallback).
3. Set **translation file mode**: "Per Project" (one CSV) or "Per Timeline" (one CSV per `.dtl`).
4. Set a **translation folder** to keep CSV files organized.

### Workflow

```
1. Write/Edit timeline  →  2. "Update CSV files"  →  3. Edit CSV translations
       ↑                                                           ↓
       └────────────────── 4. "Collect translation"  ←──────────────┘
```

**CSV format:**
```csv
keys,en,ja
Text/1/text,Hello World!,こんにちは世界！
```
- Column headers are locale codes (`en`, `ja`, `fr`, etc.).
- Each row's key identifies the translatable unit: `Text/<event_id>/text`, `Character/<id>/name`, `Glossary/<hash>/name`, etc.
- Commas in text must be escaped by wrapping in quotes.

**Important:** After editing a translated text's original, you MUST regenerate by clicking "Update CSV files" again, or translations won't apply to the changed text.

### Translation IDs in Timelines

After enabling translation, Dialogic inserts `#id:<number>` markers at the end of text events:
```
Character: Hello world! #id:14
- Yes, I do! #id:16
```
These IDs link the text to its CSV row. They are not visible during gameplay.

### Changing Language

```gdscript
# Switch to Japanese at runtime
TranslationServer.set_locale("ja")
```

### Testing in Editor

Use the "Testing locale" dropdown in Settings → Translation. This is editor-only and may not work in exported builds.

## Audio Channels

Audio plays on named channels. Default channels defined in project settings:

```gdscript
DialogicUtil.get_audio_channel_defaults()  # returns Dictionary
DialogicUtil.get_audio_channel_suggestions("search")
DialogicUtil.validate_audio_channel_name("name")
```

Channel names: `""` (default), `"music"` (looping by default), plus custom.

## Resource Management (DialogicResourceUtil)

```gdscript
# Directories (map identifier -> path)
DialogicResourceUtil.get_directory('dtl')         # timelines
DialogicResourceUtil.get_directory('dch')         # characters
DialogicResourceUtil.update_directory(extension)  # rescan

# Lookups
DialogicResourceUtil.get_timeline_resource("name")
DialogicResourceUtil.get_character_resource("name")
DialogicResourceUtil.get_unique_identifier_by_path("res://...")
DialogicResourceUtil.get_resource_path_from_identifier("name", "dtl")

# Label cache (editor only)
DialogicResourceUtil.get_label_cache()
DialogicResourceUtil.update_label_cache()

# Event cache
DialogicResourceUtil.get_event_cache()            # all event types
DialogicResourceUtil.update_event_cache()
```

## Utility Helpers (DialogicUtil)

```gdscript
# Variables
DialogicUtil.VarTypes          # ANY, STRING, FLOAT, INT, BOOL
DialogicUtil.get_default_variables()
DialogicUtil.list_variables(dict, path, type)
DialogicUtil.get_variable_value_type(value)
DialogicUtil.get_variable_type(path, dict)
DialogicUtil.logical_convert(value)  # auto-convert string to int/float/bool

# Suggestions (for editor fields)
DialogicUtil.get_character_suggestions(search, current, allow_none, allow_all)
DialogicUtil.get_portrait_suggestions(search, character, allow_empty)
DialogicUtil.get_autoload_suggestions(filter)
DialogicUtil.get_autoload_method_suggestions(filter, autoload_name)
DialogicUtil.get_autoload_property_suggestions(filter, autoload_name)
DialogicUtil.get_audio_bus_suggestions(filter)
DialogicUtil.get_audio_channel_suggestions(search)

# Timer
DialogicUtil.is_physics_timer()
DialogicUtil.update_timer_process_callback(timer)
```

## Project Settings

Key settings (under `dialogic/`):
- `dialogic/variables` — default variable dictionary
- `dialogic/layout/default_style` — default style name
- `dialogic/layout/end_behaviour` — 0=free, 1=hide, 2=keep layout on end
- `dialogic/text/letter_speed` — default letter reveal time
- `dialogic/text/autocolor_names` — auto-color character names in text
- `dialogic/text/split_at_new_lines` — treat newlines as `[n]`
- `dialogic/text/autopauses` — auto-insert pauses after punctuation
- `dialogic/extensions_folder` — custom modules path (default: `res://addons/dialogic_additions/`)
- `dialogic/directories/*_directory` — resource directories (dch, dtl, style)
- `dialogic/audio/channel_defaults` — default audio channels

## Working with Dialogic in This Project

### Common Patterns

**Starting dialog (guard against double-start):**
```gdscript
func _input(event):
    if player_is_in_area and Input.is_action_pressed("start_interaction"):
        if Dialogic.current_timeline == null:
            Dialogic.start("my_timeline")
```

**Reacting to dialog signals:**
```gdscript
Dialogic.signal_event.connect(_on_dialogic_signal)
Dialogic.timeline_ended.connect(_on_dialog_finished)
func _on_dialog_finished():
    Dialogic.timeline_ended.disconnect(_on_dialog_finished)
    # game logic here
```

**Setting variables from code:**
```gdscript
# Direct property access (preferred)
Dialogic.VAR.player_name = "Miko"
Dialogic.VAR.coins = 42

# String-based access for dynamic names
Dialogic.VAR.set_variable("player_name", "Miko")
Dialogic.VAR.set_variable("coins", 42)

# Reset all variables to defaults
Dialogic.VAR.reset()
```

**Creating timelines in code:**
```gdscript
# From strings (follow text syntax)
var events: Array = """
Jowan (Surprised): Wow this is interesting!
- Yes
    set {excitement} += 20
- No
    set {excitement} -= 10
""".split('\n')
var timeline = DialogicTimeline.new()
timeline.events = events
Dialogic.start(timeline)
```

**Hiding/showing textbox:**
```gdscript
if Dialogic.Text.is_textbox_visible():
    Dialogic.Text.hide_textbox()
else:
    Dialogic.Text.show_textbox()
```

**Getting current speaker:**
```gdscript
var speaker: DialogicCharacter = Dialogic.Text.get_current_speaker()
var portrait_info := Dialogic.Portraits.get_character_info(speaker)
```

### Troubleshooting

- **Portraits not showing**: Characters must join the scene with a Character Event (Join mode) before their portraits appear. Ensure `.dch` filename case matches timeline text exactly.
- **Wrong text displayed**: If translation is enabled, CSV rows take priority. Disable translation during development or update CSVs.
- **Lag on dialog start**: Preload styles with `style.prepare()` or preload an empty timeline during your loading screen.
- **Input conflicts**: If your interaction key matches the dialogic input action, guard with `if Dialogic.current_timeline == null:` before starting new dialog.