Facepunch.ActionJigs 0.1.1

Facepunch.ActionJigs

Runtime-composable async methods that can be converted to and from JSON.

Overview

An ActionJig is made out of nodes, links and variables. Nodes either perform actions or evaluate expressions, and links connect them together to shuttle values or signals around. Variables provide storage local to each invocation of the jig, and are used to capture values at specific points during invocation.

Node

Nodes have a definition and a binding. Bindings specify which properties, inputs, and outputs a node has. Inputs and outputs may transmit values or signals. A node with signal inputs / outputs is an Action node, which is invoked when an input signal fires. Nodes without any signal inputs / outputs are Expression nodes, which are lazily evaluated when any of their output values are requested by an Action node.

Definition

A node definition describes what the node will do, and controls which properties, inputs, and outputs a node will have.

A NodeLibrary is a collection of node definitions, and each ActionJig will reference exactly one such library. Each definition in a library has a unique internal name like op.add or math.max.

Binding

Definitions provide bindings, which are specifically typed sets of properties, inputs, and outputs. Depending on the definition, the binding of a node may change as you connect inputs or assign properties. For example, the type of the result output of an op.add addition node depends on the types of the provided inputs.

Property

Properties are constant named values stored in a node, which control its binding. For example: a var.set node, which would set a variable when invoked, has a property specifying which variable it will assign. Changing that property will change the input value type of the node, to match the variable type.

Input

A node input will either receive a signal or a value.

Input values can be provided by another node's output through a Link, or a constant value stored inside the input. Input signals can only be provided by an output signal from another node, and control when the receiving node executes.

If an input value accepts an array type, it may be linked to multiple outputs in a specific order to provide the individual items of an array. Otherwise, inputs link to at most one output.

Output

A node output will emit either a signal or a value.

Output signals may fire mutliple times per invocation of the node, for example the body output of the loop node control.foreach will fire once per element in the items input value. If multiple input signals are connected to the same output signal, the receiving nodes will act as independent concurrent tasks.

Output values of Action nodes may be provided by a specific output signal, and can only be used downstream of that output signal.

Output values of expression nodes are always available, and will be evaluated lazily when requested by an Action node.

Link

Links are the connections between an output and an input. An output signal can only connect to input signals, and an output value can only connect to input values. See Input and Output for more details.

Variable

Variables are provided as a way to capture values at specific points to be read later on.

Each variable has a specific name and type. They are referenced in var.set and var.get nodes, and must be set before they can be read. They are local to each invocation of an ActionJig, so if multiple instances of the same jig are running simultaneously they won't share variables.

User Data

Each main element of an ActionJig has a UserData property, which can store arbitary named values serialized as JSON nodes. This could be used to record each node's position in a visual editor, for example.

Validation

Each time an ActionJig is modified, elements will be marked as needing validation. This validation is performed either when attempting to invoke the ActionJig, or when accessing the Messages property. This property will be populated with a list of information, warnings and errors, each describing the context and cause. Any error messages will mean the ActionJig can't be invoked.

You can also access the messages specific to a particular node / link / property / input / output / variable by using the element.GetMessages() extension method. Accessing this will also cause validation to occur, if any elements have changed since the last validation.