Block ↔ Lua API Mapping

Lua API equivalent

Region():find(Asset.image("name"):mScore(0.8), {engine="balanced_image"})

local hit = Region():find(Asset.image("icon"):transparent(), {engine="pixel_exact_image", tol=16})
if hit then System.log(tostring(hit:getEngine()) .. " " .. hit:getAngle()) end

Searches the region for a template image; mScore is the match threshold (0–1) and engine selects the scan engine.

Lua API equivalent

Region():find(Asset.text("target"), {ocrScript="latin"})
Region():readPlain({ocrScript="latin"})  -- OCR find/replace

OCR-searches the region for the text; with OCR find/replace set, it also reads the region and writes the cleaned text to the Save Read Value variable.

Lua API equivalent

Region():find(Asset.color("#RRGGBB"):mScore(score))

Searches for a specific color in the region.

Lua API equivalent

compare repeated Region():find(Asset.color("#RRGGBB")) positions

Tracks whether a color shifts position.

Lua API equivalent

(Visual Builder only: combines multiple IMAGE/TEXT/COLOR targets into one decision block)

Combines multiple IMAGE/TEXT/COLOR targets into one decision block.

Lua API equivalent

(Visual Builder only: locks onto one IMAGE/TEXT/COLOR match, then tracks nearest continuation until lost-frame limit)

Locks onto one image/text/color match and tracks the nearest continuation candidate until the lost-frame limit is reached.

Lua API equivalent

VisualTarget.profile/refresh/step/snapshot/reset/click/swipeToward

Acquires, tracks, and reacquires a multi-view target fully on-device, publishing bounds, centre, view, engine, score, velocity, loss, and error outputs.

Lua API equivalent

local r = Region():agentDetect(macroScopeId, referenceSetId, options); if r.status == "found" then click(r.targets[r.selected].clickMatch) end

Finds and tracks targets that visually resemble examples marked in reference screenshots, offline; returns status (found/not_found/error), a typed code and a target table, and never taps by itself. The no-code block revalidates the target on a fresh frame right before tapping.

Lua API equivalent

local raw = Region():readAsString(param, "")
local value = Num.parseOcr(raw, 0)

Reads the region with OCR and converts the text to a number; an unreadable value becomes 0.

Lua API equivalent

local text = Region():readAsString(param, ""); local r = AI.ask(prompt .. text, providerId)

Reads a region via OCR, then turns the text into a decision with AI.ask.

Lua API equivalent

Capture.regionToBase64(region, "jpeg", 60) + AI.askVision(prompt, image, providerId, "image/jpeg", nil, timeoutMs)

AI mode uses a vision request; local mode samples Color.getAllScreen. true/false/unknown/error, retry, confidence and target rules are additional Lua logic; use generated code for the full equivalent.

Lua API equivalent

local result = Navigation.run({profileId="saved-profile-uuid", routeId="saved-route-uuid", routeType="one_way", controlMode="strict", timeoutMs=120000})

Use IDs from a saved setup and route in this macro; do not execute the example labels verbatim. Runs feedback-controlled movement with measured local calibration; returns state/lastFailure and typed measurements. headingKnown is false for an unknown heading.

Lua API equivalent

if Navigation.stop() ~= true then error("NAVIGATION_RELEASE_UNCONFIRMED") end

Place it before screen actions in a Scan group while moving. It ends this macro’s journey and blocks the next action until joystick release is confirmed; the journey does not resume automatically.

Lua API equivalent

click(Point(x, y), {repeatCount=1, holdMs=0})
click(Region():find(...), param)

Taps a point or a match; supports repeat and hold parameters.

Lua API equivalent

swipe({GesturePoint(start, 0, 0), GesturePoint(end, 0, 300)})

Swipe between two points.

Lua API equivalent

Replay.start(); Replay.stop()
Replay.play(name, {repeatCount=1, waitNextMs=0, randomRadius=0, speedMultiplier=1})

Starts or stops a recording, or plays a saved touch recording with Replay.play (repeat, wait, random radius and speed).

Lua API equivalent

for i = 1, maxRepeats do
  if not Region():find(Asset.image("anchor")) then break end
  Replay.play(name, {repeatCount=1})
  wait(waitMs)
end

Plays the recording with Replay.play while its image anchor stays on screen; the anchor is searched again before every repetition, and the loop stops once it disappears.

Lua API equivalent

System.toast("text")

Shows a short on-screen message (toast); {{ expression }} templates are resolved.

Lua API equivalent

Request(url):setContentType("application/json"):setBody(JSON.stringify({content=message})):post()  (Discord/Telegram/Generic preset)

Sends a notification to a Discord, Telegram, or generic webhook over HTTPS POST; built on the HTTP_POST infrastructure with no new Lua API.

Lua API equivalent

System.playMedia(asset)

Plays a sound asset.

Lua API equivalent

Panel.show() / Panel.hide() / Panel.spin() / Panel.close() / Panel.move(x, y) / Panel.setOpacity(0.6)

