Dialogue System

The Dialogue System is the runtime engine inside GS_Cinematics that drives all authored narrative experiences. It connects a persistent .dialoguedb asset to a node-graph sequencer, world-space and screen-space UI display, and an extensible set of polymorphic conditions, effects, and performances. Every piece is a standalone component communicating through EBus interfaces, so you can replace or extend any layer without modifying the gem itself.

The system is managed by the GS_DialogueManagerComponent, which participates in the standard Game Manager startup sequence.

For usage guides and setup examples, see The Basics: GS_Cinematics.

 

Contents

• Architecture
• Dialogue Manager
• Dialogue Sequencer
• Data Structure
• Effects
• Performances
• Dialogue UI
• Actors
• Editor
• See Also

---

Architecture

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.

---

Dialogue Manager

GS_DialogueManagerComponent owns the active dialogue database and performer registry. Extends GS_Core::GS_ManagerComponent.

Dialogue Manager API

---

Dialogue Sequencer

DialogueSequencerComponent traverses a node graph at runtime. The DialogueUIBridgeComponent routes dialogue and selection events to whichever UI is registered.

Dialogue Sequencer API

---

Data Structure

The .dialoguedb asset format, DialogueSequence, ActorDefinition, all node types, the polymorphic condition hierarchy, and localization types.

Data Structure API

---

Effects

Polymorphic DialogueEffect types executed synchronously from EffectsNodeData nodes. Built-in: SetRecords_DialogueEffect, ToggleEntitiesActive_DialogueEffect. Fully extensible.

Effects API

---

Performances

Polymorphic DialoguePerformance types executed asynchronously from PerformanceNodeData nodes. Built-in: MoveTo, PathTo, RepositionPerformer. Fully extensible.

Performances API

---

Dialogue UI

Screen-space and world-space dialogue display, selection menus, the typewriter text-reveal system, and the babble audio system.

Dialogue UI API

---

Actors

DialoguePerformerMarkerComponent places named performer anchors in the world, plus the ActorDefinition data model.

Dialogue Actors API

---

Editor

The in-engine GUI for authoring dialogue databases, sequences, and node graphs.

Dialogue Editor

---

See Also

For conceptual overviews and usage guides:

• The Basics: GS_Cinematics

For related references:

• Cinematics Manager – Cinematic lifecycle and stage markers
• GS_Cinematics Overview – Top-level gem reference
• GS_Core Managers – Manager base system

---

Get GS_Cinematics

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

1 - Dialogue Manager

GS_DialogueManagerComponent owns the active dialogue database and performer registry. It extends GS_Core::GS_ManagerComponent and participates in the standard Game Manager startup sequence.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• GS_DialogueManagerComponent
• Request Bus: DialogueManagerRequestBus
• Notification Bus: DialogueManagerNotificationBus
• DialoguePerformerMarkerComponent
• Script Canvas Examples
• See Also

GS_DialogueManagerComponent

Singleton GS_Play manager that owns the active .dialoguedb asset and the performer registry. Registered with the Game Manager startup sequence via GS_Core::GS_ManagerComponent.

Request Bus: DialogueManagerRequestBus

Singleton bus — Single address, single handler.

Notification Bus: DialogueManagerNotificationBus

Dialogue Manager notifications are inherited from ManagerBaseOutgoingEvents. See Manager for the full notification interface.

DialoguePerformerMarkerComponent

A world-space anchor component placed on NPC entities in the level. Performer markers register by name with the Dialogue Manager during activation. The dialogue system resolves actor names from the database to these world-space entities.

Request Bus: PerformerMarkerRequestBus

Script Canvas Examples

Starting a dialogue sequence by name:

See Also

For usage guides:

• The Basics: GS_Cinematics

For component references:

• Dialogue System Overview – Architecture and all child subsystems
• Dialogue Sequencer – Runtime node processing
• Dialogue Data Structure – Asset format and node types
• Cinematics Manager – Cinematic lifecycle and stage markers

For related resources:

• GS_Core Managers – Manager base system

Get GS_Cinematics

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

2 - Dialogue Data Structure

