This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

Script Canvas Node Definition Reference

Script Canvas Node Definition files are XML files that AzAutoGen uses to generate the necessary C++ code for registering nodes, defining their topology, and reducing the amount of “boilerplate” code that would otherwise be necessary. This reference guide covers all the available XML tags and attributes needed to create Script Canvas nodes.


ScriptCanvas

The ScriptCanvas tag is the top-level description of the node. It is used to produce the C++ class that represents the node and to configure its serialization & editor properties.

AttributeRequirementsDescriptionExample
IncludeRequiredThe name of the Script Canvas NodeInclude="Include/ScriptCanvas/Internal/Nodeables/BaseTimer.h"
xmlns:xsiRecommendedIndicates that the elements and data types used in the schema come from the "http://www.w3.org/2001/XMLSchema" namespace. It also specifies that the elements and data types that come from it should be prefixed with xsi:.xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

Class

The Class tag is used to define the node’s appearance within O3DE. Many of these attributes control the node’s serialization..

AttributeRequirementsDescriptionExample
NameRequiredThe name of the Script Canvas NodeName="My Node"
QualifiedNameRequiredFully qualified name, includes all namespaces. For example, ScriptCanvas::Nodes::MyNode.QualifiedName="ScriptCanvas::Nodes::MyNode"
DescriptionRecommendedDescribes the node and its functionality, this is displayed as a tooltip on the nodeDescription="An example node"
CategoryRecommendedCategory defines where this node will appear on the Node Palette. You can nest categories by separating with the / character.Category="Math/Linear Algebra"
PreferredClassNameOptionalIn some cases it may be desirable to override the node’s class name in the Script Canvas Editor. This field doesn’t change the node’s functionality, only the class name used in the EditContext.PreferredClassName="A Different Name"
UuidOptionalAllows you to provide a specific Universal Identifier, this is generally generated but in some situations it may be desirable to provide a specific UUID.Uuid="{EE36A690-7C33-445F-B9E8-BD045D6ACC1D}"
IconUnusedCurrently unused, would provide a path for displaying a custom icon associated with a nodeIcon="Icons/ScriptCanvas/Checkpoint.png"
VersionOptionalAs with any serialized class in O3DE, nodes may provide a version, this creates a mechanism for addressing code changes that may invalidate dataVersion="2"
VersionConverterOptionalIf the topography of a node changes, a version converter may be used to provide a migration mechanismVersionConverter="ScriptCanvas::ForEachVersionConverter"
EventHandlerOptionalUsed by the serialization system, it may sometimes be useful to capture serialization eventsEventHandler="SerializeContextOnWriteEndHandler<EBusEventHandler>"
DeprecatedOptionalMarks this node as deprecated, deprecated nodes will not be displayed in the Node Palette, but may still appear in existing Script Canvas graphsDeprecated="This node has been deprecated"
DeprecationUUIDOptionalWhen specified, this UUID is used to replace this deprecated node with the node of the provided UUID, this allows graphs to be updated automaticallyDeprecationUUID="{D3629902-02E9-AE59-0424-F366D342B433}"
BaseOptionalIn some cases it may be desireable to specify the base class, for example when a node derives from a different nodeBase="ScriptCanvas::Nodes::Internal::BaseTimerNode"
GraphEntryPointOptionalWhen enabled, Script Canvas may use this node as the entry point to begin running.GraphEntryPoint="True"
EditAttributesOptionalProvides EditContext attributes in the node’s serialization. Use the @ character to separate the key/value. Separate multiple attributes with a semi colon (;).EditAttributes="AZ::Script::Attributes::ExcludeFrom@AZ::Script::Attributes::ExcludeFlags::All; ScriptCanvas::Attributes::Node::TitlePaletteOverride@StringNodeTitlePalette"
DynamicSlotOrderingOptionalEnable this when the order of slots may change at edit time. By default, this is disabled.DynamicSlotOrdering="True"

Note: When specifying C++ code you must use the HTML Entity Codes. For example, in the case of EventHandler, instead of the C++ code SerializeContextOnWriteEndHandler<EBusEventHandler>, specify SerializeContextOnWriteEndHandler&lt;EBusEventHandler&gt;

Examples

<ScriptCanvas Include="Include/ScriptCanvas/Libraries/Core/Start.h" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Class Name="Start"
        QualifiedName="ScriptCanvas::Nodes::Core::Start"
        PreferredClassName="On Graph Start"
        Uuid="{F200B22A-5903-483A-BF63-5241BC03632B}"
        Category="Timing"
        Version="2"
        GraphEntryPoint="True"
        Description="Starts executing the graph when the entity that owns the graph is fully activated.">
    </Class>
