Implement node options

Node options provide a way to dynamically customize node behavior and structure without creating multiple node variants. They allow a single node type to adapt to different scenarios through configurable settings, simplifying your node hierarchy while maintaining flexibility.

This documentation shows how to use node options to dynamically adjust both the number of ports and their data types.

Add a node option to change the number of ports of a node

To create a node with a configurable number of ports:

1. Define a constant name for your port count option.
2. Override OnDefineOptions to create the option with a default value.
3. Apply the DelayedAttribute to defer processing until input is complete.

Note

Right now Graph Toolkit only supports the DelayedAttribute on node option but the support for more attributes (e.g MultilineAttribute) is coming.

const string k_PortCountName = "PortCount";

protected override void OnDefineOptions(IOptionDefinitionContext context)
{
    context.AddOption<int>(k_PortCountName)
        .WithDisplayName("Port Count")
        .WithDefaultValue(2)
        .Delayed();
}

Finally, implement OnDefinePorts to create ports based on the option value:

protected override void OnDefinePorts(IPortDefinitionContext context)
{
    var portCountOption = GetNodeOptionByName(k_PortCountName);
    portCountOption.TryGetValue<int>(out var portCount);
    for (var i = 0; i < portCount; i++)
    {
        context.AddInputPort<Vector2>($"{i}").Build();
    }

    context.AddOutputPort<Vector2>("result").Build();
}

The GetNodeOptionByName method retrieves your option using its name, then TryGetValue extracts its current value. This pattern allows your node to dynamically adjust its structure based on user configuration.

Now open your graph and instantiate your node to check the result. The node look similar to the following:

Add a node option to change the type of ports of a node

To create a node with switchable port data types:

1. Define an enum for your type options.
2. Create an option that uses this enum as its type.
3. Use the selected enum value to determine port data types.

Note

This time there's no DelayedAttribute as the port needs to change as soon as port type option changes.

enum PortTypes
{
    Vec2,
    Vec3
}

const string k_PortTypeName = "PortType";

protected override void OnDefineOptions(IOptionDefinitionContext context)
{
    context.AddOption<PortTypes>(k_PortTypeName).WithDisplayName("Port Type");
}

protected override void OnDefinePorts(IPortDefinitionContext context)
{
    var portTypeOption = GetNodeOptionByName(k_PortTypeName);
    portTypeOption.TryGetValue<PortTypes>(out var portType);

    if (portType == PortTypes.Vec3)
    {
        context.AddOutputPort<Vector3>("result").Build();
    }
    else
    {
        context.AddOutputPort<Vector2>("result").Build();
    }
}

Go back to the graph and use your two new options to change the layout of your node. Your node now look similar to the following:

Complete node option example

[Serializable]
public class NodeWithOptions : Node
{
    enum PortTypes
    {
        Vec2,
        Vec3
    }

    const string k_PortCountName = "PortCount";
    const string k_PortTypeName = "PortType";

    protected override void OnDefineOptions(IOptionDefinitionContext context)
    {
        context.AddOption<int>(k_PortCountName)
            .WithDisplayName("Port Count")
            .WithDefaultValue(2)
            .Delayed();
        context.AddOption<PortTypes>(k_PortTypeName);
    }

    protected override void OnDefinePorts(IPortDefinitionContext context)
    {
        var portCountOption = GetNodeOptionByName(k_PortCountName);
        portCountOption.TryGetValue<int>(out var portCount);
        for (var i = 0; i < portCount; i++)
        {
            context.AddInputPort<Vector2>($"{i}").Build();
        }

        var portTypeOption = GetNodeOptionByName(k_PortTypeName);
        portTypeOption.TryGetValue<PortTypes>(out var portType);

        if (portType == PortTypes.Vec3)
        {
            context.AddOutputPort<Vector3>("result").Build();
        }
        else
        {
            context.AddOutputPort<Vector2>("result").Build();
        }
    }
}