Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

<div lang="en" dir="ltr" class="mw-content-ltr">
'''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 [https://en.wikipedia.org/wiki/Imperative_programming imperative programming].
</div>

== <span lang="en" dir="ltr" class="mw-content-ltr">Overview</span> ==

<div lang="en" dir="ltr" class="mw-content-ltr">
In ProtoFlux's [[ExecutionContext]] and its derivatives, nodes that perform a discrete action require an impulse to execute. For example, [[ProtoFlux:Duplicate Slot|duplicating a slot]] can't trigger whenever it wants--it would be impossible to control such a thing. As such, a special input <code>*</code> of type ''Call'' is used to trigger the action. This chain can then be continued via the <code>Next</code> output.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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, [[ProtoFlux:Write|writing]] to a non-driven [[Type:SyncField`1|synced field]], managing [[slots]], and setting non-driven [[dynamic variables]].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Impulses can come from a variety of sources. Most commonly, when building ProtoFlux, a [[ProtoFlux:Call Input|Call Input]] can be created by dragging out an impulse input and pressing [[Basic Controls|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|dynamic impulses]], [[ProtoFlux:Button Events|button events]], [[ProtoFlux:Fire On True|''fire on'' events]], and [[:Category:ProtoFlux:Flow:Events|world/item events]].
</div>

== <span lang="en" dir="ltr" class="mw-content-ltr">Context</span> ==

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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 [[ProtoFlux:Local|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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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 <code>Next</code> 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 <em>will</em> be seen by the initial <code>Next</code> path.
</div>

== <span lang="en" dir="ltr" class="mw-content-ltr">Impulse flow</span> ==

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
A non-[[#Async|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.
</div>

=== <span lang="en" dir="ltr" class="mw-content-ltr">Async</span> ===

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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 [https://en.wikipedia.org/wiki/Coroutine coroutines] within the language. One can either explicitly suspend execution with nodes such as [[ProtoFlux:Delay|Delay]], or one can implicitly wait for an action to complete before resuming execution, such as using the [[ProtoFlux:Play One Shot And Wait|Play One Shot And Wait]] node.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
An async impulse flow is able to preserve locals and action node outputs across multiple engine updates, something not possible with normal impulse flow.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
It is possible to start an async impulse chain from a normal impulse chain using the [[ProtoFlux:Start Async Task|Start Async Task]] node. This node actually creates a <em>branched</em> ExecutionContext at <code>OnTriggered</code> 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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
In contrast, all the other async nodes <em>share</em> the same context. For example, a local variable modified within the <code>OnTriggered</code> chain of a [[ProtoFlux:Delay|Delay]] node <em>will</em> be reflected in the <code>Next</code> 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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

== <span lang="en" dir="ltr" class="mw-content-ltr">See Also</span> ==

* <span lang="en" dir="ltr" class="mw-content-ltr">[[ProtoFlux:Local]], [[ProtoFlux:Store]], and [[ProtoFlux:Data Model Store]] for the three types of variables one can access in ProtoFlux.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">[[:Category:ProtoFlux:Flow]] for nodes that can control how an impulse flows.</span>

[[Category:Core concepts]]