</ScriptCanvas>

Execution slot elements

Input

The Input tag is used to configure execution entry slots on a node. Visually these would be on the left side of a node in the Script Canvas editor.

Supported Attributes

AttributeRequirementsDescriptionExample
NameRequiredThe name for this input slotName="My Node"
DescriptionOptionalDescribes this input slot, it is displayed as a tooltip in the editorDescription="Useful node"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"
OutputOptionalAllows a corresponding output execution slot to be providedOutput="Done"
LatentOptionalThis only applies if the Output attribute is provided, it signals that the Output slot may not execute immediately and may take more than one frameOutput="Done" Latent="true"

Output

The Output tag is used to configure execution exit slots on a node. Visually these would be on the right side of a node in the Script Canvas editor.

Supported Attributes

AttributeRequirementsDescriptionExample
NameRequiredThe name for this input slotName="My Node"
DescriptionOptionalDescribes this input slot, it is displayed as a tooltip in the editorDescription="Useful node"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"
LatentOptionalThis only applies if the Input tag’s Output attribute is provided. It signals that the Output slot may not execute immediately and may take more than one frame.Output="Done" Latent="true"

Examples

<Input Name="Start" Output="Started" Description="Use this to start this operation"/>
<Input Name="Stop " Output="Stopped" Latent="true" Description="Use this to stop this operation"/>

<Output Name="Out" Description="Called immediately after this node is invoked"/>
<Output Name="OperationComplete" Latent="true" Description="Called when this node's operation has finished"/>

Data slot elements

Parameter

The Parameter tag can be specified within the Input tag, it is used to define data entry points into a node.

Supported Attributes

AttributeRequirementsDescriptionExample
NameRequiredThe name for this data input slotName="Operand A"
TypeRequiredThis is the C++ type of the property. It must be a type that’s exposed to the O3DE serialization context. If the type contains special characters, you must use the HTML Entity Codes (for example, update AZStd::vector<int> to AZStd::vector&lt;int&gt;).Type="float"
DescriptionOptionalDescribes this data input slot, it is displayed as a tooltip when hovering over the slotDescription="Result of this mathematical operation"

Examples

<Input Name="In">
    <Parameter Name="Value 1" Type="float" Description="First Value in the equation"/>
    <Parameter Name="Value 2" Type="float" Description="Second Value in the equation"/>
</Input>

Property

AttributeRequirementsDescriptionExample
NameRequiredThe name of the property. This is the name that will appear in the slot on the node, and is also the name of the property in C++. The name may be overridden using PropertyData.Name="m_timeUnit"
TypeRequiredThis is the C++ type of the property. It must be a type that’s exposed to the O3DE serialization context. If the type contains special characters, you must use the HTML Entity Codes (for example, update AZStd::vector<int> to AZStd::vector&lt;int&gt;).Type="float"
DefaultValueOptionalAllows you to provide the default value for the propertyDefaultValue="1000.0"
UIHandlerOptionalAllows the user to override the property’s default UI Handler in the Node InspectorUIHandler="AZ::Edit::UIHandlers::ComboBox"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"
IsInputGrammar OnlyUsed to define if this property will be placed as an input data slot on a node. This option is not available for NodeablesIsInput="True" or IsInput="False"
IsOutputGrammar OnlyUsed to define if this property will be placed as an output data slot on a node. This option is only available for NodeablesIsOutput="True" or IsOutput="False"

PropertyData

The PropertyData can be provided for elements of Property, it provides a mechanism to override certain EditContext parameters of the type’s reflection.

AttributeRequirementsDescriptionExample
NameRequiredThe name of the property, this is the name that will of the slot on the nodeName="Time Unit"

EditAttribute

The EditAttribute element can be provided within PropertyData, it allows to provide O3DE serialization attributes to the property.

AttributeRequirementsDescriptionExample
KeyRequiredThe attribute name to be setKey="AZ::Edit::Attributes::GenericValueList"
ValueRequiredThe value to set on the attributeValue="&amp;BaseTimer::GetTimeUnitList"

Examples

