Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Implement node options

Customize node behavior and structure with configurable options.
Read time 3 minutesLast updated 25 days ago
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. Implement a graph tool.
  2. 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