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.