GS_GraphCanvas

[Your Gem]              (gs_cinematics, gs_audio, gs_unit, or your own)
   Provides: GraphSystemDescriptor, GraphContext subclass, Node definitions
        |
[gs_graphcanvas]        (STATIC LIB — framework layer)
   Provides: MainWindow, save/load, undo/redo, variables, inspector,
             node registry, palette, execution engines, multi-doc, pages
        |
[O3DE GraphModel]       (engine — data model)
   Provides: Graph, Node, Slot, Connection, DataType, GraphContext
        |
[O3DE GraphCanvas]      (engine — visual rendering)
   Provides: QGraphicsScene rendering, node visuals, slot widgets,
             connection rendering, selection, copy/paste, bookmarks

ly_add_target(
    NAME GS_MyTool.Editor.Static STATIC
    ...
    BUILD_DEPENDENCIES
        PRIVATE
            Gem::GraphCanvas.Editor.Static
            Gem::GraphModel.Editor.Static
            Gem::GS_GraphCanvas.Editor.Static
            ...
)

1 - Descriptor & Topology

The GraphSystemDescriptor tells gs_graphcanvas what kind of editor to build. It is a plain struct that you fill out and pass to the MainWindow constructor.

GraphSystemDescriptor Fields

Identity

Topology

Topology options:

• FlowGraph — Directional flow slots (FlowIn/FlowOut), sequential step/wait/resume execution. Best for: dialogue trees, scripting, sequential processes.
• DataFlowGraph — No flow slots, data-only connections with dirty-propagation evaluation. Best for: audio, shaders, procedural generation, signal processing.
• StateMachineGraph — Multidirectional perimeter connections with tick-based state transitions. Best for: HFSM, behavior trees, character controllers.

See Execution Engines for detailed Topology Flow reference and internal API for runtime execution.

Feature Flags

State Machine Features

These fields are only relevant when topology == StateMachineGraph:

UI

GraphContext

Each graph system needs a GraphContext subclass that registers the data types available in that system. The framework provides a set of built-in CommonDataTypes available to all systems:

If your tool only uses these built-in types, your GraphContext subclass may be trivial. Domain-specific types (e.g., AudioRoute for audio graphs) are registered by calling context->RegisterDataType(...) in your subclass.

Topology Decision Matrix

2 - Nodes

All gs_graphcanvas nodes inherit from BaseNode, which extends GraphModel::Node. BaseNode provides slot registration helpers, flow slot support, inspector property reflection, and transition descriptor management for state machines.

Slot Registration

Slots are registered in the RegisterSlots() override using helper macros:

GS_INPUT_SLOT_TYPED("slot_name", "Display Name", DataTypeEnum, DefaultValue)
GS_OUTPUT_SLOT_TYPED("slot_name", "Display Name", DataTypeEnum)
GS_INPUT_SLOT_CONNECTION("slot_name", "Display Name")        // Connection-only, no inline editor
GS_MULTI_INPUT_SLOT_CONNECTION("slot_name", "Display Name")  // Multiple connections allowed

All input slots use editableOnNode=true by default, providing inline value editing directly on the node in the graph canvas.

For flow-based graphs, call RegisterFlowSlots() to add FlowIn and FlowOut slots. Override HasFlowIn() or HasFlowOut() to control which flow slots appear (e.g., a Start node has no FlowIn).

For state machine graphs, call RegisterTransitionSlots() to add transition_in and transition_out perimeter slots. Override HasTransitionIn() / HasTransitionOut() to control slot presence.

Auto-Registration

Nodes self-register into the node palette via macros:

// Register for ALL graph systems:
GS_AUTO_REGISTER_NODE(MyNode)

// Register for a specific system only:
GS_AUTO_REGISTER_NODE_FOR(MyNode, "dialogue")

Each registered node includes a category string (from CATEGORY constant), display name (from TITLE), and a creation lambda. The NodeRegistry singleton manages all registrations and handles MIME event reflection for drag-drop.

Rapid Node Creation

For simple nodes with no custom logic, a single macro generates the entire class:

DEFINE_SIMPLE_NODE_WITH_SLOTS(
    MyNode,
    "{UNIQUE-UUID}",
    "My Node",
    "My Category",
    {INPUT_SLOT("input", GS_Text, "Input text")},
    {OUTPUT_SLOT("output", GS_Text, "Output text")}
)

This generates the class with TITLE, CATEGORY, Reflect(), RegisterSlots(), and the constructor.

Three Tiers of Node Complexity

Reflect Pattern

Every node’s Reflect() method must include a FindClassData guard because gs_graphcanvas is a static library and types can be registered from multiple DLLs:

void MyNode::Reflect(AZ::ReflectContext* context)
{
    if (auto* sc = azrtti_cast<AZ::SerializeContext*>(context))
    {
        if (sc->FindClassData(azrtti_typeid<MyNode>())) { return; }  // MANDATORY guard
        sc->Class<MyNode, GS_GraphCanvas::BaseNode>()
            ->Version(1)
            ->Field("MyProperty", &MyNode::m_myProperty)
            ;
    }
    if (auto* ec = azrtti_cast<AZ::EditContext*>(context))
    {
        ec->Class<MyNode>("My Node", "Description")
            ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                ->Attribute(AZ::Edit::Attributes::AutoExpand, true)
            ->DataElement(AZ::Edit::UIHandlers::Default, &MyNode::m_myProperty,
                "My Property", "Tooltip")
            ;
    }
}

Built-in Nodes

gs_graphcanvas includes several utility nodes available to all graph systems:

Variable nodes are automatically included in the palette when variablesEnabled = true in the descriptor.

3 - Editor Window

The MainWindow class provides a complete graph editor out of the box. Downstream editors subclass it and override virtual hooks to add domain-specific behavior.

Out-of-the-Box Features

Every MainWindow instance includes:

• Multi-document tabs — Each graph opens in its own tab with dirty tracking (asterisk * in tab title) and close-with-save prompts
• File menu — New, Open, Save, Save As, Open Recent (tracks last 10 files)
• Edit menu — Undo/Redo (Ctrl+Z / Ctrl+Y), Cut/Copy/Paste
• Node palette — Searchable list of available nodes with drag-drop creation
• Inspector panel — Auto-generated property editor from node EditContext reflection
• Variable panel — Variable declarations, type selection, and default value editing (when enabled)

Virtual Hooks

MainWindow provides virtual methods for downstream customization:

File Menu Overrides

virtual void AddFileNewAction();
virtual void AddFileOpenAction();
virtual void AddFileSaveAction();
virtual void AddFileSaveAsAction();

Override these to replace per-file behavior with container-level behavior (e.g., the Dialogue Editor overrides these to save the entire database instead of individual graphs).

Lifecycle Hooks

Full-Window Page System

The page system lets you add non-graph pages alongside the graph editor in the same window:

AddFullWindowPage("Performers", m_performersWidget);
AddFullWindowPage("System", m_systemWidget);
SetGraphPageTitle("Sequences");  // Rename the default graph tab
SetActivePage(index);            // Switch between pages

The base class creates a tab bar on the first call. When switching to a non-graph page, the graph canvas and all docks are hidden; the page widget fills the entire window. Dock layout is preserved between switches.

Examples in practice:

• Dialogue Editor: Sequences (graph) + Performers + System
• Unit Action Editor: Layers (graph) + Layer Details

Container Editor Pattern

For editors where multiple graphs live inside a single file (like dialogue sequences in a database, or state machine layers in a unit action asset), MainWindow provides in-memory graph operations:

Opening Sub-Graphs

OpenGraphFromAsset(GraphDocumentAsset& asset, const QString& title, AZ::SerializeContext* sc);

Deserializes a graph from an asset’s byte buffer and opens it as a new tab.

Capturing Sub-Graphs

CaptureGraphToAsset(GraphModel::GraphId graphId, GraphDocumentAsset& outAsset, AZ::SerializeContext* sc);

Serializes an open graph back into the asset’s byte buffer. Used before saving the container.

Creating Empty Graphs

OpenNewGraphTab(const QString& title);

Opens a blank graph tab for a new sub-object.

Clearing Dirty State

ClearAllDocumentDirty();

Clears dirty markers on all open tabs. Called after a container-level save so that individual tab dirty states don’t linger.

Typical Container Save Flow

1. Iterate all open graph tabs
2. Call CaptureGraphToAsset() for each to write graphs back to the container
3. Serialize the container to disk
4. Call ClearAllDocumentDirty() to clear all tab markers

4 - Variables

When variablesEnabled = true in the GraphSystemDescriptor, the framework provides a complete variable system for storing and reading named values within a graph.

Variable Panel

The Variable Panel is a dock widget with a table listing all declared variables. Each variable has:

• Name — User-defined identifier
• Data Type — Selected from a dropdown of registered types (Bool, Int, Float, String, etc.)
• Default Value — Type-specific editor (checkbox for Bool, spinner for numeric, text field for String, multi-field for vectors, color picker for Color)

Variables are per-graph. Add or remove variables using the panel controls. Undo/redo integration is automatic.

Get / Set Variable Nodes

When variables are enabled, GetVariableNode and SetVariableNode are automatically included in the node palette under the “Variables” category.

• GetVariableNode — Outputs the current value of a named variable
• SetVariableNode — Writes a value to a named variable

Both nodes reference a variable by name. If the variable is renamed, all referencing Get/Set nodes update automatically.

Convert to Reference