All dialogue content lives in a .dialoguedb asset file. This page documents the complete data model: the database container, sequences, actor definitions, every node type, the polymorphic condition and effect hierarchies, and the localization pipeline. It also provides an extension guide for registering custom conditions and effects from external gems.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• DialogueDatabase
• DialogueSequence
• ActorDefinition
• Node Types
• Conditions
• Effects
• Localization
• Complete Type Reference
• Extension Guide
• See Also

DialogueDatabase

The top-level asset that contains all data for a set of dialogue encounters.

The Dialogue Manager loads one database at a time. You can swap databases at runtime via DialogueManagerRequestBus::ChangeDialogueDatabase.

DialogueSequence

A single dialogue encounter within the database. Contains a linear or branching graph of nodes.

ActorDefinition

Defines a named character that appears in dialogue.

The actor name in the database is matched against the performer name registered by a DialoguePerformerMarkerComponent in the level. This links authored data to a world-space entity.

Node Types

All nodes inherit from the abstract DialogueNodeData base class. The sequencer uses the concrete type to determine processing behavior.

DialogueNodeData (Abstract Base)

Concrete Node Types

SelectionOption

A single choice within a SelectionNodeData.

Conditions

Conditions are polymorphic evaluators attached to node connections and selection options. They are registered automatically by extending the base class.

DialogueCondition (Abstract Base)

Built-in Conditions

Effects

Effects are polymorphic actions triggered by EffectsNodeData nodes. Each effect can also be reversed. They are registered automatically by extending the base class.

DialogueEffect (Abstract Base)

Built-in Effects

Localization

All player-visible text in the dialogue system passes through the localization layer.

LocalizedStringId

A reference to a localizable string.

LocalizedStringTable

Runtime lookup table loaded alongside the active dialogue database.

Complete Type Reference

Extension Guide

Use the ClassWizard templates to generate new dialogue extension classes — see GS_Cinematics Templates:

• DialogueCondition — generates a condition stub (Basic or Boolean variant). Requires a Reflect(context) call in DialogueSequencerComponent.cpp.
• DialogueEffect — generates an effect stub with DoEffect() / ReverseEffect(). Same manual registration step.
• DialoguePerformance — generates a performance stub with the full ExecutePerformance() / FinishPerformance() lifecycle. Same manual registration step.

All three types are polymorphic and discovered automatically.

External gems can add custom conditions, effects, and performances without modifying GS_Cinematics. The process is the same for all three categories.

Adding a Custom Condition

1. Define the class

#pragma once
#include <GS_Cinematics/Dialogue/Conditions/DialogueCondition.h>

namespace MyGem
{
    class HasItem_DialogueCondition : public GS_Cinematics::DialogueCondition
    {
    public:
        AZ_RTTI(HasItem_DialogueCondition, "{YOUR-UUID-HERE}", GS_Cinematics::DialogueCondition);
        AZ_CLASS_ALLOCATOR(HasItem_DialogueCondition, AZ::SystemAllocator);

        static void Reflect(AZ::ReflectContext* context);

        bool EvaluateCondition() override;

    private:
        AZStd::string m_itemName;
    };
}

2. Implement and reflect

#include "HasItem_DialogueCondition.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyGem
{
    void HasItem_DialogueCondition::Reflect(AZ::ReflectContext* context)
    {
        if (auto sc = azrtti_cast<AZ::SerializeContext*>(context))
        {
            sc->Class<HasItem_DialogueCondition, GS_Cinematics::DialogueCondition>()
                ->Version(1)
                ->Field("ItemName", &HasItem_DialogueCondition::m_itemName);

            if (auto ec = sc->GetEditContext())
            {
                ec->Class<HasItem_DialogueCondition>("Has Item", "Checks if the player has a specific item.")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyGem/Conditions")
                    ->DataElement(AZ::Edit::UIHandlers::Default, &HasItem_DialogueCondition::m_itemName, "Item Name", "");
            }
        }
    }

    bool HasItem_DialogueCondition::EvaluateCondition()
    {
        // Query your inventory system
        bool hasItem = false;
        // MyGem::InventoryRequestBus::BroadcastResult(hasItem, ...);
        return hasItem;
    }
}

The same pattern applies to custom effects (inherit DialogueEffect, implement DoEffect() / ReverseEffect()) and custom performances (inherit DialoguePerformance, implement DoPerformance() / ExecutePerformance() / FinishPerformance()).

