Macro Handler API Guide

Runs the approved routine or plan of an enabled Agent block saved in this macro. Uses the same macro-start consent, stop rules and failure behavior as the block, returning a structured result.

-- Use a literal id from an enabled Agent block saved in this macro.
-- Its routine/plan must be approved; launch consent is still required.
local result = Agent.run("saved_agent_block_id")
if result.ok then
  print(result.outcome, result.taps)
else
  print(result.outcome, result.detail, result.kind)
end

Sends text or image prompts to the configured AI provider; the result is a table with ok, text and error.

local answer = AI.ask("Summarise this log line in five words: level 3 cleared")
if answer.ok then print(answer.text) else print(answer.error) end

Queries available API names and missing requirements for portable libraries.

local capabilities = Api.check({"Form.show", "Workflow.retry", "Module.use"})
if not capabilities.ok then
  error("Missing: " .. table.concat(capabilities.missing, ", "))
end
print("Library APIs are available")

Helpers for Lua lists: sort, filter, map, reduce, contains, length, reverse and join.

local scores = Array.sort({ 3, 1, 2 })
local doubled = Array.map(scores, function(item) return item * 2 end)

Creates search templates: Asset.image(name), Asset.color(hex) and Asset.text(text) return a template (AssetTemplate) you tune with methods such as :mScore() and :gray().

local template = Asset.image("play_button"):mScore(0.85)
local region = Region()
local match = region:find(template)

The search template Asset.image/color/text returns. It is not a global name; its methods chain and return the template (for example Asset.image("x"):mScore(0.9):gray()).

local template = Asset.image("target"):mScore(0.9):gray()
local match = Region():find(template)

Timers and promises: Async.defer and Async.every schedule delayed or repeating callbacks, Async.promise creates a result you can await. At most 128 timers and 128 promises can exist at once.

local timerId = Async.every(1000, function() print("tick") end)
wait(3500)
Async.cancel(timerId)

The result object Async.promise() creates: complete it with resolve or reject and wait for it with await.

local promise = Async.promise()
if promise then
  Async.defer(500, function() promise:resolve("ready") end)
  local ok, value = promise:await(2000)
end

The screen-capture session: grabs areas as Base64 images (for AI.askVision) and reports the session state.

local image = Capture.regionToBase64(Region(0, 0, 540, 960))
local answer = AI.askVision("What button is shown?", image)

Tap settings for click(): repeat count, hold time, pauses after each tap and a random offset.

click(Point(540, 960), ClickParam.hold(120))

Copies text to the clipboard and reads the clipboard text.

Clipboard.copy("Macro Handler")
local text = Clipboard.paste()

Persistent document collections private to the macro: write with put(name, id, document) and query by field equality with find(name, field, value).

Collection.put("players", "player_1", { name = "Ada", level = 3 })
local players = Collection.find("players", "level", 3, 10)

Reads and compares colours. Color.pixel(x, y) reads a colour from the screen; Color.isSimilar compares colours within a deltaE threshold. The factory functions are called with a dot and accept a Color object, a hex string or a packed ARGB number.

Snap.screenRefresh()
local pixel = Color.pixel(540, 960)
if pixel and Color.isSimilar(pixel, "#22BB57", 15) then
  click(Point(540, 960))
end

Writes to the macro log and asks the user for text with Console.in.

local level = Console["in"]("Enter a level number")
Console.out("Selected level: " .. level)

Digests (MD5, SHA), HMAC signatures, Base64/hex encoding, secure random values and constant-time comparison. Digests return hex strings; there is no encryption such as AES.

local signature = Crypto.hmacSha256("shared-secret", "payload")
local ok = Crypto.constantTimeEquals(signature, signature)

Date and time values. DateTime.now() or DateTime(...) returns a DateTime object; formatting uses Java patterns (yyyy-MM-dd HH:mm).

local now = DateTime.now()
toast(now:format("yyyy-MM-dd HH:mm"))

Dialog.init() returns the same dialog builder as Setting.builder(). Add fields, then show the dialog with build():show().

