Flowlab Technical Reference

The graph model

A graph is a set of nodes connected by links. Each node has input and output ports, and every port carries one of these value types: number, text, a list (of numbers, text, or anything), or any. A link connects one output port to one input port; an output may fan out to many inputs and an input may be fed by many outputs.

Triggers start evaluation on their own (Once, Timer, Collision); Mailboxes start it when a message arrives (section 6); all other nodes run only when a value arrives at an input. A bundle is a sub-graph inside a single node with its own ports. Bundles can contain bundles.

For what each node does, see the Behavior Handbook. For every node type's exact ports and fields, see the node appendix.

Values and conventions

• What a trigger sends. Trigger outputs carry the number 1 unless the Behavior Handbook says otherwise: Once, Always, Timer and Keyboard all send 1 (Keyboard set to any key sends the key as text instead; Mouse Move sends coordinates). To move an object by an amount, route the trigger through a Number: its get input emits the stored value; set stores the incoming number and emits nothing; + adds the incoming number to the stored value and emits the result.
• Axes. x increases to the right. y increases downward for positions and for Velocity. Impulse and Push Motor are the other way around: a positive y pushes up, negative pushes down.
• Units. Position works in pixels by default (its pixelUnits setting; grid cells of 32 pixels when off). Velocity, Impulse and Push Motor take engine units, not pixels: a velocity of 1 moves an object roughly 27 pixels per second. Impulse applies a one-time impulse; Push Motor applies a much smaller impulse each time it evaluates, which acts like a steady force when driven every frame. Both are divided by the object's mass.
• Keys. Keyboard's keyCode is the standard browser key code: Space 32, Enter 13, Esc 27, arrows 37 to 40 (left, up, right, down), letters 65 to 90 (A to Z), digits 48 to 57. A code of 0 means no key is set; -1 means any key.
• When triggers fire. Once fires on the first frame an instance exists: for placed objects, the first frame after the level loads; for spawned objects, when they appear. After a level restart it fires again for recreated objects, and for objects kept across the restart only when its reset-on-level-start setting is on. Always fires every frame. Keyboard fires the frame a key goes down (down) and the frame it is released (up). With repeats true it also fires down every frame the key is held, or every delay + 1 frames when delay is above 0 (delay is in logic frames and is ignored when repeats is false). Use repeats: true for movement that continues while a key is held; leave it false for a single action such as a jump. Timer fires after its delay, in tenths of a second (section 7).

The frame loop

The frame rate is a game setting: games created on the site default to 60, and games that predate the setting run at 30. Physics steps at the same rate as logic. The scene is redrawn once per logic tick; on a 60 Hz display with the game set to 30, every other display frame is skipped. Nodes act only on frame boundaries, so every duration is effectively rounded to whole frames.

One logic tick, in order:

• Objects destroyed during the previous frame are removed.
• Physics advances one step. Contacts recorded here become this frame's collision events.
• Results queued in earlier frames, such as a sound finishing, are delivered.
• The camera evaluates.
• Every object with behaviors evaluates: its triggers fire in order (section 3), and each trigger's downstream chain runs to completion (section 4). An object's attachments evaluate during the object's own evaluation.

While the game is paused, physics and behaviors are skipped. Objects whose behaviors are set to run while paused still evaluate, Mouse Click and Gesture triggers fire regardless, and queued asynchronous results (section 4) are still delivered.

Trigger evaluation order

Each frame, an object's trigger nodes fire one at a time, sorted by workspace position: the x coordinate is compared first, then y. Moving a trigger changes when it runs relative to the object's other triggers. This is the supported way to order work within a frame. If the object's type has a parent type, the parent's triggers all fire first, then the object's own, each set in its own position order.

Triggers inside a bundle sort by the bundle's own position first, so a bundle behaves as a block: everything in a bundle placed to the left runs before everything in a bundle placed to its right. Bundles created before the current bundle format still sort by each trigger's own position.

Mailboxes are not part of this pass. They fire when a message is sent (section 6). Position order applies to them only as a tie-breaker: if one object has several Mailboxes listening to the same message name, a delivery fires them in workspace position order.