Shows, hides, or minimizes the control panel, opens the helper panel (spin), stops and closes it, moves it, or sets its opacity from 0 to 1. To write text on screen, see the HUD OVERLAY row.

Lua API equivalent

local hud = Hud(x,y,w,h,false); hud:setText("text"); hud:show(); hud:setText("updated")

Writes text/state into the on-screen HUD.

Lua API equivalent

local id = System.setTimeout(ms, fn)  -- or System.setInterval(ms, fn)
System.clearTimeout(id)  -- or System.clearInterval(id)

Calls the chosen block group once after a delay (timeout) or repeatedly at an interval (interval); the same block’s clear action cancels the timer by its id.

Lua API equivalent

Touch.laneAdd(from, to, legMs, legs, turn, finish); Touch.laneStart(tag, background, maxRunMs); Touch.laneStatus(tag)

Stages fingers as lanes and starts them together: a stationary hold, a back-and-forth or restarting swipe, optionally running in the background. Touch.laneError() returns the failure code. Version 1.0.50 and earlier generate this block as Touch.down(point, finger) plus Touch.dispatch().

Lua API equivalent

Touch.breakAll()

Touch.breakAll()              -- also lifts background lanes
Touch.laneRelease("hold", 0)  -- lifts only the lane tagged "hold"

Lifts every held finger and resets the touch state.

Lua API equivalent

MultiGestureBuilder():add({GesturePoint(a1, 0, 0), GesturePoint(a2, 0, 500)}):add({GesturePoint(b1, 0, 0), GesturePoint(b2, 0, 500)}):build():go()

Each add() adds one finger path; build():go() sends two or more paths at the same time as a single multi-finger gesture.

Lua API equivalent

wait(ms)

Pauses for a duration.

Lua API equivalent

local ok = (a and b) or c

Combines compare conditions with AND/OR into one boolean result.

Lua API equivalent

if cond then ... else ... end

Runs the TRUE or FALSE branch based on a condition.

Lua API equivalent

-- Compare values
if a == b then ... else ... end
-- Compare screen regions
local ref = Capture.regionToBase64(referenceRegion, "png", 100)
-- the block turns ref into an in-memory image template (never saved to the gallery)
local hit = targetRegion:find(referenceTemplate)

“Compare values” maps to the Lua if-else construct. “Compare screen regions” captures the first region as a reference (kept only in runtime memory, never added to the gallery), searches the target regions for a similar image with any/all logic, and hands the matched target to click, swipe, and touch blocks in the True branch. This mode cannot run inside a pure condition list.

Lua API equivalent

generated _mhM measurements + Lua geometry/conditions

Evaluates measurements published by earlier blocks and produces direction, angle, distance, and status outputs.

Lua API equivalent

for i, v in ipairs(t) do ... end

Iterates over a collection.

Lua API equivalent

if v == 1 then ... elseif v == 2 then ... else ... end

Lua has no native switch; equivalent via if/elseif chain.

Lua API equivalent

local ok, err = pcall(function() ... end)

Error catching via pcall.

Lua API equivalent

return value

Returns a value from the enclosing function.

Lua API equivalent

local function name() ... end

A callable block group (function).

Lua API equivalent

Generates Lua state logic that selects one workflow per invocation: sequential, random, or advancing on the invocation after a marker completes. It is not a standalone runtime API call.

Lua API equivalent

Generates two lanes and target checkpoints at safe action boundaries as ordinary Lua flow; there is no separate global API. Nested group progress is preserved.

Lua API equivalent

Generates Lua flow that repeats preceding blocks in the same sequence by count or duration; there is no separate global API. Choose the start boundary, first-pass handling and repeat interval in the block settings.

Lua API equivalent

local gate = PhaseGate.create(options); PhaseGate.next(gate); PhaseGate.status(gate); PhaseGate.reset(gate)

Selects True/False by visit or elapsed-time limits; it does not create a loop. Retain the handle between visits. Expiry does not interrupt an action already running.

Lua API equivalent

name(arg1, arg2)

Calls a defined group.

Lua API equivalent

Lua state + conditions + group functions

State transitions, timeouts and recovery group calls are generated Lua and can be extended in the code editor.

Lua API equivalent

Macro.run(target, params)
local result = Macro.runWait(target, params, timeoutMs)

Starts another saved macro; in wait mode it stores the outcome in a variable.

Lua API equivalent

if not (cond) then error("message") end

Raises an error when the condition fails; Try/Catch catches it, and an uncaught error goes to ERROR_HANDLER when present or stops the macro.

Lua API equivalent

-- single-line
--[[ block ]]

Inline note that does not execute.

Lua API equivalent

local result = Setting.builder():add("confirm", Checkbox(false, "Confirm")):add("name", EditText("", 1, "Name", "Enter your name")):setPositiveButton("OK"):setNegativeButton("Cancel"):build():show()

Shows a dialog with checkbox, text input, and selection fields; show() returns the field values in a table keyed by field id (result.confirm, result.name).

Lua API equivalent

x = (value)  -- macro variable