local builder = Dialog.init()
builder:setTitle("Settings")
builder:add("delay", EditText("500", 1, "Delay (ms)"))
local result = builder:build():show()

Sets and reads screen cutouts (notches), used to adapt coordinates between the macro and the device.

Env.setMacroCutouts({ top = 80 })
local cutouts = Env.cutouts()

Information about the trigger that started this run (source, app, title, text, time). Event.exists() tells whether the run was started by a trigger.

if Event.exists() then
  print(Event.appName() .. ": " .. Event.title())
end

In-script events: add listeners with Events.on and emit with Events.emit. At most 128 listeners in total and 32 per event.

Events.on("level_done", function(level) print("cleared " .. level) end)
Events.emit("level_done", 3)

Reads, writes and lists text files in the macro’s file area.

File.write("run.log", "Started")
local text = File.read("run.log")

Search parameters: timeout (ms), match threshold mScore (0-1), scan rate sRate (1-30 per second), scale and engine. Chain them as in FindParam.timeout(3000):mScore(0.85).

local param = FindParam.timeout(3000):mScore(0.85):sRate(10)
local match = Region():find(Asset.image("target"), param)

Builds conditional, tabbed and styled native dialogs from code-authored schemas.

local schema = {title = "Run settings", positive = "Start", negative = "Cancel", fields = {
  {type = "checkbox", key = "enabled", label = "Enabled", value = true},
  {type = "input", key = "target", label = "Target", value = "Example", required = true},
  {type = "slider", key = "count", label = "Count", min = 1, max = 10, value = 3},
  {type = "select", key = "mode", options = {"Safe", "Fast"}, selected = 2},
  {type = "multi", key = "steps", label = "Steps", options = {"Scan", "Report"}, value = {"Scan"}}
}}
local values = Form.show(schema)
if values ~= nil and values.enabled then
  local count = tonumber(values.count)
  if count then print(values.target, values.mode, count) end
end

A floating info box on screen. Hud(x, y, w, h, clickable) creates a Hud object; text and style methods are called on that object, and Hud.off() closes every box.

local hud = Hud(20, 20, 320, 64, false)
hud:setText("Running")
hud:setTextColor("#FFFFFF")
hud:setBackgroundColor("#80000000")
hud:show()

Sets and reads this macro’s human-like gesture level (0 is off, at most 3).

Humanize.setLevel(2)

Converts between Lua tables and JSON text. Call JSON.parse and JSON.stringify with a dot.

local data = JSON.parse([[{"enabled":true,"level":3}]])
local text = JSON.stringify({ enabled = true })

Persistent key-value storage private to the macro. Each macro has its own store; a value is limited to 1 MB and the store to 10 MB.

local runs = KV.increment("runs", 1)
KV.set("last_run", DateTime.now():format("yyyy-MM-dd HH:mm"))

Checks the user’s premium entitlement from a script: License.isActive() returns true when it is active. No activation keys or per-macro licences are used, so activate and deactivate change nothing.

if License.isActive() then
  toast("License active")
end

Runs other macros: Macro.run(target, params) queues one, Macro.runWait(target, params, timeoutMs) waits for it and returns the outcome. Call with a dot.

local outcome = Macro.runWait("daily_rewards", { level = 3 }, 60000)
print(outcome.status)

A key-value collection. Map() creates a Map object; get, set, has and keys are called on it with a colon. Static helpers such as Map.keys(table) also work on plain Lua tables.

local scores = Map()
scores:set("level", 3)
if scores:has("level") then
  print(scores:get("level"))
end

Helpers that complement Lua’s math library: random ranges, angle conversion, hypot and atan2.

local distance = Math.hypot(300, 400)
local delay = Math.randomRange(200, 400)

Collects and summarises runtime metrics (scan and OCR counters).

Metrics.enable()
-- ... run the scans ...
print(Metrics.summary())

Organizes source code carried with the macro into reusable libraries with dependencies.

