Dialogue System Setup

1 - Step 1: Create the Database

Step 1 — Create the Database

Open the Dialogue Editor

From the O3DE Editor menu bar, go to GS Tools > Dialogue Editor. The editor opens with three page tabs at the top: Sequences, Performers, and System.

Create a New Database

1. Go to File > New
2. Choose a save location in your project’s assets folder (e.g., Assets/Dialogue/)
3. Name the file (e.g., town_npcs.dialoguedatabase)
4. The editor opens with an empty database

Define Performers

Switch to the Performers page by clicking the tab at the top.

Performers represent the characters who speak in your dialogues. Add one performer for each character:

1. Click Add Performer
2. Set the Name — this is the identifier you will reference in Text nodes (e.g., "Merchant", "Guard")
3. Optionally configure:
   • Portrait — Reference to a UI image asset shown during dialogue
   • Voice — Audio configuration for this character’s voice

Add at least two performers for this tutorial (e.g., "Player" and "Merchant").

Create Your First Sequence

Switch back to the Sequences page.

1. In the Sequence Sidebar (left dock), click Add
2. Name the sequence (e.g., "MerchantGreeting")
3. The sequence opens as a graph tab with a single Start node

Your database now has one empty sequence ready for authoring. Save the database with File > Save (Ctrl+S).

What You Have So Far

town_npcs.dialoguedatabase
├── Performers: Player, Merchant
└── Sequences: MerchantGreeting (empty)

Next: Author a Conversation

2 - Step 2: Author a Conversation

Step 2 — Author a Conversation

Build a Linear Sequence

With the MerchantGreeting sequence open, you have a Start node on the canvas. Now add dialogue nodes:

1. From the Node Palette (right dock), drag a Text node onto the canvas
2. Connect the Start node’s FlowOut slot to the Text node’s FlowIn slot by clicking and dragging between the slots
3. Select the Text node and set its properties in the Inspector:
   • Speaker: "Merchant" (matches your performer name)
   • Text: "Welcome to my shop! Looking for something special?"

Add More Lines

Repeat the process to add a second Text node for the player’s response:

1. Drag another Text node onto the canvas
2. Connect the first Text node’s FlowOut to this new node’s FlowIn
3. Set properties:
   • Speaker: "Player"
   • Text: "Just browsing, thanks."

End the Sequence

1. Drag an End node from the palette
2. Connect the last Text node’s FlowOut to the End node’s FlowIn

Your sequence now reads:

Start → [Merchant: "Welcome to my shop!"] → [Player: "Just browsing."] → End

Test the Flow

The node footers preview each line of dialogue, making it easy to read through the conversation visually on the canvas. Verify the flow makes sense by following the connections from Start to End.

Save the database (Ctrl+S).

Tips

• Undo/Redo: Ctrl+Z / Ctrl+Y work on all graph operations
• Node selection: Click a node to see its full properties in the Inspector
• Moving nodes: Drag nodes to rearrange the layout for readability
• Copy/Paste: Select nodes and use Ctrl+C / Ctrl+V to duplicate sections

Next: Wire Up the Runtime

3 - Step 3: Wire Up the Runtime

Step 3 — Wire Up the Runtime

The Dialogue Editor is for authoring. To play dialogue at runtime, you need three components on entities in your level.

The Dialogue Manager

The Dialogue Manager is a GS_Play manager that owns the active dialogue database and provides the top-level API.

1. Your Game Manager prefab should already spawn a GS_DialogueManager (it is part of the GS_Cinematics manager set)
2. If not, create a manager entity and add the GS_DialogueManagerComponent
3. In the component properties, set the Dialogue Database field to your .dialoguedatabase asset

The manager provides the entry point API: StartDialogueSequenceByName("MerchantGreeting").

The Dialogue Sequencer

The sequencer is the component that actually executes the graph — stepping through nodes, waiting for text display, and handling player choices.

1. On your NPC entity (or a dedicated dialogue entity), add a DialogueSequencerComponent
2. No configuration needed — the sequencer receives commands from the manager

The Dialogue UI Bridge

The UI Bridge connects the sequencer to your UI display components. It routes dialogue text to the correct UI panel and relays player choices back.

1. On the same entity as the sequencer (or a shared UI entity), add a DialogueUIBridgeComponent
2. It will automatically discover registered UI components in the scene

Triggering Dialogue

To start dialogue from gameplay code or ScriptCanvas:

// C++ via EBus
DialogueManagerRequestBus::Broadcast(
    &DialogueManagerRequests::StartDialogueSequenceByName,
    "MerchantGreeting"
);

Or connect it to an interaction trigger — when the player interacts with the merchant entity, fire StartDialogueSequenceByName.

Component Summary

Next: Display Dialogue In-Game

4 - Step 4: Display Dialogue In-Game

Step 4 — Display Dialogue In-Game

Dialogue UI Component

The DialogueUIComponent handles displaying dialogue text on screen. It receives text from the UI Bridge and shows it in a UI element.

1. Create a UI canvas with a text panel for dialogue display (speaker name label + dialogue text area)
2. On the UI entity, add a DialogueUIComponent
3. Register the UI entity with the bridge by calling RegisterDialogueUI(panelType, entityId) or by placing it where the bridge can discover it

When a Text node executes, the sequencer sends the speaker name and dialogue text through the bridge to the UI component, which updates the display.

Typewriter Effect

The TypewriterComponent reveals text character by character for a classic RPG dialogue feel:

1. On the same entity as the DialogueUIComponent, add a TypewriterComponent
2. Set the Default Speed — letters per second (e.g., 30 for moderate speed)
3. The typewriter automatically hooks into the dialogue display