See Also

For conceptual overviews and usage guides:

• Dialogue System Overview – Architecture

For component references:

• Dialogue Sequencer – Runtime node processing
• Dialogue Actors – Performer markers and actor definitions
• Performances – Built-in performance types
• Dialogue UI – Display components

For related resources:

• Dialogue Editor – Authoring GUI

Get GS_Cinematics

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

3 - Editor

For usage guides and setup examples, see The Basics: GS_Cinematics.

Performer

Performer Targeting

Sequences

Localization

Nodes

Start / End

End

Restart

New Sequence

Specific Node

Dialogue

Text

Animated/Stylized Text

Performance

Posing

Pathing

Portrait

Trigger Timeline

Sound

2D

3D

Option Menu + Choices

Actions + Set Record

Conditions

How to use conditions to determine path.

Not always related to player choice.

Timeline Integration

Start Sequence

Continue Dialogue

UI

O3DE Editor Menu

Editor GUI

Adding icon to editor is a complex problem, outlined by Nick.

Sequence Window

The Inspector Window can have any number of sub-tabs. Which might be valuable for adding unique settings, or multiple Conditions, for example. Basically component-ize different node types.

System Window

Actors Window

Ingame UI

Get GS_Cinematics

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

4 - Dialogue Sequencer

The Dialogue Sequencer is the runtime engine that executes dialogue sequences node-by-node. It receives a DialogueSequence from the Dialogue Manager, traverses the node graph, evaluates conditions, fires effects and performances, and routes text and selection events to the UI layer through the DialogueUIBridgeComponent.

The two components on this page work together:

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• DialogueSequencerComponent
• DialogueUIBridgeComponent
• Execution Flow
• C++ Usage
• See Also

DialogueSequencerComponent

The sequencer is the core playback controller. When a sequence starts, the sequencer reads the startNodeId, resolves the first node, and begins processing. Each node type has its own processing logic:

• TextNodeData – Sends text, speaker, and portrait data to the UI bridge for display.
• SelectionNodeData – Sends options to the UI bridge. Waits for a player selection before continuing.
• RandomNodeData – Picks a random outgoing connection (pure random or weighted) and continues.
• EffectsNodeData – Executes all attached DialogueEffect instances, then continues.
• PerformanceNodeData – Starts a DialoguePerformance. Waits for the performance to signal completion before continuing.

At each node, outgoing connections are evaluated. Conditions on connections are tested in priority order; the first connection whose conditions all pass is followed. When no outgoing connections remain, the sequence ends.

Request Bus: DialogueSequencerRequestBus

Singleton bus – Single address, single handler.

Notification Bus: DialogueSequencerNotificationBus

Multiple handler bus – any number of components can subscribe.

Runtime Token Management

The sequencer maintains a set of runtime tokens that track state within a single sequence execution. Tokens are used internally to prevent infinite loops, track visited nodes, and manage branching state. They are cleared when a sequence completes or is interrupted.

DialogueUIBridgeComponent

The UI Bridge sits between the sequencer and the presentation layer. It holds a reference to the currently registered DialogueUIComponent and DialogueUISelectionComponent. When the sequencer needs to display text or a selection menu, it calls the bridge, which forwards the request to the active UI. This allows you to swap between screen-space, world-space, or custom UI implementations at runtime without changing the sequencer or the dialogue data.

Request Bus: DialogueUIBridgeRequestBus

Singleton bus.

Notification Bus: DialogueUIBridgeNotificationBus

Multiple handler bus.

Execution Flow

A typical dialogue playback follows this path:

1. Start – DialogueManagerRequestBus::StartDialogueSequenceByName("MySequence") looks up the sequence in the active database and calls DialogueSequencerRequestBus::StartDialogueBySequence(sequence).
2. Node Processing – The sequencer reads the start node and begins processing. For each node:
   • Text – The sequencer calls DialogueUIBridgeRequestBus::RunDialogue(payload). The bridge forwards to the registered UI. The UI displays text (via TypewriterComponent), then fires OnDialogueComplete. The sequencer advances.
   • Selection – The sequencer calls DialogueUIBridgeRequestBus::RunSelection(payload). The bridge forwards to the selection UI. The player picks an option, the UI fires OnSelectionComplete(index). The sequencer follows the indexed connection.
   • Effects – The sequencer executes each DialogueEffect on the node, then advances immediately.
   • Performance – The sequencer starts the DialoguePerformance. When the performance calls OnPerformanceComplete, the sequencer advances.
   • Random – The sequencer picks a connection and advances immediately.