Module.define("example.normalizer", function()
  return {clean = function(text) return string.lower(text) end}
end)
local library = Module.use("example.normalizer")
print(library.clean("HELLO"))

Multi-finger gestures: add each finger path with MultiGesture.builder(), then run them together with build():go().

local builder = MultiGesture.builder()
builder:add({ GesturePoint(Point(300, 1500), 0, 0), GesturePoint(Point(300, 600), 0, 400) })
builder:add({ GesturePoint(Point(780, 1500), 0, 0), GesturePoint(Point(780, 600), 0, 400) })
builder:build():go()

Steers a joystick along a saved map and route. Navigation.run(options, onCheckpoint?) owns the control loop and returns a table describing how the run ended; Navigation.stop() ends the journey from an observation group after confirmed input release.

local result = Navigation.run({ profileId = profileId, routeId = routeId, routeType = "one_way", timeoutMs = 120000 })
print(result.state, result.progress)

Number conversion and rounding; Num.parseOcr and Num.evalOcrMath turn OCR-read text into numbers safely.

local coins = Num.parseOcr("l,234", 0)
local price = Num.precise(19.987, 2)

Controls the floating control panel from a script: show, hide, position it, set its opacity and read its state.

Panel.show()
Panel.setOpacity(0.85)
Panel.setPosition(120, 300)

The Time/Repeat gate: on each visit it picks the true or the false phase by visit count or elapsed time and keeps its state for the macro run.

local gate = PhaseGate.create({ trueMode = "count", trueLimit = 3, falseMode = "count", falseLimit = 1 })
if PhaseGate.next(gate) then
  print("work phase")
end

Playback settings for Replay.play(): repeats, pauses, a random offset and speed.

Replay.play("daily_route", PlayParam.setSpeed(1.5))

A point on the screen. Point(x, y) maps macro coordinates to the device and returns a Point object (nil when mapping fails); click, quickTap and Touch calls accept a Point.

local point = Point(540, 960)
if point then quickTap(point) end

Java regular expressions: match, matchAll, find, replace and split. The pattern is the first argument; each operation is limited to 2 seconds.

local level = Regex.match("[0-9]+", "Level 12, stage 3")
local parts = Regex.split(",\\s*", "red, green, blue")

An area of the screen to search and act in. Region(x, y, w, h) creates a Region object (Region() is the whole screen); find, click, wait, read and the geometry methods are called on that object with a colon.

local area = Region()
local hit = area:find(Asset.image("ok_button"))
if hit then quickTap(hit) end

Touch recordings: start and stop a recording, save it under a name, list them and play one with Replay.play.

local ok = Replay.play("daily_route")

HTTPS requests. Short calls such as Request.get(url) take only the address; for headers, a body or retries create a request object with Request(url) and configure it. Read the response with getResponseCode() and getData().

local res = Request.get("https://example.com/api/status")
if res:getResponseCode() == 200 then
  local data = JSON.parse(res:getData())
end

The match a search such as region:find(...) returns. It is not a global name: check the search result for nil first, then call methods such as getX(), getScore() or getEngine() on it.

local match = Region():find(Asset.image("target"), FindParam.timeout(3000))
if match then
  print(match:getX(), match:getY(), match:getScore())
  click(match)
end

Coordinate and runtime settings: the macro’s reference resolution (Runtime.setMacroSize), scale, debug mode and completion messages.

Runtime.setMacroSize(1080, 2400)
print(Runtime.resolution())

Manages macro settings and the user dialog. Call its functions with a dot: Setting.get(key, default) and Setting.set(key, value) read their arguments by position.

local builder = Setting.builder()
builder:add("delay", EditText("500", 1, "Delay (ms)"))
Setting.setDialog(builder:build())
Setting.show()
local delay = tonumber(Setting.get("delay", "500")) or 500

The dialog builder from Setting.builder() or Dialog.init(). Add fields with add(key, view); build() returns the dialog and build():show() returns the user’s answers.

local builder = Setting.builder()
builder:setTitle("Macro settings")
builder:add("delay", EditText("500", 1, "Delay (ms)"))
local result = builder:build():show()

