There is more information in the Sandbox Manual on how to use the Flow Graph Editor.
It's also possible to add Flowgraph functionality to any Lua entity by Adding Lua Flownode Inputs and Outputs.
This article describes the steps to implement a new flow graph node.
It is recommended to implement flow nodes that belong to the same group in a single cpp files. Usually there is no need for a header except for some special nodes.
Place the cpp file in the project file in
CryAction/Flow System Files/Nodes and within the file system directory structure in
In the cpp file, add a class using the following code template and replace "MyName" with the desired name of your flow node. Replace "FlowNodeGroup" with your desired group name and create a corresponding sub-folder in the editor node selector where this node type will be placed.
eNCT_Instanced vs eNCT_Singleton
When you declare a FlowNode in code you can choose between Instanced and Singleton in the template parameter of the parent.
If you have a singleton node, it will only create 1 instance of it. you can still have multiple nodes in your Flowgraph, but the memory footprint will be much smaller.
As a general rule of thumb, use singleton whenever you are not keeping any state data (member variables etc.) and prefer singleton over instanced.
Adding Output Ports
Flow nodes have both input and output ports. An output port can be added by altering the GetConfiguration function, as can be seen in the following example:
OutputPortConfig is a templatized helper function that is useful for filling a small structure with appropriate data.
Various types can be specified but in the sample the type of the port is "int". The available types are: SFlowSystemVoid, int, float, EntityId, Vec3, string, and bool. SFlowSystemVoid is a special type which represents "no value". OutputPortConfig takes three parameters: the name of the output port, some descriptive help text that is shown in the editor GUI and an optional human readable port name which is visible to designers. Make sure that you choose a good port name as changing it later will break all flow graphs that use this node. If you need to change the displayed name, use the third parameter.
To emit a value from the port, you can use the function CFlowBaseNode::ActivateOutput( pActInfo, nPort, value ). This function takes a pActInfo (typically passed to ProcessEvent()), the port identifier (count starting a zero from the top of out_config), and a value of the same type as the port. So to activate our output "alertness" with 3 we could write:
Adding Input Ports
An input port can be added in a similar way as an output port by altering the GetConfiguration function:
InputPortConfig is a templatized helper function similar to OutputPortConfig. The same types as for output ports can be specified for the input ports as well.
InputPortConfig takes the following parameters:
- name [required] - used internally and for saving the graph. It is again recommended to choose the port name carefully as changing it later will break flow graphs using this node. Important: Do not use the underscore character '_' in port names as this was used in previous versions to specify a specialized editor for the port,
- value - default value of the port when a new node is created,
- description - for the tooltip on mouse hover,
- humanName - human readable name for display on the node. Use this to visually override a port name without breaking script compatibility,
- sUIConfig - a formatted string specifying how the UI should behave when setting the port value. Here you can choose a specialized widget or tune the allowed range of the input. See 'UI Configuration' for more details.
The interface for setting the Input Port value can be defined by passing a series of options in the form of a string with key-value pairs in the InputPortConfig.
- Setting the value range:
This will limit the widget's arrows and ramp as well as clamp manually inserted values as seen in the picture.
- Enum dropdown:
There are several types of enums that can be used to display a dropdown list of readable strings which map to a value that is actually used by the node (and persisted when the graph is saved). Enums can be of type int or float as in the example above and shown in the picture.
An enum can also be of type string with or without mapping to another value:
Enums can also refer to the Global and dynamic UI Enums defined in InitUIEnums. For instance, 'vehicleLightTypes' is read from Scripts/Entities/Vehicles/Lights/DefaultVehicleLights.xml . Optionally the enum can depend on another port to affect the available selection:
- Specialized Editor
A dedicated property editor can be indicated with the keyword 'dt', followed by parameters optionally needed by the editor as can be seen in the example above.
There is a set of available editors which name can be consulted in the table below. The following picture illustrates the color picker.
Full engine licensees can add new editors. For that, see the file Sandbox/Editor/HyperGraph/FlowGraphVariables.cpp.
Note: previously the editor names were passed as a prefix to the port name, however this is not recommended because changes to the port name will break compatibility with saved graphs.
Property Editor Type
Sometimes it is useful to have a trigger signal as input or output port. Such ports should be implemented using the type In/OutputPortConfig_Void or In/OutputPortConfig_AnyType and not bool.
Sometimes you want to have an update loop for your node instead of just reacting on ports, below is explained how to do this. You can also only temporarily enable the update event.
The following code will add your node to the list of regularly updated nodes:
This means from now on you will get ProcessEvent calls with eFE_Update event.
To be removed again from this list call the same function with false as the second parameter.
Frequency: you will get 1 ProcessEvent(eFE_Updated) call per Game update call.