Objects evaluate in the level's internal order, which changes as objects spawn and despawn. Do not build logic that depends on which object goes first; within a single object the trigger order above is guaranteed.

Signal flow

When a trigger fires an output, each linked node evaluates immediately, and its outputs continue downstream before control returns to the trigger. A chain runs as one call stack. When one output links to several inputs, all of them run before the trigger's next output fires. The engine currently runs them top to bottom by the position of the receiving input; do not depend on this.

Many component nodes are pass-through: after acting, they send a value on to a matching output, so chains like Timer → Velocity → Sound carry one value through several nodes. Velocity, Impulse and Push Motor forward the value they received; Position forwards the object's resulting position in pixels.

Two limits stop runaway graphs. Hitting the chain-depth limit, which catches loops, cuts off that branch and lets the rest of the frame continue; hitting the per-frame budget on total evaluations drops all remaining evaluations until the next frame. The first overrun after a level loads shows a warning popup, in the editor and in play alike; later overruns in the same level are silent. The game does not freeze.

Some outputs are asynchronous, such as a sound's done. These are queued and delivered at the start of a later frame's behavior pass, not in the frame that started them.

Per-entity state

Because a graph belongs to the type (section 1), a node like Timer or Toggle Switch keeps a state record per instance. The record is created when the instance first evaluates the node and discarded when the instance is destroyed.

What resets when:

• Destroying an object discards its per-instance state. A respawned object starts fresh.
• Loading a level during play resets most per-instance state (objects are recreated), but Global Variables keep their values across levels and across Restart Game. Global nodes from before that change (node version 1) still reset on every level load.
• Returning to the editor resets everything to the values set in the editor, including Globals. Save Value data is device storage and is not reset.
• Game Save snapshots the per-instance state of stateful nodes and restores it on load.

Object Variables are per instance; Global Variables are game-wide.

Messages

When a Message behavior fires, the engine finds every matching Mailbox on the target object and evaluates it immediately, inside the sender's evaluation chain. Control returns to the sender's graph only after the receiver's downstream nodes have finished. Consequences:

• A Mailbox's downstream logic runs in the same frame as the send.
• Ordering is depth-first: if a Mailbox's chain sends another message, that second delivery completes before the first sender continues.
• A Mailbox → Message loop is stopped by the chain-depth limit (section 4) instead of hanging the game.
• Parent-class Mailboxes receive the message too, and first: delivery walks the target's parent chain before the object's own Mailboxes, so a Mailbox defined on a parent type fires for messages sent to any child instance.

Which objects receive a message depends on the sender's target setting. See Message and Mailbox for the targeting options.

Timing

• Timer delays are set in tenths of a second and cannot resolve finer than one frame. A Timer measures elapsed game time but fires only when its object evaluates; a repeating Timer carries any overshoot into its next interval, so it averages its exact delay.
• Logic Gate inputs count as simultaneous when they arrive within the gate's time-slack window: 40 ms by default, just over two frames at 60 fps or one frame at 30. The window is adjustable per gate; gates saved before the setting existed keep 0 ms until edited.
• Collision events are recorded during the physics step and consumed during the same frame's behavior pass. Each object's collision set clears when the object finishes evaluating.
• Attachments evaluate during their parent object's evaluation and share the chain-depth limit with it.
• Pausing stops physics and behavior evaluation. When play resumes, Timers subtract the paused interval, so durations exclude paused time. Objects set to run while paused do not get this correction.

Choosing between similar nodes

Detecting objects

• Collision - fires on physical contact, from the physics step. Both objects need collisions enabled. Use for touching.
• Sensor - fires when something enters or leaves a region around the object, through the physics system. No per-frame scan: the physics engine tracks overlaps itself. Both objects need collisions enabled. Use for zones and ranges.
• Proximity - checks distance only when its check input fires, so its cost depends on what drives it: Always scans every frame, a Timer scans on that schedule. Works when the scanning object has collisions disabled; targets must be movable or collidable, or they have no physics body and are not seen. Prefer Sensor when both objects have collision shapes.
• RayCast - casts a line only when its input fires. Use for line-of-sight and ground checks on demand.
• In View - tests against the camera viewport each frame while in use. Use for on/off-screen logic, not gameplay range.

