Lua Script Guide

Advanced automation on the default launch Lua runtime.

Runtime Scope

The 500+ API methods claim applies to the default launch Lua runtime. Lua 5.4.8 native runtime remains experimental and is not the production default until the cutover gate passes.

Guide Map

Mobile quick navigation

6 sections

Code Editor

Write Lua code in the dark-themed editor with line numbers. The code editor opens directly from the control panel and allows code changes even while macros are running. Use toolbar buttons to import code from external files, work with the template gallery, or speed up development with ready-made code snippets.

Toolbar:

Import: Import code from external files. Include external Lua files into your project.
Gallery: Access template images. Insert saved template names into your code.
Snippets: Add frequently used operations with one tap using ready-made snippets. Region scanning, tapping, loops, and more.

Editor

Snippets

Lua Editor - Try It

Write Lua code in the editor below. Use Ctrl+Space for autocomplete with Macro Handler APIs.

Macro Handler - Lua Editor

Basic Pattern

Every macro script follows a four-step structure: first cache the screen capture, then define the scan region, search for the target template, and apply an action when found. This pattern is the foundation of all macros and can be adapted to any scenario.

lua

Try in Editor →

Snap.screenRefresh()
local area = Region()
local tpl = Asset.image("start_btn")
local hit = area:find(tpl)
if hit then
  quickTap(hit)
  wait(500)
end

Snap.screenRefresh()Caches the screen capture. All subsequent Region.find() calls use this cached image.

Region()Defines the scan region (x, y, width, height).

area:find(tpl)Searches for template in region; returns location if found.

quickTap(hit)Taps the found location.

Production Pattern

In real scenarios, combining timeout, error handling, and loops yields more stable results. The pattern below keeps searching for the target within the specified time, catches errors without stopping the script, and exits the loop after applying the action when found. This pattern is recommended for all production use.

lua

Try in Editor →

local deadline = System.currentTime() + 15000
while System.currentTime() < deadline do
  local ok, result = pcall(function()
    Snap.screenRefresh()
    local r = Region()
    return r:find(Asset.image("reward_btn"))
  end)
  if ok and result then
    quickTap(result)
    toast("Reward tapped")
    break
  end
  wait(500)
end

pcall: Catches errors instead of stopping the script.

Timeout: Define a deadline with System.currentTime() to eliminate infinite loop risk.

Snippet Gallery

Common automation patterns. Each snippet runs as-is on the default launch runtime; copy, adapt to your macro's name.

6 snippets

Image Search with Timeout

Searches for a target image within a window, taps when found, and quietly gives up otherwise.

lua

Try in Editor →

local deadline = System.currentTime() + 8000
while System.currentTime() < deadline do
  Snap.screenRefresh()
  local hit = Region():find(Asset.image("start_btn"))
  if hit then
    quickTap(hit)
    return
  end
  wait(250)
end

HTTP GET with Retry

Network-resilient request: 3 attempts, exponential backoff, 4xx/5xx separation.

lua

Try in Editor →

local attempts, lastErr = 3, nil
for i = 1, attempts do
  local r = Request.get("https://api.example.com/v1/health")
  if r.status >= 200 and r.status < 300 then
    return r.body
  end
  lastErr = "status=" .. tostring(r.status)
  if r.status >= 400 and r.status < 500 then break end
  wait(500 * (2 ^ (i - 1)))
end
toast("HTTP failed: " .. tostring(lastErr))

Color Cluster Detection

Looks for at least N pixels of a target color in a region; ideal for UI state checks.

lua

Try in Editor →

Snap.screenRefresh()
local region = Region(100, 200, 800, 400)
local hits = region:findAllColors(0xFF3366, 12)  -- 12 px tolerance
if #hits >= 25 then
  toast("Active state detected")
else
  toast("Idle")
end

Two-finger Pinch Gesture

A two-finger pinch zoom-out via Touch.down/move/up.

lua

Try in Editor →

local f1, f2 = 0, 1
Touch.down(Point(540, 960), f1)
Touch.down(Point(640, 960), f2)
for i = 1, 20 do
  Touch.move(Point(540 - i * 10, 960), f1)
  Touch.move(Point(640 + i * 10, 960), f2)
  wait(16)