<Property Name="m_timeUnits" Type="int" DefaultValue="0" Serialize="true">
    <PropertyData Name="Units" Description="Units to represent the time in." UIHandler="AZ::Edit::UIHandlers::ComboBox">
        <EditAttribute Key="AZ::Edit::Attributes::GenericValueList" Value="&amp;BaseTimer::GetTimeUnitList"/>
        <EditAttribute Key="AZ::Edit::Attributes::PostChangeNotify" Value="&amp;BaseTimer::OnTimeUnitsChanged"/>
    </PropertyData>
</Property>


Parameter

Parameter is used by the Input and Output tags. They represent data slots on the node.

AttributeRequirementsDescriptionExample
Name
TypeRequiredThis is the C++ type of the property. It must be a type that’s exposed to the O3DE serialization context. If the type contains special characters, you must use the HTML Entity Codes (for example, update AZStd::vector<int> to AZStd::vector&lt;int&gt;).Type="float"
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"
DefaultValueOptionalAllows you to provide the default value for the propertyDefaultValue="1000.0"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"

Return

Return is used by the Input tag, represents an output data slot on the node. You can think of it as the return value in a function, such as the value returned by the following C++ function int Foo() { return 42; }.

AttributeRequirementsDescriptionExample
NameRequiredThe name will be used as the data output slot’s nameName="Return Value"
TypeRequiredThis is the C++ type of the property. It must be a type that’s exposed to the O3DE serialization context. If the type contains special characters, you must use the HTML Entity Codes (for example, update AZStd::vector<int> to AZStd::vector&lt;int&gt;).Type="float"
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"
DefaultValueOptionalAllows you to provide the default value for the propertyDefaultValue="1000.0"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"

Examples

<Input Name="Fibonacci" OutputName="Done">
    <Parameter Name="X" Type="int" Description="The value to calculate Fibonacci for"/>
    <Return Name="Result" Type="int"/>
</Input>

Branch

AttributeRequirementsDescriptionExample
NameRequiredSpecifies the name of the branch, in C++ this will create a function with the name Call<BranchName> where <BranchName> is the specified name.

Examples

The following example creates a node that will return Success and an Entity Spawn Ticket or return Failed

<Input Name="Create Ticket" OutputName="Ticket Created">
    <Parameter Name="Prefab" Type="const AzFramework::Scripts::SpawnableScriptAssetRef&amp;" Description="Prefab source asset to spawn"/>
	<Branch Name="Success">
        <Return Name="Entity Spawn Ticket" Type="AzFramework::EntitySpawnTicket"/>
    </Branch>
    <Branch Name="Failed"/>
</Input>

The node definition above will generate corresponding calls for each C++ branch in the same way it generates C++ functions for outputs. In this example it will generate CallSuccess and CallFailed, you can call these functions from within your node’s C++ implementation.

void CreateSpawnTicketNodeable::CreateTicket(const AzFramework::Scripts::SpawnableScriptAssetRef& prefab)
{
    auto ticket = m_spawnableScriptMediator.CreateSpawnTicket(prefab);
    if (ticket.IsSuccess())
    {
        CallSuccess(ticket.GetValue());
    }
    else
    {
        AZLOG_ERROR("Unable to Create Spawn Ticket - A valid prefab was not provided");
        CallFailed();
    }
}

Free function elements

Script Canvas Free Function Nodes expose C++ functions directly into the Behavior Context. This provides a quick and easy way to create libraries of functions that are available for use in Script Canvas.

Use the following elements when defining Free Function Nodes:

Function

AttributeRequirementsDescriptionExample
NameRequiredThe name of the functionName="RandomColor"
BranchOptionalSpecifies that the function be used to evaluate the branching conditionBranch="IsValidFindPosition"
BranchWithValueOptionalBranchWithValue="True"

Note: functions can use the Parameter element to specify data inputs.

<Function Name="RandomColor">
    <Parameter Name="MinValue" DefaultValue="Data::ColorType(0.0f, 0.0f, 0.0f, 1.0f)"/>
    <Parameter Name="MaxValue" DefaultValue="Data::ColorType(1.0f, 1.0f, 1.0f, 1.0f)"/>
</Function>

<Function Name="IsValidFindPosition"> <!-- Used by ContainsString to evaluate the condition to branch -->
    <Parameter Name="Position" Description="The string find position to check against"/>
</Function>

<Function Name="ContainsString" Branch="IsValidFindPosition" BranchWithValue="True">
    <Parameter Name="Source" Description="The string to search in."/>
    <Parameter Name="Pattern" Description="The substring to search for."/>
    <Parameter Name="Search From End" Description="Start the match checking from the end of a string."/>
    <Parameter Name="Case Sensitive" Description="Take into account the case of the string when searching."/>
