LogiX Overview
Background
LogiX is a dataflow programming language. This means that it is laid out as a graph, rather than as a long list of instructions.
Programs are laid out in physical space; you can use all three dimensions to organize your nodes and wires.
Basics
Operations, such as addition, are represented as nodes. Data (values, like numbers and text) flows between nodes on wires.
The LogiX to the right multiples and adds together some numbers. Note how data flows from source to destination. This is directed; data can't flow out of the left side of a node or flow into the right side of a node.
The connection points on the left side of a node are its inputs, and those on the right side are its outputs. You can tell what type of data each input wants or each output provides by looking at its color and texture -- you can consult the Variables > Storage section of your node browser to see a variety of common types and their corresponding looks.
Impulses
In addition to data, impulses can also flow from node to node. An impulse fires in response to something happening, like a timer going off or a button being pressed.
Impulses put things in order, and are always required for nodes that change the world. Nodes that take an impulse are called passthrough nodes. Values flowing out of passthrough nodes often only exist during the impulse, making them transient. For example, Duplicate Slot's Slot output is only valid during the impulse that caused the duplication.
Conversely, you will rarely see impulses used for nodes that just read values.
Impulses flow along impulse wires. An impulse output can only go to one place. An impulse input can receive many wires.
An impulse is always run by exactly one user.
The LogiX to the right writes the current time to a variable whenever the button is pressed.
Note how the value in the variable does not equal the current time! It will only change when an impulse occurs.
Impulse wires can be identified by their white and gray chevron pattern; impulse inputs and outputs are also shaped like chevrons.
Usage
To create or modify LogiX graphs, you need to have the LogiX Tooltip equipped. You can find it in your Inventory under the Essential Tools folder.
Creating
The LogiX Tooltip can spawn a node browser, which provides the majority of nodes you will need. It is organized into categories; see the LogiX page for a table explaining the various categories. Double-clicking is necessary both to navigate the nodes and to select one.
Your currently selected node will be displayed by your tooltip, along with the packing root (see below).
Double-clicking in the world after selecting a node will spawn it. To connect nodes, physically touch the input or output with your tooltip, then pull your primary input (probably your trigger). Release when hovering over a compatible input or output to create a wire.
To cut a wire, pull the trigger away from any existing wires or nodes and drag. A line will appear. Any wire touching the line when you release the trigger will be destroyed.
Grabbing a wire with your laser will create a relay. Relays let you reshape your wires, as well as connect multiple inputs to a single piece of data (or multiple impulse wires to a single impulse input).
For some types, like ints and strings, you can press secondary while dragging from an input to create a new input node, which will let you enter a value directly. For any type, you can press secondary while dragging from an output to create a new display node, which will show the current value.
You can always plug an output into an input of the same type. In other cases, the types may be compatible after a cast, which will be automatically created when you make the connections.
Some nodes have dummy inputs, which are bright purple. They will transform into the appropriate type when you connect something. This is known as overloading the node. Some nodes can have interesting behaviors when overloaded -- for example, the * node can multiply a string and an int to make many copies of the string.
Extracting
Your tooltip can "extract" fields and components in three different ways to let you observe and control the world:
- Extract Interface
- Press secondary whilst grabbing a slot or a component (or any of its fields) to create an interface card. The interface card provides outputs, which you can use to read values from the component. You can also drag outputs into the interface card to create a drive node.
- Extract Drive Node
- Press secondary whilst grabbing a value field to create a drive node. The drive node is an input, and will control the value of its field. Only one thing can drive a field at a time.
- Extract Ref Node
- Press secondary whilst grabbing a reference field to create a ref node. The ref node can be used as an output, to get a reference, or as an input, to give things like Write nodes a target.
Interfaces
Interface cards allow you to get values out of a slot or a component. They also allow you to control their contents, whether by writing a specific value or by taking control with a drive node.
You can pull wires out of an interface card just like you would from a node's outputs. Dragging wires into the interface will generate a drive node for that field.
You can have one (and only one) interface card for a single thing.
Drives
Drive nodes (also called "drive arrows") give you exclusive control of the field they are created from. The driven field will turn purple, and it will become impossible to manually set values.
Instead, the field will take its value from whatever it's connected to. Drive nodes spawn with an input node attached; if you cut the wire, then the drive node will automatically destroy itself.
You can have one (and only one) drive node for a single thing.
Refs
Ref nodes provide a reference to something. You may have noticed that the Slot output of a card does not form a direct connection when plugged into something like a Duplicate Slot node; instead, an arrow is created.
You can have many ref nodes for a single thing. Ref nodes provide an output containing the reference.
Packing
Once you've finished your LogiX, you'll want to pack it to hide it from view. Grab a reference to a slot in the same hand that has your tool (by grabbing a name in an Inspector window's hierarchy), open the context menu, and select Set Packing Root.
Then, hold the secondary input down while pointing at a LogiX node. Once the circle is full, let go. It, along with all connected nodes, will be packed under the slot.
Packing removes the visuals for nodes, but preserves their positions. They are parented to the packing root, and will thus move, rotate, and scale along with it.
You can unpack LogiX by grabbing a slot reference and selecting the Unpack option in your context menu. This restores all nodes beneath that slot.
If you have no packing root set, the tool will display "Pack-in-place". This packs nodes under the parent of the node that you targeted, and is useful if you're inspecting many different groups of LogiX nodes. If you accidentally pack nodes that were never packed before, they will probably be under the world root. You can unpack them all by grabbing one of the nodes and unpacking it -- the entire bundle of nodes will be unpacked all at once.
If your Traversal Mode is set to "Stop At Other Nodes", then only nodes directly connected to the target will be packed. Note that reference nodes are not a connection to their target. Conversely, in "Complete" mode, reference nodes are followed. This is useful to make sure that things like variable nodes are packed along with the nodes that write to them. However, this can cause major headaches -- consider what might happen if you have many distinct pieces of LogiX that all reference your avatar's root slot!
Reference Material
Controls
Primary
- Click and hold while the tip is physically touching an input or output to create a new wire; release to connect the wire
- Click and hold while the tip is not touching an input or output to start cutting; release to cut all wires along the cut line
- Double click to spawn a node
Secondary
- Hold until the circle fills and release to pack the targeted node
- Click to copy the targeted node into the tooltip
- Click while dragging a wire to create an input or display node
Grab
- Grab a wire to create a new relay
Glossary
Background
- Type
- The type of a piece of data describes what values it can have and what it means. Some common types are integers (whole numbers), floats (numbers with decimals), strings (text), and booleans (true/false)
- Data
- A piece of data is a value. 5, 5.3, true, and "hello world" are all data.
Basics
- Node
- A single unit of LogiX that performs some kind of operation, such as adding two numbers or sending an impulse every frame.
- Wire
- A connection between LogiX nodes. A wire can carry either data or an impulse.
- Relay
- A node that allows you to control the shape of wires; it is just an input tied directly to an output. You can also connect multiple data wires to the output of a relay, or multiple impulse wires to the input of an impulse relay.
- Input
- A piece of data that goes into the left side of a node. Only one wire may flow into a non-impulse input. Many impulse wires may flow into one impulse input.
- Output
- A piece of data that leaves the right side of a node. Many wires may flow out of a non-impulse output. Only one impulse wire may flow out of one impulse output.
- Impulse
- A single event that is run by a single user. Impulses flow through the LogiX graph. Impulses cannot be duplicated or split -- they will follow one path, and only one path. Some kinds of nodes can produce impulses, such as Raw Data Tooltip Events.
Specifics
- Passthrough Node
- A node that accepts an impulse. Every passthrough node, except for the Display Impulse node, will have at least one impulse output. These nodes can change the state of the world; see Write for an example.
- Transient
- A piece of data is transient if it only exists during an impulse. For example, On Collision Start's ICollider output only exists during the impulse triggered by the collision.
- Cast
- A node that is automatically created if your data isn't of the right type. Casts may lose precision (e.g. float-to-int loses the decimal and may be significantly wrong if the float is too big).
- Value
- A value type directly stores some data. Most of the types in the node picker, with the exception of User and Slot, are value types.
- Ref
- A ref type points to something else. User and Slot are common examples of ref types. They are often handled differently from value types, and are necessary if you want to modify something in the world.
- Slot
- Anything in the world. Slots can contain other slots.
- Component
- Something attached to a slot that adds functionality.
- Field
- A piece of data stored on a slot. A field can be referred to with a reference node, or read from with an interface card.
- Interface Card
- A LogiX node that allows you to read the fields from a slot or component, as well as generate drive nodes for the fields.
- Drive Node
- A node that controls a field. It directly replaces the field's value with something computed from other values, which means that each client can handle it locally. You cannot drive reference fields.
- Ref Node
- A node that contains a reference. You need ref nodes to give things like the Write node a target.
- Write
- To write is to set a value once. A write is shared over the network. Writing to a driven field does nothing (unless the driver is listening for writes, in which case it may have an effect).
- Drive
- To drive is to continuously control a value based on another value. Drives are handled by each user; nothing is shared over the network. Only one thing may drive a field at a time.
- Dummy
- A dummy node is one that can become a more specific node when given a type. For example, Write can write any value type, and will switch colors to match the one that is plugged into it.
- Overloading
- To overload a node is to give it a different type. The + node overloads to add ints, floats, shorts, and so forth. The Write node overloads to switch from its default dummy type to a specific value type.
Notes
Some known bugs related to LogiX:
- Grabbing the wire coming out of a cast node will destroy the cast and cause an exception, which unequips your tooltip.
- An interface card is generated for every player in the world. All but one of the cards will be non-functional. The "Clean Interfaces" tool is useful for cleaning this up.