Patches
Patches let you build logic from nodes and wires instead of typing code. Use one when an event is not enough.
A patch sits between events and scripts:
- Events are simple, but they cannot keep a value or do maths.
- Scripts can do anything, but you have to write code.
Try a patch the first time you want "…but only if the score is above ten" or "…move it a bit further each time".
A patch runs as fast as code written by hand. You can see it as code at any time in the Code panel. It is also the quickest way to check that a graph does what you meant.
Every node and its ports are in the patch node reference: 203 nodes in 24 categories.
Build a patch
- Open the Patch editor from the left rail. It shows the scene's graph.
- Click + Add node and pick a node from the Events group. This is where the graph starts.
- Add a node that does something, for example one that changes a component.
- Drag a wire from the event node's pulse output to the other node's pulse input.
- Open the Code panel to check your graph as code.
Kinds of node
| Kind | How to spot it | What it does |
|---|---|---|
| Event | only outputs, one of them a pulse | starts the graph: on launch, on tap, every frame |
| Effect | a pulse in and a pulse out | does something, in order |
| Control | splits or repeats the pulse | branch, gate, repeat, for-each, once, delay |
| Data | no pulses at all | gives a value: a number, a sum, a component's field |
The pulse wire sets the order in which things happen. Follow it from an event node to read the sequence. Data wires only carry values. They have no order.
Ports and wires
Each port has a type: number, boolean, string, vector, colour or object. Ports of different types do not connect. This catches many mistakes before you run anything.
A vector port opens into x, y and z. You can wire one of them and type the other two.
An input with no wire uses the value you typed into the node. So wire only the parts that change.
Choose which object a node uses
Component nodes, such as "get transform" or "set material", need to know which object to use.
- Leave the object empty, and the node uses this object: the one the patch is attached to.
- Set an object, and the node works on that object instead.
Two things make this easier:
- Get nodes do not break. Reading a component the object does not have gives you nothing, and the graph keeps working.
- Set nodes change only what you filled in. Everything else stays as it was.
This matches everything else you see in the editor. Scripts use radians, so convert when you pass rotation between a patch and a script.
What is in the node menu
| Group | What you will find |
|---|---|
| Events | 30 starting points: launch, frame, tap, keys, collisions, tracking |
| Components | read and change any component |
| Math, Vectors, Logic, Strings | maths, comparisons, vectors and text |
| Flow | branch, gate, repeat, for-each, once, delay, sequence |
| State | counter, toggle, timer, smooth |
| Entities, Lifecycle | find, create, spawn and destroy objects |
| Physics | impulses, forces, velocity, raycast |
| Multiplayer | send, receive, shared state, spawn |
| Globals, Variables, Messaging | values shared with other patches and scripts |
| UI | read and change an interface card's variables |
| Functions | call another patch or a script |
Reuse a patch
Keep a graph as a patch in your project assets, and you can drop it onto other canvases. What you get depends on how you built it:
| You built | You get |
|---|---|
| no input or output nodes | a behaviour: drop it in and it runs, no wires needed |
| inputs, outputs and a pulse input | a step: it runs when the pulse arrives, then its outputs are ready |
| inputs and outputs, but no pulse | a function: its outputs are worked out wherever they are read |
The patch's sockets come from the input and output nodes inside it. Add one, and it appears everywhere the patch is used. When you edit the patch, everything that uses it updates right away.
Inside a function there is no "this object", so object and component nodes do not work there. Use functions for data, maths and logic. Do the scene work in the patch that calls it.
Patches can also call scripts. This is the usual way to do something no node covers.
Keep values between runs
There are three ways to keep a value. They differ in who can see it:
| Node group | Shared with |
|---|---|
| Variables | the nodes of this one patch |
| Globals | every patch, script and event in the project |
| Messaging | anyone listening, as a one-time notice sent by name |
Globals come in two kinds:
- project globals keep their value when the visitor moves between spaces;
- space globals start fresh in each space.
You type the names of variables, globals and messages instead of wiring them.
Write a line of JavaScript
Two nodes take JavaScript directly:
- Expression (
expression) returns a value. - Action (
action) runs statements.
Inside them, you can use everything a script can.
Use them for one small thing that no node covers. If you find yourself writing a lot of code in them, write a script instead and call it from the graph.
When something goes wrong
Open the Code panel. If something in the graph is wrong, the problem shows there. Two common causes are a loop in the data wires and broken JavaScript in an Action node.
A broken patch does not stop the scene. Your other patches keep running.
Next: Game controls — let people walk around.