3. End – When no outgoing connections remain, the sequencer fires OnDialogueSequenceComplete and calls DialogueUIBridgeRequestBus::CloseDialogue().

C++ Usage

Starting a Sequence

#include <GS_Cinematics/GS_CinematicsBus.h>

// Start by name through the Dialogue Manager
GS_Cinematics::DialogueManagerRequestBus::Broadcast(
    &GS_Cinematics::DialogueManagerRequestBus::Events::StartDialogueSequenceByName,
    AZStd::string("PerryConfrontation")
);

Listening for Sequence Completion

#include <GS_Cinematics/GS_CinematicsBus.h>

class MyListener
    : public AZ::Component
    , protected GS_Cinematics::DialogueSequencerNotificationBus::Handler
{
protected:
    void Activate() override
    {
        GS_Cinematics::DialogueSequencerNotificationBus::Handler::BusConnect();
    }

    void Deactivate() override
    {
        GS_Cinematics::DialogueSequencerNotificationBus::Handler::BusDisconnect();
    }

    void OnDialogueSequenceComplete() override
    {
        // Sequence finished — resume gameplay, unlock camera, etc.
    }
};

See Also

For conceptual overviews and usage guides:

• Dialogue System Overview – Architecture and manager APIs

For component references:

• Dialogue UI – Display components and typewriter
• Performances – MoveTo, PathTo, RepositionPerformer
• Dialogue Actors – Performer markers

For related resources:

• Dialogue Data Structure – Node types, conditions, effects

Get GS_Cinematics

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

5 - Dialogue UI

The Dialogue UI layer handles all player-facing presentation of dialogue content. It is completely decoupled from the sequencer through the DialogueUIBridgeComponent – the sequencer never talks to a UI component directly. This page documents the seven components that make up the built-in UI system.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• DialogueUIComponent
• WorldDialogueUIComponent
• DialogueUISelectionComponent
• WorldDialogueUISelectionComponent
• DialogueSelectButtonComponent
• TypewriterComponent
• BabbleComponent
• Setup Guide
• See Also

DialogueUIComponent

The standard screen-space dialogue display. Receives dialogue payloads from the UI Bridge and renders speaker name, portrait, and text lines using LyShine UI canvases.

Request Bus: DialogueUIRequestBus

WorldDialogueUIComponent

Extends DialogueUIComponent for world-space rendering. Displays speech bubbles attached to performer entities in 3D space. Shares the same DialogueUIRequestBus interface as the base class. The world-space variant tracks the performer entity’s position and orients the UI element toward the camera.

Use WorldDialogueUIComponent when you want dialogue to appear as in-world speech bubbles rather than as a screen overlay.

DialogueUISelectionComponent

Screen-space player choice display. Builds a list of selectable options from a DialogueSelectionPayload, spawns DialogueSelectButtonComponent instances for each valid option, and waits for the player to pick one.

Request Bus: DialogueUISelectionRequestBus

WorldDialogueUISelectionComponent

Extends DialogueUISelectionComponent for world-space rendering. Displays selection options as in-world UI elements attached to performer entities. Shares the same DialogueUISelectionRequestBus interface as the base class.

DialogueSelectButtonComponent

An individual button within a selection menu. One instance is spawned per valid option. The button displays option text and forwards press events to the parent selection component.

Event Bus: DialogueUISelectionEventBus

TypewriterComponent

Character-by-character text reveal system. The typewriter receives a full text string and reveals it one character at a time at a configurable speed. It fires events on each character reveal and when the full text has been displayed. The typewriter is used internally by DialogueUIComponent but can also be used independently for any text reveal effect.

For detailed usage and standalone setup, see the Typewriter sub-page.

Request Bus: TypewriterRequestBus

Notification Bus: TypewriterNotificationBus

Multiple handler bus.

BabbleComponent

