Lua Script Guide

Advanced automation with full API access.

Guide Map

Mobile quick navigation

5 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.

Loading 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

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

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.

API Categories

Macro Handler offers 500+ API methods. Each category addresses a different automation need. Review the example code to get started quickly.

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 →