Impulses

Impulses, sometimes known as calls, are discrete actions within the ProtoFlux ExecutionContext and one of the two basic types of chains to build. In contrast to chains of inputs and outputs to a node, which are generally continuous to one another, impulses push a task execution along the impulse chain, much like conventional imperative programming.

Overview

In ProtoFlux's ExecutionContext and its derivatives, nodes that perform a discrete action require an impulse to execute. For example, duplicating a slot can't trigger whenever it wants--it would be impossible to control such a thing. As such, a special input * of type Call is used to trigger the action. This chain can then be continued via the Next output.

Upon an action node receiving an impulse, it evaluates all the non-impulse inputs connected to the node. This contextualizes the relationship between impulses and other node chains: Impulses push task execution, while action nodes pull their inputs, which may pull their inputs, and so on until the original input can be evaluated.

Impulses are a local runtime by default within ProtoFlux. If interacting with the FrooxEngine data model in any fashion, however, the actions they perform get synced across users. This includes, but is not limited to, writing to a non-driven synced field, managing slots, and setting non-driven dynamic variables.

Impulses can come from a variety of sources. Most commonly, when building ProtoFlux, a Call Input can be created by dragging out an impulse input and pressing secondary. Impulses may also come from events, or impulse chains that start once receiving some sort of signal. These include, but are not limited to, dynamic impulses, button events, fire on events, and world/item events.

Context

Impulses are attached to a particular instance of an ExecutionContext. This is not to be confused with the general concept of contexts in ProtoFlux, as all impulses are from an ExecutionContext, but rather refers to the specific values and variables that the impulse sees.

Context is picked up by the trigger of the original impulse and carried until the chain completes. Contexts carry certain values with them throughout the duration of the chain, including local values and outputs to action nodes. Outside of the specific context (and nested contexts) that they are used, it is impossible to access the underlying value of one of these context-sensitive values.

Context is kept when passing through the same node group and lost if there is a disconnect of execution to a different node group. Node groups are the nodes that are all connected in some way or another, whether through direct wire connections or by references to another node, such as referencing a variable for a write node.

For example, if a dynamic impulse is pulsed, and that dynamic impulse pulses another one, and that third dynamic impulse writes to a local, the change will not be seen by the Next path of the first dynamic impulse trigger. This is because the execution leaves the node group of the first trigger after the first dynamic impulse is pulsed, causing the second dynamic impulse to not be within the same context as the initial chain. If the second dynamic impulse wrote to the same local, then all the node groups are connected, and the change will be seen by the initial Next path.

Impulse flow

Impulse flow dictates how the impulse will be executed in relation to the runtime of the engine. There are two types of impulse flows: non-async and async.

A non-async impulse chain will run entirely in one engine update, halting the engine for as long as it takes to complete. If the impulse does actions that are synced across users, only the difference between the initial state the end of the engine update is synced. For example, if one duplicates and removes a load of slots in one non-async impulse chain, no data will be synced over the network.

Async

When an action has the potential to take multiple engine updates to complete, an async impulse flow is required. Otherwise, the node chain will raise an exception and refuse to execute.

Async impulse flow is generally the same as normal impulse flow, though with the added flexibility of being able to suspend and resume certain chains of execution at will. In essence, it is ProtoFlux's way of being able to use coroutines within the language. One can either explicitly suspend execution with nodes such as Delay, or one can implicitly wait for an action to complete before resuming execution, such as using the Play One Shot And Wait node.

An async impulse flow is able to preserve locals and action node outputs across multiple engine updates, something not possible with normal impulse flow.

It is possible to start an async impulse chain from a normal impulse chain using the Start Async Task node. This node actually creates a branched ExecutionContext at OnTriggered that is distinct from the context that triggered it. Every value used by the triggered ExecutionContext gets duplicated into the new context, but after that point, neither context is able to affect the other.

In contrast, all the other async nodes share the same context. For example, a local variable modified within the OnTriggered chain of a Delay node will be reflected in the Next chain of the same node, and vice versa if the node gets triggered twice in one context. This is what makes async impulse flow so powerful.

If processing a lot of data using ProtoFlux, it may be desirable to use async impulse flow and spread execution across multiple frames, as it will prevent a massive framerate hitch when executing at the cost of taking slightly longer.

See Also

• ProtoFlux:Local, ProtoFlux:Store, and ProtoFlux:Data Model Store for the three types of variables one can access in ProtoFlux.
• Category:ProtoFlux:Flow for nodes that can control how an impulse flows.