end
Touch.up(f1)
Touch.up(f2)

Region OCR with Number Extraction

Reads a region with OCR and extracts the first numeric value.

lua

Try in Editor →

Snap.screenRefresh()
local hud = Region(80, 60, 360, 80)
local text = hud:readText({ profile = "latin_score" }) or ""
local n = tonumber(text:match("(%d[%d%.]*)"))
if n then
  toast("Score: " .. n)
end

Safe Loop with pcall

Unexpected errors stop one iteration without stopping the script; they are logged and the loop continues.

lua

Try in Editor →

for i = 1, 50 do
  local ok, err = pcall(function()
    Snap.screenRefresh()
    -- ... your iteration body ...
  end)
  if not ok then
    System.log("iter " .. i .. " failed: " .. tostring(err))
  end
  wait(200)
end

Want more patterns? Suggest additions through the support form. Suggest a snippet

API Categories

Macro Handler offers 500+ API methods on the default launch Lua runtime. Each category addresses a different automation need. Lua 5.4.8 native runtime remains experimental until the cutover gate passes.

Detection

Region, Asset, Color, Snap

Image, color, and template scanning on screen. Asset matching, multi-result finding, and similarity settings. Snap the screen with Snap.screenRefresh(), define scan area with Region, and search for targets with Asset.image().

Snap.screenRefresh()
local r = Region()
local hit = r:find(Asset.image("btn"))

Go to Docs →

Automation

Touch, Point, click, quickTap, swipe

Tap, click, swipe, and multi-touch gesture controls up to 10 fingers. Use quickTap() for single tap, swipe() for swiping, and Touch.down/move/up for custom gestures.

quickTap(Point(540, 960))
swipe({GesturePoint(Point(100,500), 0, 0), GesturePoint(Point(900,500), 0, 300)})
Touch.down(Point(540,960), 0)

Go to Docs →

UI

Hud, Setting, Dialog

On-screen HUD panels, user settings dialogs, and notification messages. Show info on screen with Hud, collect user input with Setting.builder(), and display short messages with toast().

local hud = Hud(10, 10, 260, 50, false)
hud:setText("Running...")
hud:show()

Go to Docs →

System

System, File, Clipboard

File read/write, clipboard access, device info, and system commands. Get timestamp with System.currentTime(), handle files with File, and read/write clipboard with Clipboard.

local t = System.currentTime()
File.write("log.txt", "data")
Clipboard.copy("copied")

Go to Docs →

Network

Request

Connect to external APIs and exchange data via HTTP GET/POST requests. Fetch data from remote servers, send webhooks, or integrate with external services.

local res = Request.get("https://api.example.com/data")
local req = Request("https://api.example.com/webhook")
req:setBody("{\"ok\":true}")
local posted = req:post()

Go to Docs →

Time

DateTime, TimeSpan, Stopwatch

Date formatting, duration measurement, timer management, and delay handling. Measure operation times with Stopwatch, get date/time info with DateTime, and add delays with wait().

local sw = Stopwatch()
sw:start()
wait(1000)
local ms = sw:elapsed()

Go to Docs →

Data

File, Str, Num, Map, Clipboard

File read/write, string manipulation, number operations, and key-value data structures. Process text with Str, convert numbers with Num, and store persistent data with Map.

local s = Str.split("a,b,c", ",")
local n = Num.toInt("42")
Map.set("score", 100)

Go to Docs →

Parameters

FindParam, ClickParam, SwipeParam, PlayParam

Fine-tune template, find, color, swipe, and region parameters in detail. Override default behaviors to adjust search sensitivity, swipe speed, and color tolerance.

local fp = FindParam.mScore(0.85):timeout(3000)
local sp = { repeatCount = 2, delayMs = 150 }
r:find(tpl, fp)

Go to Docs →

License

License, Version

License validation, expiration checking, and version info querying. Add license checks when distributing your macro to prevent unauthorized usage.

if not License.isValid() then
  toast("License invalid!")
  return
end

Go to Docs →