Document the `sequenced` property of `VisualScriptFunction`

[follower]

Context

While researching an answer for a Reddit /r/godot question about the Sequenced property of VisualScriptFunction I actually figured out how it works, so thought I'd document it here so it can eventually be added to the official docs--as it's not at all obvious. :D (I think in part due to a bug/missing functionality.)

Example

Example use (click to enlarge):

Configuration:

• functionA has Sequenced set to true i.e. "On"/checked/ticked.
• functionB has Sequenced set to false i.e. "Off"/not-checked/not-ticked

With this configuration the nodes representing the function calls (created by dragging the function name from the "Functions" list onto the graph) can be seen to have different appearances i.e. the call of functionB() does not have any white input or output "Sequence Ports" while the call to functionA() does have an input and an output Sequence Port.

What this means is that functionB() is used as a "getter" where it can be connected directly to an input "Data Port" of another node but functionA() must be called as part of an execution "sequence" in order to have the return value set and able to be supplied to an input data port of another node.

If the call to functionA() is not connected as part of a sequence then an error is generated by the Add node:

Add: Invalid arguments A: Nil B int

Related bug?

However currently there is a bug that makes discovering all this extremely difficult (especially if one is playing with Visual Script for pretty much the first time as I was while researching this :D ), if the "Sequenced" property of the VisualScriptFunction node is modified, existing call nodes in the Visual Script are not modified nor do they have their appearance redrawn.

This can be seen here where the two functionA() calls have different appearances (the lower functionA() node was created after "Sequenced" was unchecked) (click to enlarge):

Related documentation

I noticed that the existing Visual Scripting node documentation about the Local Variable nodes does mention:

As it can be seen above, there are two nodes available: A simple getter, and a sequenced getter (setting requires a sequence port).

Where to document

In terms of low level/class documentation, here:

• https://docs.godotengine.org/en/stable/classes/class_visualscriptfunction.html

It's not entirely clear where this functionality/setting would be best documented at a higher level, the primary options seem to be:

• In (or after) the "Creating a function manually" section.

• In the (non-existant?) section mentioned as "More on that will be explained later in this document" in the same section.

• In a part of this page related to Functions and/or calling.

Potential wording

The exact wording to be used (particularly for the higher level documentation) depends on a couple of aspects:

• How do the behaviour of these differ:

  • A "sequenced getter".
  • A sequenced function that takes no arguments.
  • A "non-sequenced getter" that returns a constant value.
  • A "non-sequenced getter" that returns a non-constant value.

• Is there an issue with the manner in which the "non-sequenced getter" functionality has been exposed that unnecessarily complicates its use/documentation?

  • e.g. If the output data port of a sequenced getter (a.k.a a function with no arguments) is attached to the input data port of a node, why is the sequence input not just executed directly?

(The mention of constant and non-constant values relate to a code comment that mentions "assumed constant if not sequenced" and I've not confirmed if this means the value is cached or in some other way treated differently.)

Possible VisualScriptFunction Class reference Property documentation wording [zeroeth draft :)] :

• sequenced -- When true, the output data port can be directly connected to the input data port of another node without this node being part of execution sequence. i.e. The function acts as a "getter".

Possible higher level documentation wording [zeroeth draft]:

You can create your own "getter" function by unchecking the Sequenced property of the VisualScriptFunction in the Inspector. This means you can use the function without needing to make it part of an execution sequence.

Related links

• Commit where functionality was added: https://github.com/godotengine/godot/commit/8a4bce6ebd843f9a8f482f74601f4933aae737a3

• Issue marked as "Fixed" by above commit: "It's impossible to create custom function without sequence port in VS godotengine/godot#6346 "

• Semi-related issue: https://github.com/godotengine/godot/pull/9758

• Const/constant-related commits/issues that might be relevant to understanding implementation:

  • "Fixed constness of variant functions, as well as visual script sequence ports. Closes godotengine/godot#11258"
  • "Add sequence ports to non-constant CallBasic VS nodes godotengine/godot#11258"
  • "Visual script Call/Set - Basic type does not have a flow node! godotengine/godot#10440".

• Related to output sequence ports discovered when I was thinking that sequenced/is_sequenced() were just an optimisation for avoiding calling get_output_sequence_port_count():

  • Example VisualScriptCustomNode GDScript implementation: vs_custom_nodes/2DIterator.gd (via https://github.com/godotengine/godot-visual-script/issues/46)

  • Documentation on how to implement a VisualScriptCustomNode in GDScript: https://github.com/swarnimarun/visual-scripting-node-library/pull/11/files?short_path=04c6e90#diff-04c6e90faac2675aa89e2176d2eec7d8 (Ideally this could be pulled into the official docs IMO.)

• Location of functionality implementation in Godot:

  • https://github.com/godotengine/godot/blob/b8577ecce1bb62a4a589d02bdd71b701e5bdea81/modules/visual_script/visual_script_nodes.cpp#L2924 (And all through this file.)

  • https://github.com/godotengine/godot/blob/62d656ea063f69d5b48adf60486433c37125b8be/modules/visual_script/visual_script_nodes.h#L797 (ditto)

• Documentation of ports_changed_notify which seems like it might used to modify/update display of node after sequenced property is toggled.

Edit: Added additional related links.