Moving objects

• Impulse - a one-time push; physics takes over from there. Use for jumps and knockback.
• Push Motor - a small push each time it evaluates, so driven by Always it acts as a steady force; the object accelerates against its mass and friction. Use for vehicles and thrust.
• Velocity - sets speed directly, replacing the current velocity. The new speed persists until physics or another node changes it. x and y each set only their own axis; forward sets both.

All three work with collisions. Collision problems usually come from bypassing physics: setting a position or rotation directly with a property node teleports the physics body, skipping collision response for that move, so it can land overlapping another collider.

Keeping a value

• Number / Text - a value in the graph, kept per instance; resets with the object.
• Object Variable - a named value on the instance; other objects' logic can read it by targeting that instance.
• Global Variable - one value game-wide; survives level changes and restarts (section 5).
• Save Value - persists on the player's device across sessions.

Clipboard JSON

Selecting behaviors and choosing Copy in the wheel menu puts a JSON document on the clipboard. Paste accepts the same document. The envelope:

{"data": {"behavior": {"v": "2", "nodes": [...], "links": [...], "frames": [...]}}}

A copied payload: a Timer wired into a Number. Each key is explained below the block.

{"data":{"behavior":{"nodes":[
  {"version":3,"x":120,"notes":null,"y":80,"delay":10,
   "id":"86f6a2760592ea4e","name":"Timer","behaviorType":"logic.triggers.Timer",
   "inputCount":3,"v":3,"n_o":0,"outputCount":2,"count":1,"group":"grpD"},
  {"x":340,"roundMode":1,"notes":null,"y":90,"tag":null,
   "id":"86f6a27639df8047","name":"Number","behaviorType":"logic.logic.Value",
   "inputCount":3,"n_o":0,"outputCount":1,"startVal":0,"group":"grpD"}],
 "frames":[],"v":"2",
 "links":[{"input_id":"86f6a27639df8047i0","output_id":"86f6a2760592ea4eo0"}]}}}

1. id - 16-character identifier, unique within the graph. Paste always assigns fresh ids, so hand-built ids only need to be unique and consistent with the links entries.
2. name - the node's display name; behaviorType - the engine class that deserializes it. Both must be present and agree.
3. x, y - workspace position in pixels; group - the id of the containing bundle, or the graph's root id for top-level nodes; n_o, notes - display order and the attached note text.
4. inputCount / outputCount - port counts, which the port index in a link id must stay below.
5. Per-type fields carry the node's settings: delay and count on the Timer, startVal and roundMode on the Number. Property names mirror the node's properties panel; the node appendix lists every type's fields.
6. v / version - the node type's port-layout version. Absent on types that have never changed ports.
7. The single link connects Timer output 0 to Number input 0. A link id is a node id followed by a direction letter and a port index: <nodeId>o0 is the Timer's first output (“out”), <nodeId>i0 the Number's first input (“set”). Port index order is the node's visible top-to-bottom port order, listed per type in the appendix and the Behavior Handbook.

9.1 Format stability

Stable - safe for tools to depend on: the envelope shape; the universal node fields (id, name, behaviorType, x, y, group, inputCount, outputCount); the link id grammar; and each node type's property names at its current version, as listed in the appendix.

Unspecified - present but deliberately not documented, and may change without notice: the id generation scheme, field ordering, the internals of Custom Behavior bodies, and any field not listed here or in the appendix. A tool that round-trips payloads must preserve fields it does not understand.

Port layouts change only with a node's version field: when a type gains or reorders ports, new nodes carry a higher v and old payloads keep their meaning. This page documents the current version of each type.

This documents the clipboard format for reading and re-pasting. It is not a server API, and no server endpoint accepts these payloads from third-party tools.

9.2 Example: a trigger chain

Mouse Click → Filter → Sound. Three nodes, two links:

{"data":{"behavior":{"nodes":[
  {"version":2,"x":100,"notes":null,"y":60,"global":false,
   "id":"86f6a277167ce54b","name":"MouseClick","rightClick":false,
   "behaviorType":"logic.triggers.MouseClick","inputCount":0,"v":2,"n_o":0,
   "outputCount":4,"skipAlpha":false,"group":"grpD"},
  {"x":300,"notes":null,"y":70,"id":"86f6a27756728948","name":"Filter",
   "mode":"greater than","behaviorType":"logic.logic.Filter2",
   "inputCount":2,"n_o":0,"outputCount":2,"gateVal":0,"group":"grpD"},
  {"pitch":100,"soundURL":null,"ext":false,"notes":null,"mode":0,"pos":0,
   "loop":false,"inputCount":8,"synthId":0,"sod":false,"x":520,
   "preload":false,"y":60,"volume":100,"soundName":null,"name":"SoundEffect",
   "id":"86f6a27726699545","behaviorType":"logic.components.SoundEffect2",
   "ol":false,"pan":0,"outputCount":8,"n_o":0,"group":"grpD","sound":null,
   "url":null}],
 "frames":[],"v":"2",
 "links":[{"input_id":"86f6a27726699545i0","output_id":"86f6a27756728948o0"},
          {"input_id":"86f6a27756728948i0","output_id":"86f6a277167ce54bo0"}]}}}

1. name is a display name and does not always match the editor palette: the Sound behavior serializes as "SoundEffect", Proximity as its internal name, and so on. behaviorType is the reliable type key; the appendix lists both.
2. The order of entries in links is not meaningful. Here the second link listed is the first in signal-flow order.
3. Settings fields vary widely per type - Sound serializes eighteen. A field holding null means the setting is unset, not absent.

9.3 Example: per-node versions

Payloads carry two unrelated version fields: the envelope's v is the schema version of the whole document, while a node's numeric v versions that node type's ports and settings. Two Logic Gates of different node versions in one (schema v2) payload:

{"data":{"behavior":{"nodes":[
  {"slack":0,"x":100,"notes":null,"y":200,"id":"86f6a277dcbbb648",
   "name":"Logic Gate","behaviorType":"logic.logic.Gate","gateType":"AND",
   "inputCount":2,"trueZero":false,"v":1,"n_o":0,"outputCount":1,"group":""},
  {"slack":40,"x":300,"notes":null,"y":200,"id":"86f6a277f5508842",
   "name":"Logic Gate","behaviorType":"logic.logic.Gate","gateType":"AND",
   "inputCount":2,"trueZero":false,"v":2,"n_o":0,"outputCount":1,
   "group":"grpD"}],
 "frames":[],"v":"2","links":[]}}}

1. The v:1 gate predates the time-slack setting and keeps slack: 0; the v:2 gate carries the 40 ms default. The engine reads v before interpreting the rest of the node, which is how old graphs keep their original behavior.
2. When a type changes its port layout, the same mechanism applies: port count and order are those of the node's v, not necessarily the current version's.

9.4 Example: Custom Behavior

Custom Behavior nodes define their own ports, so they carry a ports object no other type has:

{"data":{"behavior":{"nodes":[
  {"version":1,"x":100,"notes":null,"y":400,
   "ports":{"inputs":[{"name":"a","type":"Number"}],
            "outputs":[{"name":"out","type":"Number"}]},
   "tag":null,"id":"86f6a277c4b5fc41","name":"Custom Behavior",
   "body_hash":"","behaviorType":"logic.logic.Code","inputCount":2,
   "n_o":0,"v":1,"outputCount":1,"group":"grpD"}],
 "frames":[],"v":"2","links":[]}}}

1. ports lists the user-defined ports by name and type. Type names here are capitalized ("Number", "Text") - a different spelling than this page's lowercase port types.
2. inputCount is 2 for one defined input: the eval input is always present and is not listed in ports.
3. body_hash identifies the script body. The body itself and its storage are unspecified (section 9.1); tools must treat Custom Behavior nodes as opaque beyond their ports.

A subsection on bundles and frames is in preparation.