Variables, Functions & Flow Control

A variable is a "named box" used to store data at runtime (such as the result coordinates of an image search, OCR-recognized text, a counter, and so on).

How to use one:

1. Type a name directly (e.g. count) into the "Variable Name" field of a Set Variable node and you get a local variable — no prior definition needed
2. To share a value across actions, first define it in the "Variables" tab (Ctrl+3), then click the ◎ button next to the variable name field of the "Set Variable" node to pick it — that gives you a global variable
3. Read the variable downstream: reference it in a condition expression, or insert its value in an "Input Text" node

Local vs global variables:

• Local variable (the default) — just type the name. It belongs to this run; every action gets its own, so concurrently running actions never interfere. It is visible across functions within the same run.
• Global variable — pick an entry from the "Variables" tab via ◎. Shared across actions, used to pass data between them.

There is no "scope: local/global" switch — the scope is decided by whether you pick a Variables-tab entry with ◎. Any name that isn't picked and doesn't match a Variables-tab entry is treated as a local variable, which keeps older projects behaving exactly as before.

Typical usage:

• The result of an image search is automatically stored in a variable (e.g. result), including coordinates and confidence
• Use a "Set Variable" node as a counter: count + 1 on each loop iteration
• Reference a variable in an "Input Text" node for dynamic input

Note: variables are not persisted — every run starts again from the default values set in the Variables tab. So you cannot use variables for run-spanning counters like "times collected today"; use a Custom Code node to read/write a file if you need that.

Conditions let your script "take different paths depending on the situation". Every node can have an execution condition set (at the bottom of the node configuration):

• Unconditional (default) — runs no matter what happened before
• On Success — runs only if the previous node succeeded. E.g. image found → then click
• On Failure — runs only if the previous node failed. E.g. image not found → take a fallback path
• Custom Condition — write an expression; it runs only when the expression is true. E.g. count >= 5 (only run after more than 5 loop iterations)

How are "success/failure" defined?

• Find Image: found = success, not found = failure
• OCR Compare: text matches = success, doesn't match = failure
• Wait for Change: change detected = success, timed out = failure
• Call Function: function returns false = failure; returns true/another value, or returns nothing (no failure inside) = success
• Wait / Click / Log: always succeeds

The Loop node is a container — drag other nodes into it and they'll be executed repeatedly. Three modes:

• Fixed count — loop N times. E.g. click 10 times → set the count to 10.
• Infinite loop — repeats forever until the script is stopped manually. E.g. continuously monitoring a health bar, continuous farming.
• Iterate array — takes each element of an array in turn and executes. E.g. click each button in a list one by one.

How to use:

1. Add a "Loop" node
2. Double-click to configure it, choosing the loop mode and parameters
3. Drag the nodes to repeat into the loop container (they'll be shown indented)

Tip: in an infinite loop, we recommend adding a short "Wait" node (e.g. 100ms) to avoid excessive CPU usage.

A function "packages" a group of nodes into a reusable module. Define it once, then call it multiple times from the main flow.

When to use one?

• The same sequence appears 2 or more times in your flow → make it a function to avoid duplication
• A sequence has an independent meaning (e.g. "return to town", "reload ammo", "turn the page") → making it a function makes the flow clearer
• You want to call a sequence from a custom action → it must be a function first

How to use:

1. Create a function in the "Functions" tab (Ctrl+5) and edit its internal nodes
2. You can give a function a description, shown in the function list and used as the title of "Call Function" nodes — handy for telling similar functions apart in a long flow
3. Add a "Call Function" node in the main flow and select the function to call
4. Functions can take parameters, letting you pass different values at each call
5. To return a value, add a Return node (Flow Control group) inside the function. A new "Call Function" node comes with a result variable named call_result that captures the return value — rename it in the node config, or clear it to ignore the return value

Functions can call each other. Inside a function you can read and write this run's local variables directly (visible across functions within the same run); use global variables only when data must be shared across actions.

When a function needs to hand a result back to its caller, add a Return node (Flow Control group) inside the function and put a variable name, an expression, or a literal in its "Return Value" field. Leave it empty to return nil.

Return value convention:

• return false — business failure: the script raised no error, but the goal wasn't met (the target never appeared, the reward wasn't claimed). The task is treated as failed, the run is not counted, and it is retried using the task's retry settings.
• return true or any other value — success
• No Return node at all (returns nil) — unchanged behaviour, judged at the technical layer (no error means success)

This convention only applies to the entry function — the one a task invokes directly. Its purpose is to report "technically fine, business failed" back to the task system.

Two things to watch out for:

• The Return node must be the last node of its block (function body / loop / condition). Anything placed after it never executes — you can check the generated Lua in the code preview.
• The return value is visible only within the same function (later nodes in that function reference it by the result variable name). To hand it to another function or another action, use a global variable.

An expression is a snippet of Lua code that produces a value when run. It lets you perform calculations, concatenation, comparisons, and other flexible operations.

Places where you can use expressions:

• Custom conditions in a Condition: count >= 10 and hp < 30
• Set Variable with "Expression" checked: count + 1, name .. "_done"
• Log Output with "Expression" checked: "Loop #" .. count
• Custom Code (Pro) accepts any Lua — for dynamic values such as a random wait, use wait(math.random(500, 1500))

Note: the Wait node takes a fixed number of milliseconds and does not support expressions.

Common syntax:

• Arithmetic: a + b, a * 2, a % 3
• String concatenation: "hello" .. name
• Comparison: x > 100, name == "test"
• Logic: a and b, a or b, not a

When "Expression" is not checked, the input field's content is treated as plain text/a number.