</Function>

Out

Functions can use the Out element to specify the name for each of the Branch results.

NOTE: There may only be 2 Out elements for branching functions, if more than 2 exist an error will be displayed during compilation.

AttributeRequirementsDescriptionExample
NameRequiredThe name of the function<Function Name="Clamp">
<Function Name="BranchExample" Branch="IsPositive" BranchWithValue="True">
    <Out Name="Is Positive"/>
    <Out Name="Is Negative"/>
</Function>

Library

Create a collection of functions using the Library element.

AttributeRequirementsDescriptionExample
IncludeRequiredThe relative path to the C++ include file that will contain the library function declarationsInclude="Include/ScriptCanvas/Libraries/Math/Color.h"
NamespaceRequiredThe namespace that holds the C++ functions in this libraryNamespace="ScriptCanvas::ColorFunctions"
CategoryRecommendedCategory defines where this node will appear in the Node Palette. You can nest categories by separating with the / character.Category="Math/Color"
<Library Include="Include/ScriptCanvas/Libraries/Math/MathFunctions.h"
        Namespace="ScriptCanvas::MathRandoms"
        Category="Math/Random">

    <!-- Function Definitions -->

</Library>

Grammar

Grammar nodes are nodes that have a direct translation into the backend’s execution format, which is Lua. You do not need to create new grammar nodes if the Script Canvas Nodeable format is sufficient. However, in some situations it might be desirable to extend the Script Canvas grammar.

There are many shared elements and attributes between the grammar nodes and the node definitions. This section will cover the differences.

In

Specifies an execution entry slot

AttributeRequirementsDescriptionExample
NameRequiredThe name of the execution slot<In Name="Start">
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"

Out

Specifies an execution exit slot

AttributeRequirementsDescriptionExample
NameRequiredThe name of the execution slot<Out Name="Done">
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"

OutLatent

Specifies a latent execution exit slot, a latent slot may execute several frames or ticks from the moment the node is invoked

AttributeRequirementsDescriptionExample
NameRequiredThe name of the execution slot<OutLatent Name="TimerDone">
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The specified time interval is complete"

SerializedProperty

A C++ member variable that needs to be serialized

AttributeRequirementsDescriptionExample
NameRequiredThe name of the execution slot<SerializedProperty Name="m_numericPrecision"/>

EditProperty

Allows providing EditContext attributes to an existing Property or SerializedProperty

AttributeRequirementsDescriptionExample
NameRequiredThe name to replace the field’s name, cosmetic only<SerializedProperty Name="m_numericPrecision"/>
FieldNameRequiredThe name of the Property or SerializedPropertyFieldName="m_numericPrecision"
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"
UIHandlerOptionalAllows the user to override the property’s default UI Handler in the Node InspectorUIHandler="AZ::Edit::UIHandlers::ComboBox"
DisplayGroupOptionalAllows slots to be grouped visuallyDisplayGroup="Tests"
<EditProperty UiHandler="AZ::Edit::UIHandlers::Default" FieldName="m_numericPrecision" Name="Precision" Description="The precision with which to print any numeric values.">
    <EditAttribute Key="AZ::Edit::Attributes::Min" Value="0"/>
    <EditAttribute Key="AZ::Edit::Attributes::Max" Value="24"/>
</EditProperty>

EditAttribute

EditProperty may also use EditAttribute data.

DynamicDataSlot

A Dynamic Data Slot is a slot that does not have a predefined type; the type is acquired by the slot when a connection is made or when a variable reference is created. The type of the slot may be a value, a container, or a general purpose slot that supports ‘Any’ type.

AttributeRequirementsDescriptionExample
NameRequiredThe name of the data slotName="Format"
DescriptionOptionalDisplayed as a tooltip when hovering over the slotDescription="The radius of the circle"
ConnectionTypeRequiredScriptCanvas::ConnectionType::Input or ScriptCanvas::ConnectionType::OutputConnectionType="ScriptCanvas::ConnectionType::Input"
DynamicTypeRequiredValue, Container, or AnyDynamicType="ScriptCanvas::DynamicDataType::Container"
<DynamicDataSlot Name="Source"
                 Description="The container to get the size of."
                 ConnectionType="ScriptCanvas::ConnectionType::Input"
                 DynamicType="ScriptCanvas::DynamicDataType::Container" />