Dialogue System

The Dialogue System is the authoring and runtime core of GS_Cinematics. Dialogue content is stored in .dialoguedb assets (DialogueDatabase), which contain named actors and a collection of DialogueSequence records. Each sequence is a graph of polymorphic nodes. At runtime, GS_DialogueManagerComponent manages the database and maps performer names to entities in the level, while DialogueSequencerComponent drives playback — walking the graph, evaluating conditions on branches, executing effects, and emitting events that UI and other systems consume.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

 

Contents

• Dialogue Database
• DialogueDatabase Asset
• Node Types
• Conditions
• Effects
• Performances
• Runtime Playback
• Localization
• ScriptCanvas Usage
• Quick Reference
• Glossary
• See Also

---

Dialogue Database

Breakdown

A dialogue sequence is authored in the node editor, stored in a .dialoguedb asset, and driven at runtime by the Dialogue Manager and Sequencer:

Layer	What It Means
DialogueDatabase	Stores named actors and sequences. Loaded at runtime by the Dialogue Manager.
DialogueSequence	A directed node graph. The Sequencer walks from startNodeId through Text, Selection, Effects, and Performance nodes.
Conditions	Polymorphic evaluators on branches. Failed conditions skip that branch automatically.
Effects	Polymorphic actions at EffectsNodeData nodes — set records, toggle entities.
Performers	Named actor anchors in the level. Resolved from database actor names via DialoguePerformerMarkerComponent.

Conditions, effects, and performances are discovered automatically at startup — custom types from any gem appear in the editor without modifying GS_Cinematics.

E Indicates extensible classes and methods.

Patterns - Complete list of system patterns used in GS_Play.

DialogueDatabase Asset

The DialogueDatabase is a .dialoguedb asset authored in the O3DE node editor. It is the single source of truth for all dialogue content in a project section.

Asset Contents	Purpose
Actors	Named character definitions with portrait and metadata.
Sequences	Named DialogueSequence records, each a graph of nodes.

Load a database at runtime by calling ChangeDialogueDatabase on DialogueManagerRequestBus. The manager resolves performer names from the database against DialoguePerformerMarkerComponent entities placed in the current level.

---

Node Types

Each sequence is a directed graph of DialogueNodeData nodes. The sequencer walks the graph starting from startNodeId and advances through the nodes in order.

Node Type	What It Does
TextNodeData	Displays a speaker line. Supports LocalizedStringId for localization.
SelectionNodeData	Presents the player with a list of choices. Branches based on selection.
RandomNodeData	Selects a random outgoing branch.
EffectsNodeData	Executes one or more DialogueEffect objects without advancing to a text node.
PerformanceNodeData	Triggers a DialoguePerformance action and waits for OnPerformanceComplete before continuing.

---

Conditions

Conditions are polymorphic objects attached to sequence branches. The sequencer evaluates all conditions on a branch before following it. Branches whose conditions fail are skipped.

Condition Type	What It Evaluates
Boolean_DialogueCondition	A base boolean comparison.
Record_DialogueCondition	Checks a game record via the RecordKeeper system. Extends Boolean_DialogueCondition.

---

Effects

Effects are polymorphic objects executed when the sequencer reaches an EffectsNodeData node. Effects can also be reversed.

Effect Type	What It Does
SetRecords_DialogueEffect	Sets one or more game records via the RecordKeeper system.
ToggleEntitiesActive_DialogueEffect	Toggles one or more entities active or inactive.

---

Performances

Performances are polymorphic objects executed when the sequencer reaches a PerformanceNodeData node. A performance can be blocking — the sequencer pauses and waits for OnPerformanceComplete before advancing — or non-blocking, where dialogue continues immediately after the performance fires.

Like conditions and effects, performance types are discovered automatically at startup via the type registry. Custom performance types from any gem appear in the editor without modifying GS_Cinematics.