Stores a value or expression result in a macro variable; for a value that persists between runs, use KV_SET.

Lua API equivalent

local r = expression  -- plain Lua arithmetic

Computes an arithmetic or variable-based expression.

Lua API equivalent

Math.randomRange(min, max)

Generates a random whole number between min and max, inclusive.

Lua API equivalent

break

Exits the enclosing loop.

Lua API equivalent

goto continue  -- the ::continue:: label sits at the end of the loop body

Lua has no continue keyword; emulated via goto + label.

Lua API equivalent

Metrics.summary(); Metrics.enable(); Metrics.disable(); Metrics.reset()

Manages runtime metrics with summary, enable, disable, and reset actions.

Lua API equivalent

System.home() / System.back() / System.openApp(package) / System.openUrl(url) / System.sendIntent(action, package) ...

Safe wrapper over system calls; Send Intent emits System.sendIntent(action, package?) and still passes runtime allowlist policy.

Lua API equivalent

System.log("text")
System.log("Count: " .. tostring(count))  -- LOG "Count: {{ count }}"

Writes a message to the macro log; {{ expression }} templates are resolved, Lua concatenation outside a template is printed as written.

Lua API equivalent

local res = Request(url):get(); local code, body = res:getResponseCode(), res:getData()

Sends an HTTPS GET request; read the status code with getResponseCode() and the response body with getData().

Lua API equivalent

Request(url):setBody(body):post()

Sends a POST request.

Lua API equivalent

Request(url):setBody(body):put()

Sends a PUT request.

Lua API equivalent

Request(url):setHeader(...):setBody(...):post()

Fully parameterized HTTP request.

Lua API equivalent

local r = WebSocket.exchange(url, message, maxMessages, timeoutMs, headers)
-- r.ok, r.first, r.messages, r.count, r.error

One-shot exchange: connects to a wss:// address, sends the message, waits for the requested number of replies or the timeout, then closes; it is not a permanent subscription. For a connection that stays open, use the object returned by WebSocket.connect(url) in code with ws:on(...), ws:send(...), and ws:receive(...).

Lua API equivalent

(runs your Lua as written)

Embeds a raw Lua block inside the visual chain.

Lua API equivalent

local list = {"a", "b", "c"}

Stores line- or comma-separated values as a list variable.

Lua API equivalent

Str.toUpperCase(s) / Str.substring(s, i, j) / Str.replace(s, a, b) / Str.split(s, sep) ...

String operations (lower, upper, replace, etc.).

Lua API equivalent

Regex.match("h.*o", "hello")
Regex.matchAll(pattern, s)

Matches with Java-syntax regex (not Lua patterns).

Lua API equivalent

DateTime.nowMs()
DateTime.format(DateTime.nowMs(), "yyyy-MM-dd")

Reads current date or timestamp.

Lua API equivalent

TimeSpan.fromSeconds(5)
TimeSpan.fromMinutes(2):totalMillis()

Builds a duration from a value and a unit (ms, seconds, minutes, hours, days) and returns the duration or its total milliseconds.

Lua API equivalent

local sw = Stopwatch(); sw:start(); ... local dt = sw:elapsedMs()

Measures elapsed time.

Lua API equivalent

KV.get("key")

Reads from the persistent key/value store.

Lua API equivalent

KV.set("key", value)

Writes to the persistent key/value store.

Lua API equivalent

Clipboard.paste()

Reads the system clipboard; Clipboard.get() returns the same value.

Lua API equivalent

Clipboard.copy("text")

Writes to the system clipboard.

Lua API equivalent

File.readText("path")  -- sandboxed path

Sandboxed file read.

Lua API equivalent

File.writeText("path", "content")
File.appendText("path", "content")  -- append mode

Sandboxed file write.

Lua API equivalent

File.delete("path")

Deletes a sandboxed file or folder.

Lua API equivalent

JSON.parse("...")

Parses JSON text into a Lua table.

Lua API equivalent

Collection.put("items", "id", {name="value"}); Collection.list("items")

Manages an ordered document collection.

Lua API equivalent

local m = Map(); m:set("key", "value"); m:get("key")

Manages a key/value map.

Lua API equivalent

while cond do ... end

Repeats while a condition holds.

Lua API equivalent

repeat ... until cond

Repeats until a condition holds (at least once).

Lua API equivalent

local ok, err = pcall(function() ... end)  -- the whole main flow
if not ok then System.log("Error: " .. tostring(err)) end  -- Error Action: Log

Wraps the whole main flow in one pcall; an uncaught error goes to the Error Variable (default errorMessage) and the chosen Error Action runs once: Log, Notify, Stop, Continue or Custom (Recovery Actions). The macro then ends.

Lua API equivalent

while DateTime.nowMs() < deadline do wait(interval) end

Waits until a deadline.

Lua API equivalent

local result = Agent.run("saved_agent_block_id")

Runs a separately approved routine/plan of a saved Agent block in this macro with macro-start consent. Use a literal block id; returns ok/outcome/taps/detail/kind. Emulator/API tests are not physical-device or game-success proof.