When text arrives, the typewriter reveals it gradually. The player can press a button to call ForceComplete() for instant reveal.

World-Space Dialogue (Speech Bubbles)

For dialogue that appears above characters in the 3D world:

1. Use WorldDialogueUIComponent instead of DialogueUIComponent
2. Configure a spawnable prefab for the speech bubble UI
3. The component tracks the speaking entity’s position and places the UI above them

Flow

Sequencer executes Text node
    → UIBridge.RunDialogue(text, speakerName)
        → DialogueUIComponent.DoDialogue(text, performerData)
            → TypewriterComponent.StartTypewriter(text)
                → Text reveals character by character
                    → Player presses button → ForceComplete()
                        → Sequencer advances to next node

Next: Add Player Choices

5 - Step 5: Add Player Choices

Step 5 — Add Player Choices

Add a Selection Node

Go back to the Dialogue Editor and open your MerchantGreeting sequence.

1. Delete the connection between the merchant’s greeting and the player’s response
2. Drag a Selection node from the palette and place it between them
3. Connect the merchant’s Text node FlowOut to the Selection node’s FlowIn

Configure Choices

Select the Selection node. In the Inspector:

1. Set Question Text to "What would you like to do?" (optional — displayed above the choices)
2. Add options in the Selection Options list:
   • Option 1: "Browse your wares"
   • Option 2: "Tell me about the town"
   • Option 3: "Goodbye"

Each option creates a dynamic FlowOut slot on the node.

Branch the Conversation

Now connect each output to different dialogue paths:

1. “Browse your wares” FlowOut → New Text node (Merchant: "Take a look around!") → End
2. “Tell me about the town” FlowOut → New Text node (Merchant: "This town was founded...") → End
3. “Goodbye” FlowOut → New Text node (Merchant: "Safe travels!") → End

Your graph now branches based on the player’s choice and each branch leads to a different response.

Selection UI Component

On the UI side, the DialogueUISelectionComponent displays the choices to the player:

1. On a UI entity, add a DialogueUISelectionComponent
2. Configure it with a button prefab for spawning choice options
3. Register it with the UI Bridge

When the sequencer hits a Selection node:

Sequencer reaches Selection node
    → UIBridge.RunSelection(options)
        → DialogueUISelectionComponent.DoSelection(options, performerData)
            → Spawns choice buttons
                → Player clicks a choice
                    → OnSelection(index) fires
                        → Sequencer follows the chosen FlowOut

Random Branching

For variety without player choice, use a Random node instead. It picks a random output each time the sequence reaches it. Optionally configure weights to make some branches more likely.

Next: Conditions and Effects

6 - Step 6: Conditions and Effects

Step 6 — Conditions and Effects

Using Variables

Declare variables in the Variable Panel to track dialogue state:

1. Open the Variable Panel dock
2. Click Add and create a boolean variable: "hasVisitedMerchant" (default: false)

Conditions on Nodes

Any dialogue node can have conditions that gate whether it executes. If conditions fail, the evaluator skips that node and tries the next connection.

1. Select a Text node in the inspector
2. In the Conditions section, click the type picker dropdown
3. Add a Boolean_DialogueCondition
4. Set:
   • Variable Name: "hasVisitedMerchant"
   • Expected Value: true

Now that Text node only executes if the player has visited before. You can create two branches from a single output — one with hasVisitedMerchant = true and one without conditions as a fallback.

Effects Nodes

Effects nodes trigger game actions during dialogue. They are the bridge between conversation and gameplay.

1. Drag an Effects node from the palette
2. Place it in the flow where you want the effect to happen
3. Select it and use the type picker in the Inspector to add effect types

For example, after the merchant’s greeting, add an Effects node that sets hasVisitedMerchant = true so subsequent visits show different dialogue.

Performance Nodes

Performance nodes trigger character actions — animations, movement, posing:

1. Drag a Performance node into the flow
2. Add performance types via the Inspector type picker:
   • MoveTo_DialoguePerformance — Move a character to a position
   • PathTo_DialoguePerformance — Move along a path
3. Enable Wait to Continue if the dialogue should pause until the performance finishes

Creating Custom Types

The polymorphic extension system makes it simple to add project-specific conditions, effects, and performances:

1. Create a subclass of DialogueCondition, DialogueEffect, or DialoguePerformance
2. Add AZ_RTTI and implement Reflect() with SerializeContext and EditContext
3. Include and reflect it in DialogueSequencerComponent::Reflect()

The inspector automatically discovers your new type — no registry code needed.

Complete Example

Here is a complete branching dialogue with conditions and effects:

Start
  → [Merchant greeting (no condition): "Welcome, stranger!"]
  → [Merchant greeting (hasVisitedMerchant=true): "Welcome back, friend!"]
      → Selection: "Buy" / "Sell" / "Leave"
          → "Buy" → Effects(OpenShopUI) → End
          → "Sell" → Effects(OpenSellUI) → End
          → "Leave" → [Merchant: "Come again!"] → Effects(Set hasVisitedMerchant=true) → End

Summary

You now have a complete dialogue pipeline:

• Database with performers and multiple sequences
• Visual authoring with Text, Selection, Random, Effects, and Performance nodes
• Runtime components (Manager, Sequencer, UI Bridge) executing the graphs
• UI display with typewriter text reveal and player choice buttons
• Conditions for dynamic branching based on game state
• Effects for triggering gameplay from within dialogue

For the full API reference, see the Dialogue Editor documentation.