Implement node options

Customize node behavior and structure with configurable options.

Use node options to dynamically customize node behavior and structure without creating multiple node variants. Configure the node option settings to use a single node type in different scenarios. For example, you can use node options to dynamically adjust both the number of ports and their data types. With node options, you can simplify the node hierarchy while maintaining flexibility.

This page covers how to implement node options only. For information on how to implement nodes, refer to Implement nodes for your graph tool. For information about node types, refer to About nodes.

Prerequisites

1. Set up the code structure.
2. Implement a graph tool.
3. Implement nodes for your graph tool.

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 the port count option.

2. Override OnDefineOptions to create the option with a default value.

3. Call Delayed() to defer processing until the input is complete.

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

4. Implement OnDefinePorts to create ports based on the option value as follows:

   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 the option using its name, and then TryGetValue extracts its current value. The node can dynamically adjust its structure based on user configuration.

Open the graph and instantiate the node to check the result.

Add a node option to change port types of a node

To create a node with switchable port data types:

1. Define an enum for your type options.

2. To create an option that uses this enum as its type, override OnDefineOptions.

3. To determine port data types in your OnDefinePorts implementation, use the selected enum value.

   Note: There’s no need to call Delayed() because the port needs to change as soon as the 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();
       }
   }
   

4. Go back to the graph, and use the two new options to change the layout of the node.

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();
        }
    }
}

Additional resources

• Node Option API Reference