Procedural audio babble that plays in sync with the typewriter. Each character reveal from OnTypeFired can trigger a short audio event, creating a character-by-character speech sound. Different speakers can have different babble tones.

Request Bus: BabbleRequestBus

Data Types

Setup Guide

Screen-Space Dialogue

1. Create a UI canvas entity with your dialogue layout (speaker name text, portrait image, dialogue text area).
2. Attach a DialogueUIComponent to the entity.
3. Attach a TypewriterComponent to the text entity (or the same entity).
4. Optionally attach a BabbleComponent and configure speaker babble events.
5. Attach a DialogueUISelectionComponent to a separate entity (or the same canvas) for player choices.
6. Register the UI entity with DialogueUIBridgeRequestBus::RegisterDialogueUI(uiEntityId).

World-Space Dialogue

1. Follow the same steps as screen-space, but use WorldDialogueUIComponent and WorldDialogueUISelectionComponent instead.
2. The world-space components will track the performer entity’s position automatically.
3. Register the UI entity with the bridge the same way.

Swapping between screen-space and world-space at runtime requires only changing which UI entity is registered with the bridge. No sequencer or dialogue data changes are needed.

See Also

For conceptual overviews and usage guides:

• Dialogue System Overview – Architecture

For component references:

• Typewriter – Detailed TypewriterComponent reference
• Dialogue Sequencer – UI Bridge routing
• Dialogue Actors – Performer markers for world-space tracking

For related resources:

• Dialogue Data Structure – SelectionOption, text payload data

Get GS_Cinematics

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

5.1 - Typewriter

The TypewriterComponent provides character-by-character text reveal for dialogue display. It receives a string and a speed value, then reveals one character at a time on tick. It fires a notification on every character reveal and again when the full text is complete. The component is used internally by the DialogueUIComponent but can also be attached to any text entity independently for non-dialogue text effects.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• Request Bus: TypewriterRequestBus
• Notification Bus: TypewriterNotificationBus
• How It Works
• Text Command Reference
• Standalone Usage
• C++ Usage
• See Also

Request Bus: TypewriterRequestBus

Entity-addressed bus.

Notification Bus: TypewriterNotificationBus

Multiple handler bus – any number of listeners can connect.

How It Works

1. A caller (typically DialogueUIComponent) calls StartTypewriter(text, speed).
2. The component runs ParseFormattedText on the input string, stripping inline [command] tags and building an internal command schedule — pauses, speed changes, and style runs are all resolved before the first tick.
3. The component stores the parsed text, resets its character index to zero, and connects to TickBus.
4. On each tick, the component calculates how many characters should be visible based on elapsed time and the current speed. For each newly revealed character it fires OnTypeFired(character). Scheduled commands (pauses, speed changes, style tags) execute when their character position is reached.
5. The component updates the associated LyShine text element — style tags ([color], [b], etc.) are output as LyShine <font> / <b> / <i> markup inside the visible string.
6. When the last character is revealed, the component fires OnTypewriterComplete and disconnects from TickBus.
7. If ForceComplete is called mid-reveal, all remaining characters are revealed at once, OnTypewriterComplete fires, and the tick handler disconnects.

Text Command Reference

Inline commands are embedded directly in dialogue text strings and parsed by ParseFormattedText before reveal begins. Commands do not appear in the displayed text.

Format: [command=value] to open, [/command] to close where applicable.

[pause=X]

Pause the reveal for X seconds before continuing. If no value is given, defaults to 1.0 second. No closing tag.

Hello[pause=1.5] world.

[speed=X] / [/speed]

Change the typing speed to X characters per second from this point forward. [/speed] resets to the component’s configured default speed. Setting speed=0 causes all following text to appear instantly until the next speed tag.

Normal text [speed=5]fast text[/speed] normal again.

[color=VALUE] / [/color]