Right-click any typed input slot on a node to convert it to a variable reference. A dropdown appears listing all declared variables that match the slot’s data type. Once bound:

• The slot displays the variable name instead of an inline value
• The slot reads the variable’s value at evaluation time
• Right-click again and select “Convert to Value” to unbind

Reference bindings are persisted as VariableBinding structs (NodeId + SlotName + VariableId) and restored automatically on load.

Drag to Canvas

Drag a variable from the Variable Panel directly onto the graph canvas. A popup menu asks whether to create a Get or Set node for that variable. The node is automatically configured with the variable name and data type.

Runtime Variable Access

At runtime, variables live in the GraphExecutionContext blackboard. The execution context provides:

• Read/write access by variable name
• InitializeBindings() resolves VariableId references to names
• Variable changes can trigger re-evaluation (in DataFlowGraph, MarkDirty(variableName) propagates to dependent nodes)

Downstream gems expose variable control through their own APIs. For example, the Audio Event Graph provides SetAudioGraphVariable(instanceId, name, value) to control graph variables from gameplay code.

5 - Execution Engines

gs_graphcanvas provides three execution engines — one for each topology. All share a common GraphExecutionContext for variable storage and value resolution, and GraphInstance for creating independent runtime copies.

FlowGraphEvaluator

Topology: FlowGraph

Step/wait/resume execution model for sequential graphs. The evaluator follows FlowIn/FlowOut connections from node to node.

Nodes implement the IExecutableNode interface:

FlowResult Execute(GraphExecutionContext& context);

FlowResult controls what happens after a node executes:

Used by: Dialogue Editor — text nodes return Wait while dialogue is displayed, then Resume() advances to the next node.

DataFlowGraphEvaluator

Topology: DataFlowGraph

Dirty-propagation evaluator for continuously-evaluated graphs. On initialization, builds a topological ordering of all nodes via Kahn’s algorithm.

Nodes implement the IDataFlowNode interface:

void Process(GraphExecutionContext& context);

Evaluation Pipeline

1. Initialize — Build topological order from the graph’s connection structure
2. Track dependencies — Map which nodes depend on which variables
3. Mark dirty — MarkDirty(variableName) marks dependent nodes dirty, then transitively marks all downstream nodes
4. Evaluate — Iterate nodes in topological order, re-running only dirty nodes

The explicit dirty marking (not automatic) gives downstream code batching control — set multiple variables, then call Evaluate() once.

Empty Any Pattern

When a data-flow node has no valid output (gated off, no valid input), it must output AZStd::any{} (truly empty), never a default-constructed value:

if (validInput)
    context.SetOutputValue(this, "result", computedValue);
else
    context.SetOutputValueAny(this, "result", AZStd::any{});

This is critical because multi-input resolution returns the first non-empty AZStd::any. A default-constructed struct inside an any is non-empty and will mask valid values from other connections.

Used by: Audio Event Graph — entry gate nodes, filter nodes, and effect nodes all follow this pattern.

StateMachineEvaluator

Topology: StateMachineGraph

Tick-based evaluator for hierarchical finite state machines. Maintains the current active state and evaluates transitions each tick.

Nodes implement the IStateMachineNode interface:

void OnEnter(GraphExecutionContext& context);
void OnTick(GraphExecutionContext& context, float deltaTime);
void OnExit(GraphExecutionContext& context);

Tick Cycle

1. Increment __stateTime auto-variable
2. Gather all outgoing transitions from the current state
3. Evaluate conditions on each transition
4. Fire the highest-priority valid transition (OnExit on source, OnEnter on destination)
5. Call OnTick on the active state

Transition Conditions

Each connection carries a TransitionDescriptor with a priority and a list of polymorphic TransitionCondition objects. Built-in conditions:

Custom conditions are created by subclassing TransitionCondition, reflecting it, and it auto-discovers via SerializeContext::EnumerateDerived().

ParallelLayerEvaluator

Wraps multiple StateMachineEvaluator instances (one per layer) with shared context synchronization. Each layer evaluates independently but shares the same variable context for cross-layer reads.

Used by: Unit Action Graph — parallel Movement, Action, and Rotation layers.

GraphExecutionContext

Shared context for all evaluator types. Provides:

• Input value resolution — GetInputValue<T>() and GetInputValueAny() with multi-input resolution (returns first non-empty value)
• Output values — SetOutputValue() and SetOutputValueAny()
• Blackboard — Variable storage by name
• Binding initialization — InitializeBindings() resolves VariableId references to variable names

GraphInstance

An independent runtime copy of a graph. GraphInstance::CreateFromAsset() deserializes a fresh graph from a GraphDocumentAsset’s byte buffer, initializes variables and bindings. Each instance is fully independent — downstream gems can pool instances for high-frequency execution paths.