Manages the screen-capture cache: take a fresh frame with Snap.screenRefresh() before searching and limit capture to an area with Snap.region(...).

Snap.screenRefresh()
local region = Region()
local found = region:find(Asset.image("start_button"))

Server-Sent Events reader: reads events from an address and returns a table with ok, events, count and first.

local result = SSE.first("https://example.com/events", 10000)
if result.ok and result.first then print(result.first.data) end

Measures elapsed time. Stopwatch() creates a stopwatch object; start(), elapsedMs() and lap() are called on that object.

local watch = Stopwatch()
watch:start()
wait(250)
print("Elapsed ms: " .. tostring(watch:elapsedMs()))

String helpers. Positions are 0-based like Java strings: Str.indexOf returns -1 when nothing is found and Str.substring(source, start, end) excludes end.

local name = Str.trim("  Macro Handler  ")
if Str.startsWith(name, "Macro") then
  print(Str.toUpperCase(name))
end

Swipe settings for swipe(): repeat count, pauses between repeats and waypoints, and a random offset.

swipe({ GesturePoint(Point(540, 1500), 0, 0), GesturePoint(Point(540, 500), 0, 300) }, SwipeParam["repeat"](2))

Device and app operations: messages and logging, global actions (Back, Home), opening apps, timers and scheduled runs, and screen information.

System.toast("Starting")
local width, height = System.width(), System.height()
System.log("Screen: " .. width .. "x" .. height)

Duration values. Factory functions such as TimeSpan.fromSeconds(...) return a TimeSpan object; totalSeconds(), add() and format() are called on it.

local span = TimeSpan.fromMinutes(90)
print(span:totalHours(), span:format("HH:mm:ss"))

Styled messages: ToastParams() creates a style object, settings chain, and show(text) displays the message.

local style = ToastParams():setPosition("top"):setDuration(3000)
style:show("Level complete")

Low-level touch: finger down/move/up, pinch and rotate gestures and, from 1.0.51, background finger lanes (Touch.lane*).

Touch.down(Point(500, 1200), 0)
wait(80)
Touch.up(0)

Settings for this run: a script can store and read back a match threshold, tap and swipe delays, a scan interval and a comparison size; these do not change searches or gestures. Only the grayscale switch changes searches: from Macro Handler 1.0.51, Tune.grayscaleOn() makes image searches colour-independent.

Tune.grayscaleOn()
local match = Region():find(Asset.image("enemy_icon"), FindParam.timeout(2000))
Tune.grayscaleOff()

Reads the on-screen app interface from the accessibility tree: finds elements by text or id and clicks them.

local node = Ui.byText("Settings")
if node then Ui.click(node) end

Utility functions: Utils.interpolatePoints creates evenly spaced points between two points.

local points = Utils.interpolatePoints(Point(200, 1600), Point(880, 400), 8)

Version comparison. Version.isAtLeast("1.0.40") checks the running app; Version("1.2.3") creates a Version object.

if not Version.isAtLeast("1.0.40") then
  System.alert("Please update Macro Handler")
  requestStop()
end

Visual target tracking: describe several views of one target with profile, find it on each frame with step, and follow its moving or lost status.

local profile = VisualTarget.profile("enemy", { { name = "front", template = Asset.image("enemy_front") } })
local state = VisualTarget.step(profile, Region())
if state.found then VisualTarget.click(profile) end

WebSocket client: WebSocket.text and WebSocket.exchange make a one-off exchange; WebSocket.connect opens a connection object whose send, receive, on and close methods are called on it.

local socket = WebSocket.connect("wss://example.com/socket")
socket:send("ping")
local event = socket:receive(5000)
socket:close()

Combines condition polling, bounded retries, sequential loops and cleanup in authored code.

local result = Workflow.retry(function(attempt)
  return attempt >= 3, "sample result"
end, {maxAttempts = 4, delayMs = 50, backoff = 2, timeoutMs = 2000})
print(result.ok, result.attempts, result.values[2])