Performance Type	What It Does
MoveTo_DialoguePerformance	Smoothly moves a named performer to a CinematicStageMarkerComponent position. Fires MoveTo_PerformanceNotificationBus — a companion component on the performer entity responds and moves it, then signals completion.
PathTo_DialoguePerformance	Navigates a named performer to a marker using the scene navmesh. Uses RecastNavigation pathfinding through the world geometry rather than a direct interpolation.
RepositionPerformer_DialoguePerformance	Instantly teleports a performer to a marker. Non-blocking — dialogue advances without waiting.

---

Runtime Playback

GS_DialogueManagerComponent

The Dialogue Manager is the top-level manager for all dialogue. It holds the active DialogueDatabase, maps performer names to level entities via DialoguePerformerMarkerComponent, and is the entry point for starting sequences by name.

Bus	Method	What It Does
DialogueManagerRequestBus	StartDialogueSequenceByName	Starts a named sequence from the active database.
DialogueManagerRequestBus	ChangeDialogueDatabase	Loads a different DialogueDatabase asset.
DialogueManagerRequestBus	RegisterPerformerMarker	Registers a performer entity by name for the current level.
DialogueManagerRequestBus	GetPerformer	Returns the entity for a named performer.

DialogueSequencerComponent

The Dialogue Sequencer drives sequence playback. It walks the node graph, evaluates conditions, executes effects, triggers performances, and emits notifications when text lines begin and when the sequence completes. It is typically placed on a dedicated sequencer entity in the level alongside DialogueUIBridgeComponent.

Bus	Method / Event	Purpose
DialogueSequencerRequestBus	StartDialogueBySequence	Begins playback of a given sequence object.
DialogueSequencerNotificationBus	OnDialogueTextBegin	Fires when a TextNodeData begins — carries speaker and text data.
DialogueSequencerNotificationBus	OnDialogueSequenceComplete	Fires when the sequence reaches its end node.

---

Localization

Text nodes store speaker lines as LocalizedStringId references rather than raw strings. A LocalizedStringId holds a key and a default fallback text. At runtime, the sequencer calls Resolve() on each LocalizedStringId, which looks up the key in the active LocalizedStringTable and returns the localized string for the current locale. If no table is loaded or the key is not found, the default text is returned.

To use localization, load a LocalizedStringTable asset through your project’s initialization flow before any dialogue plays.

---

ScriptCanvas Usage

Starting a Dialogue Sequence

Reacting to Sequence States

Listen on DialogueSequencerNotificationBus to receive speaker and text data as each line begins:

---

Quick Reference

Need	Bus	Method / Event
Start a sequence by name	DialogueManagerRequestBus	StartDialogueSequenceByName
Load a different database	DialogueManagerRequestBus	ChangeDialogueDatabase
Register a performer in the level	DialogueManagerRequestBus	RegisterPerformerMarker
Get a performer entity	DialogueManagerRequestBus	GetPerformer
Start a sequence object directly	DialogueSequencerRequestBus	StartDialogueBySequence
React to a text line starting	DialogueSequencerNotificationBus	OnDialogueTextBegin
React to sequence completion	DialogueSequencerNotificationBus	OnDialogueSequenceComplete

---

Glossary

Term	Meaning
DialogueDatabase	A .dialoguedb asset containing actors and dialogue sequences
DialogueSequence	A graph of nodes that defines a single dialogue conversation
DialogueNodeData	A polymorphic node in the sequence graph (Text, Selection, Random, Effects, Performance)
DialogueCondition	A polymorphic evaluator attached to branches that gates progression
DialogueEffect	A polymorphic action executed at EffectsNodeData nodes (e.g., setting records)
DialoguePerformance	A polymorphic action executed at PerformanceNodeData nodes — moves, paths, or repositions performers. Can be blocking or non-blocking
Performer	A named actor entity in the level mapped from the database via DialoguePerformerMarkerComponent

For full definitions, see the Glossary.

---

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Dialogue System

For related systems:

• The Basics: Cinematics Manager
• The Basics: Dialogue UI

