When should Flow Variables be used in Unity Visual Scripting?

Question

There are six types of variables in Unity's visual scripting. I'm not 100% clear on the difference between Graph and Flow Variables.

Here's the most extensive description of them that I've seen:

https://docs.unity3d.com/Packages/[email protected]/manual/vs-variables.html

Currently I use Object Variables if:

• The data in them is tied to a specific Object
• I need the data to be persistent, so I can access it later.

I use Graph Variables if:

• I don't need the variable's data to persist.

I use Flow variables if I say have a loop, and need to increment some numbers in the loop.

I'd like to use Flow variables as often as possible, as I assume they have a lower memory footprint (perhaps not true?). The way I think about it is: a Graph Variable are local to a graph, and a Flow variable is local to a smaller subsection of the graph (as defined in the screenshot). Is that the correct way to think about Flow variables?

Answer 1

In general, the lifetime of Flow variables is an execution process of UVS, or within the runtime of an event trigger.

I think to understand this, the most important thing is to understand what Flow is. UVS is not open source, we can't know its specific implementation, but we can guess some.

In Bolt.Flow.Runtime.dll we can find:

namespace Bolt
{
    public sealed class Flow : IPoolable, IDisposable
    {
        ...
        public readonly VariableDeclarations variables;
        ...
        public MonoBehaviour coroutineRunner { get; }
        ...
        public GraphStack stack { get; }
        ...
    }
}

In Bolt.Core.Runtime.dll we can find:

namespace Bolt
{
    public class Variables : LudiqBehaviour, IAotStubbable
    {
        public static VariableDeclarations Saved { get; }
        public static VariableDeclarations Application { get; }
        public static VariableDeclarations ActiveScene { get; }
        public static VariableDeclarations Graph(GraphPointer pointer);
        public static VariableDeclarations GraphInstance(GraphPointer pointer);
        public static VariableDeclarations Object(Component component);
        public static VariableDeclarations Object(GameObject go);
        public static VariableDeclarations Scene(GameObject go);
        public static VariableDeclarations Scene(Scene? scene);
        public static VariableDeclarations Scene(Component component);
        ...
    }
}

So Variables is a static utility class for UVS to get/set all types of variables. With other APIs and documentation, we can roughly guess the structure of the UVS runtime.

The USV runtime is essentially an interpreter for blueprints that relies on the Unity lifecycle. The Script Machine mounted on a Gameobject is responsible for monitoring Unity and user-defined messages and starting a new Flow run. Flow starts execution from the entry node that receives the event, finds all required parameters, executes the node itself, and proceeds to the next node. If another Gragh is called during the process, it is pushed onto the GraghStack to preserve the context, and returns to the original gragh after execution. If there are no subsequent nodes to execute, this time the Flow ends. It all happens within one frame.

An event triggers the Graph to run until the operation is completed, this is the lifetime of a Flow, and it is also the lifetime of the Flow variable. So in general, it's roughly equivalent to "temp variables".

BTW, I personally do not recommend using Graph Variables, I didn't find the VariableDeclarations structure in Graph. In fact, in practice I found that Graph Variables do not follow the Graph instance, but its assets file. After unity exits running, the variables generated will be saved in the file. This is very counter-intuitive and can lead to unexpected bugs.

I don't know if they fixed the bug, or I don't know if it's a bug at all. I choose not to use it anyway :)