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
| Field | Type | Description |
|---|---|---|
systemId | const char* | Unique ID string (e.g., "dialogue", "audiograph", "unitaction"). Used for node filtering. |
systemName | const char* | Display name shown in the editor title bar. |
fileExtension | const char* | File extension for graph files (e.g., ".dialogue", ".audiograph"). |
mimeType | const char* | MIME type for drag-drop from the node palette. |
saveIdentifier | const char* | QSettings key for persisting window layout state. |
editorId | GraphCanvas::EditorId | Unique editor ID for the GraphCanvas system. |
Topology
| Field | Type | Default | Description |
|---|---|---|---|
topology | GraphTopology | FlowGraph | Determines connection style, slot types, and execution model. |
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
| Field | Type | Default | Description |
|---|---|---|---|
variablesEnabled | bool | false | Enables the variable panel, Get/Set variable nodes, and reference bindings. |
allowConnectionLoopback | bool | false | Whether cycles are allowed in the graph. |
State Machine Features
These fields are only relevant when topology == StateMachineGraph:
| Field | Type | Default | Description |
|---|---|---|---|
hierarchicalStates | bool | false | Enable compound/nested states. |
parallelLayers | bool | false | Enable parallel layer evaluation. |
transitionConditions | bool | false | Enable polymorphic transition conditions on connections. |
UI
| Field | Type | Description |
|---|---|---|
autoSpawnNodeTypes | AZStd::vector<AZ::TypeId> | Node types automatically created in every new graph (e.g., entry nodes). |
stylesheetPath | const char* | Optional path to a custom QSS stylesheet for node styling. |
windowTitle | const char* | Window title text. |
menuCategory | const char* | Menu path in the O3DE editor (e.g., "GS Tools"). |
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:
| Type | Enum | C++ Type |
|---|---|---|
| Bool | GS_Bool | bool |
| Int | GS_Int | int |
| Float | GS_Float | float |
| String | GS_Text | AZStd::string |
| Vector2 | GS_Vec2 | AZ::Vector2 |
| Vector3 | GS_Vec3 | AZ::Vector3 |
| Color | GS_Color | AZ::Color |
| EntityId | GS_EntityId | AZ::EntityId |
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
| Consideration | FlowGraph | DataFlowGraph | StateMachineGraph |
|---|---|---|---|
| Flow slots (FlowIn/FlowOut) | Yes | No | No |
| Connection direction | Left-to-right | Left-to-right | Multidirectional (perimeter) |
| Execution model | Step/wait/resume | Topological dirty-propagation | Tick-based state transitions |
| Node interface | IExecutableNode | IDataFlowNode | IStateMachineNode |
| Evaluator | FlowGraphEvaluator | DataFlowGraphEvaluator | StateMachineEvaluator |
| Cycles allowed | Optional | No (DAG required) | Yes (inherent) |
| Transition conditions | N/A | N/A | TransitionCondition base class |
| Example downstream | Dialogue Editor | Audio Event Graph | Unit Action Graph |