---

Get GS_Cinematics

GS_Cinematics — Explore this gem on the product page and add it to your project.

1 - Dialogue UI

The Dialogue UI layer is the display side of the GS_Cinematics system. It receives events from DialogueSequencerComponent through DialogueUIBridgeComponent and routes them to the correct UI implementation — screen-space for HUD-style dialogue or world-space for speech bubbles above actors. Player choices are handled by selection components, and the TypewriterComponent reveals text character-by-character. BabbleComponent optionally plays per-character audio babble to give speakers a voice.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• Component Overview
• DialogueUIBridgeComponent
• Dialogue Display Components
• Selection Components
• TypewriterComponent
• BabbleComponent
• ScriptCanvas Usage
• Quick Reference
• Glossary
• See Also

Component Overview

DialogueUIBridgeComponent

The Bridge component is the central connector between the sequencer and the UI. Place it on the same entity as DialogueSequencerComponent. It listens for OnDialogueTextBegin and OnDialogueSequenceComplete from the sequencer and forwards those events to whatever UI components are registered with it. It also receives player selection events from the selection UI and forwards them back to the sequencer.

This design keeps the sequencer and the display fully decoupled — swapping in a new UI implementation only requires registering it with the Bridge.

Dialogue Display Components

Screen-Space Text

DialogueUIComponent handles HUD-style dialogue display. Add it to a UI canvas entity. It exposes the active TypewriterComponent so other systems can check typewriter state or force completion.

World-Space Speech Bubbles

WorldDialogueUIComponent extends DialogueUIComponent for world-space placement. It positions the dialogue panel above the speaking actor’s entity in 3D space. Use this for over-the-shoulder dialogue or conversations where the camera stays in the world rather than cutting to a UI overlay.

Selection Components

Screen-Space Choices

DialogueUISelectionComponent renders the player’s available choices as a list on the HUD. Each choice is backed by a DialogueSelectButtonComponent entity that is configured with option text and a selection index. When the player activates a button, it fires back through the Bridge to the sequencer.

World-Space Choices

WorldDialogueUISelectionComponent extends DialogueUISelectionComponent for world-space display. Choices appear positioned in 3D space rather than as a HUD overlay, useful for games with diegetic UI.

TypewriterComponent

The TypewriterComponent reveals a string one character at a time. It fires OnTypeFired for each character revealed and OnTypewriterComplete when the full string is displayed. Use ForceComplete to instantly reveal the remaining text — typically wired to a player skip input — and ClearTypewriter to reset the display to empty.

BabbleComponent

BabbleComponent pairs with TypewriterComponent to play short audio sounds for each character revealed, giving the impression of a speaker’s voice. Each actor has a SpeakerBabbleEvents record that maps them to a specific babble sound profile. The component returns the correct BabbleToneEvent for the current speaker via GetBabbleEvent, which is called by the typewriter on each OnTypeFired.

ScriptCanvas Usage

Forcing Typewriter Completion on Skip Input

Wire a player input action to ForceComplete so pressing a button instantly reveals the current line:

Reacting to Typewriter Events

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Dialogue UI

For related systems:

• The Basics: Dialogue
• The Basics: Cinematics Manager

Get GS_Cinematics

GS_Cinematics — Explore this gem on the product page and add it to your project.

2 - Performances

Performances are polymorphic actions that move or reposition actors during dialogue sequences. The sequencer triggers a performance when it reaches a PerformanceNodeData node and waits for OnPerformanceComplete before advancing. This async model lets multi-step actor choreography complete fully before dialogue continues. Three built-in performance types cover direct movement, navmesh navigation, and instant teleportation. Custom types can be created by extending the base class.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• How Performances Work
• Built-in Performance Types
• MoveTo_DialoguePerformance
• PathTo_DialoguePerformance
• RepositionPerformer_DialoguePerformance
• Async Completion
• Extending with Custom Performances
• ScriptCanvas Usage
• Quick Reference
• Glossary
• See Also