Change text colour. VALUE is any valid LyShine <font color> value — hex (#FF0000) or a named colour. Outputs <font color="VALUE">…</font> to the text element. Styles are tracked on a stack so nested formatting closes correctly.

Regular [color=#FF4444]danger text[/color] back to normal.

[size=VALUE] / [/size]

Change font size. VALUE is a numeric point size (e.g. 32). Outputs <font size="VALUE">…</font> to the text element.

Normal [size=48]big text[/size] normal.

[bold] or [b] / [/bold] or [/b]

Apply bold formatting. Both bold and b are valid keywords. Outputs <b>…</b>.

This is [b]bold[/b] text.

[italic] or [i] / [/italic] or [/i]

Apply italic formatting. Both italic and i are valid keywords. Outputs <i>…</i>.

This is [i]italic[/i] text.

[n] or [new]

Insert a newline character. No closing tag. Both n and new are valid.

First line[n]Second line.

Standalone Usage

The typewriter is not limited to dialogue. You can attach it to any entity with a LyShine text element for effects like:

• Tutorial text that types out instructions
• Item descriptions that reveal on hover
• Narrative text during loading screens
• Any text that benefits from a gradual reveal

Setup

1. Create an entity with a LyShine text component.
2. Attach a TypewriterComponent to the same entity.
3. Call TypewriterRequestBus::Event(entityId, &TypewriterRequestBus::Events::StartTypewriter, text, speed) from C++ or ScriptCanvas.
4. Optionally listen to TypewriterNotificationBus for per-character or completion events.

C++ Usage

#include <GS_Cinematics/GS_CinematicsBus.h>

// Start typewriter on a specific entity
AZ::EntityId textEntity = /* your text entity */;
GS_Cinematics::TypewriterRequestBus::Event(
    textEntity,
    &GS_Cinematics::TypewriterRequestBus::Events::StartTypewriter,
    AZStd::string("Hello, traveler. Welcome to the village."),
    12.0f  // 12 characters per second
);

// Force-complete if the player presses a button
GS_Cinematics::TypewriterRequestBus::Event(
    textEntity,
    &GS_Cinematics::TypewriterRequestBus::Events::ForceComplete
);

Script Canvas

Typewriter requests and notification events:

See Also

For conceptual overviews and usage guides:

• Dialogue UI – Parent UI component reference

For component references:

• BabbleComponent – Audio synchronized to typewriter events
• Dialogue Sequencer – How the sequencer triggers dialogue display

Get GS_Cinematics

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

6 - Dialogue Actors

Dialogue Actors connect authored character data in the .dialoguedb asset to world-space entities in the level. The system has two halves:

• ActorDefinition – The data side. Defined in the DialogueDatabase, it holds the actor’s name, portrait, and metadata.
• DialoguePerformerMarkerComponent – The world side. Attached to an entity in the level, it registers a named performer with the Dialogue Manager so the sequencer can find it at runtime.

When a dialogue sequence references an actor by name, the sequencer looks up the matching performer entity through DialogueManagerRequestBus::GetPerformer(name). This links the authored text, portraits, and performance instructions to a specific entity in the world.

For usage guides and setup examples, see The Basics: GS_Cinematics.

DialoguePerformerMarkerComponent

A component placed on any entity that represents a dialogue performer in the level. On Activate(), the marker registers itself with the Dialogue Manager by name. Multiple performers with the same name can exist in different levels, but only one should be active at a time within a single level.

Request Bus: PerformerMarkerRequestBus

Entity-addressed bus – each marker entity responds on its own address.

ActorDefinition Data Model

The ActorDefinition is the authored data for a single character, stored inside the DialogueDatabase.

Performer Registration and Lookup

Registration Flow

1. A DialoguePerformerMarkerComponent activates on an entity in the level.
2. During Activate(), the component calls DialogueManagerRequestBus::RegisterPerformerMarker(name, entityId).
3. The Dialogue Manager stores the mapping from name to entity ID.
4. When the component deactivates, it unregisters itself.

Lookup Flow

1. The sequencer processes a node that references an actor name (e.g. a TextNodeData with speaker “perry” or a PerformanceNodeData targeting “perry”).
2. The sequencer calls DialogueManagerRequestBus::GetPerformer("perry").
3. The Dialogue Manager returns the registered entity ID.
4. The sequencer (or performance) can now query the performer’s position, facing, and tracking state through PerformerMarkerRequestBus.

Multiple Performers

The actorTargetId field on node data allows a sequence to target a specific instance of a performer when multiple entities share the same actor name. This supports scenarios like having the same NPC appear in multiple locations across different levels while keeping the same actor definition in the database.

Setup

1. In your .dialoguedb asset, define an actor with a unique name (e.g. “perry”) using the Dialogue Editor.
2. In your level, create an entity and attach a DialoguePerformerMarkerComponent.
3. Set the marker’s performer name to match the actor name in the database (e.g. “perry”).
4. Position the entity where the performer should appear in the world.
5. Optionally, add child entities for position offsets or attach visual representation (mesh, animation) to the same entity.

The marker entity will self-register with the Dialogue Manager on activation. The sequencer can now find this performer when processing sequences that reference the matching actor name.

Script Canvas Examples

Getting a performer’s name and world position:

See Also

• Dialogue Data Structure – ActorDefinition in the database
• Dialogue System Overview – Dialogue Manager registration API
• Dialogue Sequencer – How the sequencer looks up performers
• Performances – Performance types that drive performer entities
• Dialogue UI – World-space UI that tracks performer positions

Get GS_Cinematics

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

7 - Effects

Effects are synchronous actions executed from EffectsNodeData nodes within a dialogue sequence. When the Dialogue Sequencer encounters an Effects node, it calls DoEffect() on each DialogueEffect in the node’s list in order, then immediately advances to the next node.

All effects are polymorphic — extending the base class automatically populates the effects list in the dialogue editor at startup.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• DialogueEffect (Abstract Base)
• SetRecords_DialogueEffect
• ToggleEntitiesActive_DialogueEffect
• Complete Effect Type Reference
• Creating a Custom Effect
• See Also

DialogueEffect (Abstract Base)

The base class for all dialogue effects. Effects execute synchronously and can be reversed for rollback scenarios.

Virtual Methods

Lifecycle

1. The sequencer encounters an EffectsNodeData node.
2. The sequencer calls DoEffect() on each effect in the node’s list in order.
3. All effects complete synchronously within the same frame.
4. The sequencer immediately advances to the next node.

SetRecords_DialogueEffect

Sets one or more game records in the GS_Save RecordKeeper system. Commonly used to flag quest progress, NPC disposition, or world state changes triggered by dialogue.

ToggleEntitiesActive_DialogueEffect

Activates or deactivates a list of entities in the level. Used to show or hide objects, enable or disable triggers, or change world state during dialogue.

Complete Effect Type Reference

Creating a Custom Effect

To add a custom effect type from an external gem:

1. Define the class

#pragma once
#include <GS_Cinematics/Dialogue/Effects/DialogueEffect.h>

namespace MyGem
{
    class PlaySound_DialogueEffect : public GS_Cinematics::DialogueEffect
    {
    public:
        AZ_RTTI(PlaySound_DialogueEffect, "{YOUR-UUID-HERE}", GS_Cinematics::DialogueEffect);
        AZ_CLASS_ALLOCATOR(PlaySound_DialogueEffect, AZ::SystemAllocator);

        static void Reflect(AZ::ReflectContext* context);

        void DoEffect() override;
        void ReverseEffect() override;

    private:
        AZStd::string m_soundEvent;
    };
}

2. Implement and reflect

#include "PlaySound_DialogueEffect.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyGem
{
    void PlaySound_DialogueEffect::Reflect(AZ::ReflectContext* context)
    {
        if (auto sc = azrtti_cast<AZ::SerializeContext*>(context))
        {
            sc->Class<PlaySound_DialogueEffect, GS_Cinematics::DialogueEffect>()
                ->Version(1)
                ->Field("SoundEvent", &PlaySound_DialogueEffect::m_soundEvent);

            if (auto ec = sc->GetEditContext())
            {
                ec->Class<PlaySound_DialogueEffect>("Play Sound", "Fires a sound event during dialogue.")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyGem/Effects")
                    ->DataElement(AZ::Edit::UIHandlers::Default, &PlaySound_DialogueEffect::m_soundEvent, "Sound Event", "");
            }
        }
    }

    void PlaySound_DialogueEffect::DoEffect()
    {
        // Fire the sound event
    }

    void PlaySound_DialogueEffect::ReverseEffect()
    {
        // Stop the sound if needed
    }
}

Custom effects are discovered automatically at startup through O3DE serialization — no manual registration step is required.

See Also

For conceptual overviews and usage guides:

• Dialogue System Overview – Architecture and subsystems
• GS_Cinematics Overview – Top-level gem reference

For component references:

• Dialogue Sequencer – How the sequencer drives effects
• Dialogue Data Structure – EffectsNodeData and data model

For related resources:

• Performances – Asynchronous performance types

Get GS_Cinematics

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

8 - Performances

Performances are asynchronous actions executed from PerformanceNodeData nodes within a dialogue sequence. When the Dialogue Sequencer encounters a performance node, it instantiates the appropriate DialoguePerformance subclass, starts it, and waits for it to signal completion before advancing to the next node.

All performances are polymorphic by extending the class they automatically populate the performances list when adding performances to a node.

For usage guides and setup examples, see The Basics: GS_Cinematics.

Contents

• DialoguePerformance (Abstract Base)
• MoveTo_DialoguePerformance
• PathTo_DialoguePerformance
• RepositionPerformer_DialoguePerformance
• Complete Performance Type Reference
• Creating a Custom Performance
• See Also

DialoguePerformance (Abstract Base)

The base class for all dialogue performances. Extends AZ::TickBus::Handler so that performances can drive time-based behavior across multiple frames.

Virtual Methods

Lifecycle

1. The sequencer encounters a PerformanceNodeData and instantiates the corresponding DialoguePerformance subclass.
2. The sequencer calls DoPerformance().
3. DoPerformance() connects to TickBus and calls ExecutePerformance().
4. The performance runs across multiple ticks until its completion condition is met.
5. The performance calls FinishPerformance(), which disconnects from TickBus and notifies the sequencer.
6. The sequencer advances to the next node.

MoveTo_DialoguePerformance

Moves a performer entity to a named stage marker position over time using direct interpolation (no navmesh). Suitable for short-distance movements within a scene where pathfinding is unnecessary.

Request Bus: MoveTo_PerformanceRequestBus

Notification Bus: MoveTo_PerformanceNotificationBus

PathTo_DialoguePerformance

Navigates a performer entity to a named stage marker along a RecastNavigation navmesh path. Suitable for longer-distance movements where the performer must navigate around obstacles. Requires RecastNavigation to be enabled in the project.

Request Bus: PathTo_PerformanceRequestBus

Notification Bus: PathTo_PerformanceNotificationBus

RepositionPerformer_DialoguePerformance

Instantly teleports a performer entity to a named stage marker position. No interpolation, no pathfinding – the entity is moved in a single frame. Useful for off-screen repositioning between scenes or for snapping a performer to a mark before a sequence begins.

Notification Bus: RepositionPerformer_PerformanceNotificationBus

Complete Performance Type Reference

Creating a Custom Performance

To add a custom performance type from an external gem:

1. Define the class

#pragma once
#include <GS_Cinematics/Dialogue/Performances/DialoguePerformance.h>

namespace MyGem
{
    class PlayAnimation_DialoguePerformance : public GS_Cinematics::DialoguePerformance
    {
    public:
        AZ_RTTI(PlayAnimation_DialoguePerformance, "{YOUR-UUID-HERE}", GS_Cinematics::DialoguePerformance);
        AZ_CLASS_ALLOCATOR(PlayAnimation_DialoguePerformance, AZ::SystemAllocator);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        void ExecutePerformance() override;
        void OnTick(float deltaTime, AZ::ScriptTimePoint time) override;

    private:
        AZStd::string m_animationName;
        bool m_animationComplete = false;
    };
}

2. Implement and register

void PlayAnimation_DialoguePerformance::ExecutePerformance()
{
    // Start the animation on the performer entity
    // Listen for animation completion
}

void PlayAnimation_DialoguePerformance::OnTick(float deltaTime, AZ::ScriptTimePoint time)
{
    if (m_animationComplete)
    {
        FinishPerformance();
    }
}

See Also

For conceptual overviews and usage guides:

• Dialogue System Overview – Manager APIs and extensible types
• GS_Cinematics Overview – Stage markers and cinematic mode

For component references:

• Dialogue Sequencer – How the sequencer drives performances
• Dialogue Actors – Performer markers that performances target

For related resources:

• Dialogue Data Structure – PerformanceNodeData and extension guide

Get GS_Cinematics

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