How Performances Work

When the sequencer encounters a PerformanceNodeData node, it:

1. Resolves the named performer entity via DialogueManagerRequestBus → GetPerformer.
2. Instantiates the performance object specified on the node.
3. Calls DoPerformance() — the public entry point.
4. Waits. The sequencer does not advance until the performance broadcasts OnPerformanceComplete.
5. Resumes from the next node once completion is received.

The performance itself handles the movement logic, monitors completion, and signals back through its notification bus. This means a single PerformanceNodeData can represent any action that takes time — walking to a spot, running a path, playing an animation, triggering a VFX sequence — as long as it broadcasts completion when done.

Built-in Performance Types

All three extend DialoguePerformance, the abstract base class. The base class provides DoPerformance(), ExecutePerformance(), and FinishPerformance() hooks, plus TickBus integration for per-frame movement updates.

MoveTo_DialoguePerformance

MoveTo_DialoguePerformance translates an actor toward one or more named stage markers using direct movement — no obstacle avoidance, no navmesh. It broadcasts movement requests over MoveTo_PerformanceNotificationBus. Listening systems (typically the performer’s movement component) receive those requests and execute the actual translation. When the actor reaches the final marker, the performance calls FinishPerformance() and broadcasts completion.

Use this for stylized games where physical path correctness is less important than snappy, predictable actor placement, or for any case where the path between actor and marker is guaranteed to be clear.

PathTo_DialoguePerformance

PathTo_DialoguePerformance navigates an actor to one or more named stage markers using the RecastNavigation navmesh. It requests a path from the navmesh, walks the actor along that path, and completes when the actor arrives at the final marker. Use this in games with detailed geometry where actors must walk around walls, furniture, and obstacles rather than moving in a straight line.

RecastNavigation must be enabled in the project and a navmesh must be baked in any level where PathTo performances are used.

RepositionPerformer_DialoguePerformance

RepositionPerformer_DialoguePerformance teleports an actor instantly to a named stage marker. It does not animate, translate, or navigate — it sets position directly. Useful for placing actors at the start of a new scene, recovering from a previous sequence that ended far from the required starting point, or repositioning actors that are off-camera and do not need visible movement.

Async Completion

All performances signal completion asynchronously. The sequencer does not poll or time out — it simply waits for the performance to call FinishPerformance(), which broadcasts OnPerformanceComplete over the appropriate notification bus. This means:

• A performance can take any amount of time.
• A performance can be driven by external events — animation callbacks, physics arrival, etc.
• Multiple performances can run in parallel if the node graph is structured to fork, because each notifies independently.

When writing custom performance types, always call FinishPerformance() when the action is done. Forgetting to do so will stall the sequencer indefinitely.

Extending with Custom Performances

Custom performance types are discovered automatically through O3DE serialization at startup. Extend DialoguePerformance, reflect it, and your custom type appears in the node editor’s performance picker and can be placed on any PerformanceNodeData node.

See the Framework API reference for the full base class interface and extension guide.

ScriptCanvas Usage

Performances are authored in the dialogue node graph and executed automatically by the sequencer. Most projects do not need to drive performances from ScriptCanvas directly. The common scripting patterns involve the movement side — receiving move or path requests from a performance and executing them on the performer entity.

Receiving a MoveTo Request

[MoveTo_PerformanceNotificationBus → StartMoveToMarker(markerEntity)]
    └─► [Move performer toward markerEntity position]
    └─► [When arrived → MoveTo_PerformanceRequestBus → ReportArrival]

Receiving a Reposition Request

[RepositionPerformer_PerformanceNotificationBus → RepositionToMarker(markerEntity)]
    └─► [Set performer transform to markerEntity transform]

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Dialogue System

For related systems:

• The Basics: Dialogue
• The Basics: Cinematics Manager
• The Basics: Dialogue UI

Get GS_Cinematics

GS_Cinematics — Explore this gem on the product page and add it to your project.