# Lua Guide

This guide describes the current Lua API. Older builds may not include newer functions or options; check your installed version before using them.

# Usage

For installation, recording, playback and license setup, start with the user guide. This page covers Lua scripting and the built-in API. JavaScript scripts and index.js package entry points are not supported by current builds.

# Quick start

Create hello.lua in AutoTouch, save it, then select it from the control panel:

log("AutoTouch " .. getVersion())
local width, height = getScreenResolution()
if not width or not height then
    alert("Screen dimensions are not available. Check the device and try again.")
    return
end
alert(string.format("Hello! Screen: %d × %d pixels", width, height))

Built-in functions such as tap, findImage and dialog are available without require. Libraries such as json use require("json"). Hold Volume Down to stop a running script. Use log() to inspect progress in the runtime log.

# API map

Task	Functions
Touches and buttons	touchDown, tap, keyPress
Screen state	getScreenResolution, screenshot, unlockScreen
Colors and images	getColors, findColors, findImage
Text and dialogs	ocr, inputText, dialog
Apps	appRun, appActivate, appInfo
Timing and repetition	usleep, keep, setTimer
Paths and diagnostics	rootDir, currentDir, captureDebugInfo

# Paths and packages

A package is a directory ending in .at, with main.lua as its entry point:

MyProject.at/
  main.lua
  images/
    button.PNG
  helpers.lua

From main.lua, use findImage({image = "images/button.PNG"}). Image paths are relative to the running script; an absolute path starts with /. File names must match the actual file, including its extension. A Photos album entry is not a file path: import the image into the project first.

currentDir() is the runtime directory, which can be temporary for encrypted packages. botPath() identifies the original script/package. Use rootDir() to locate the persistent scripts directory instead of hard-coding a jailbreak-specific path. Native APIs document their path rules individually; for Lua file I/O, an explicit path avoids reliance on the process working directory.

# Lua basics

AutoTouch uses Lua 5.3. See the Lua reference manual (opens new window) for language syntax. Lua arrays start at 1; screen coordinates start at 0. Booleans are true and false, and an absent value is nil.

For debugging, start with a small script and log intermediate values. A missing image or invalid option can raise a Lua error. Use pcall around an operation when your script needs to recover; do not treat an error as an empty search result.

# Coordinate, Size and Orientation System

AutoTouch touch and image APIs use native screen pixels. Read getScreenResolution() for the current orientation instead of copying dimensions from another device. The call can return nil, nil if display state is unavailable.

The origin (0, 0) is the top-left of the current application interface; x increases to the right and y downward. A search region is {x, y, width, height}, not two corner points. Touch coordinates must be inside the screen. Re-read dimensions after rotation.

Do not mix physical device orientation (getOrientation()) with interface orientation (frontMostAppOrientation()). Searches within a region still return full-screen coordinates. Offline image searches return coordinates in the source image.

For example

Parameter	Type	Specification
id	Integer	Finger ID. is used to mark a finger in single-touch or multi-touch.
x	Float	x-coordinate on the screen
y	Float	y-coordinate on the screen

Parameter	Type	Specification	Optional	Default
color	Integer	Matched color value.	NO
count	integer	Maximum matches; `0` means all. Use `1` when you only need one target.	YES	0
region	table	`{x, y, width, height}` in screen pixels; nil searches the whole screen.	YES	nil
debug	boolean	If pass debug=true, it will produce a image ends with "-Debug.PNG" marked the matching areas.	YES	false
rightToLeft	boolean	Search direction, default is left to right.	YES	false
bottomToTop	boolean	Search direction, default is top to bottom.	YES	false

Parameter	Type	Specification	Optional	Default
colors	table	A non-empty pattern of `{color, dx, dy}` entries. Use `{color, 0, 0}` for the first anchor, then offsets from that anchor for other colors.	NO
count	integer	Maximum matches; `0` means all. Use `1` when you only need one target.	YES	0
region	table	`{x, y, width, height}` in screen pixels; nil searches the whole screen.	YES	nil
debug	boolean	If pass debug=true, it will produce a image ends with "-Debug.PNG" marked the matching areas.	YES	false
rightToLeft	boolean	Search direction, default is left to right.	YES	false
bottomToTop	boolean	Search direction, default is top to bottom.	YES	false

Field	Type	Default	Specification
image	string	required	Target image path, relative to the current script or absolute.
source	string	current screen	Optional source image path for offline matching and tests.
count	integer	1	Integer from `0` to `100`; `0` requests up to 100 results, not an unlimited search.
confidence	float	0.82	Normalized minimum confidence in `[0, 1]`.
region	table	whole source	`{x, y, width, height}` search region.
strategy	string	`"auto"`	`"auto"`, `"template"`, `"feature"`, or `"shape"`.
colorMode	string	`"auto"`	`"auto"`, `"color"`, `"luminance"`, or `"shape"`.
featureBackend	string	`"auto"`	`"auto"`, `"sift"`, or `"orb"`. On rootless/Dopamine, `auto` selects ORB; explicitly selecting SIFT for `auto` or `feature` strategy raises an error.
minScale / maxScale / scaleStep	number	0.5 / 2.0 / 1.25	Scale bounds: `0.1`–`8.0`, minimum ≤ maximum. Multiplicative step: `1.01`–`4.0`. Scale `1` is the original target size.
minAngle / maxAngle / angleStep	number	-180 / 180 / 30	Angle bounds: `-180`–`180`, minimum ≤ maximum. Step: `1`–`180` degrees. `0` means unrotated.
allowPerspective	boolean	true	Allow homography verification for feature matches.
maxVariants	integer	128	Integer from `1` to `512`; caps generated rotation/scale variants. Broad ranges may be cut short by this budget.
debug	boolean	false	Save an annotated image under the scripts directory as `Debug/findImage-HHmmss-Debug.PNG`.

Result field	Shape / meaning
`center`	`{x = number, y = number}`; use `match.center.x` and `match.center.y` to tap.
`corners`	Four `{x = number, y = number}` points around the detected target.
`rectangle`	`{x = number, y = number, width = number, height = number}` bounding box.
`confidence`	Match score from `0` to `1`, not a probability of correctness.
`scale`, `rotation`	Estimated scale relative to the target and rotation in degrees.
`method`	Matcher used, useful for diagnostics.
`inliers`, `inlierRatio`, `reprojectionError`	Feature-verification diagnostics; not meaningful for every method.

Parameter	Type	Specification	Optional	Default
targetImagePath	string	Target image path. Absolute paths start with `/`; other paths are relative to the current script.	NO
count	integer	Non-negative integer. Local results are capped at 100, including when `0` requests all matches; `nil` uses the default.	YES	1
threshold	float	Matching threshold in `(0, 1]`. Values ≤ `0.0001` or > `1` reset to `0.9`; non-finite values raise an error.	YES	0.9
region	table	`{x, y, width, height}` search region; `nil` searches the whole screen.	YES	Whole screen
debug	boolean	Produce an image ending in `-Debug.PNG` with matching areas marked.	YES	false
method	integer	Compatibility preset: `1` color template, `2` automatic, `3` SIFT, `4` ORB, `21` luminance template. Cloud methods `11` and `12` run only when explicitly requested.	YES	`1` (always local)

Parameter	Type	Specification	Optional	Default
filePath	string	Where to save the image.	YES	"AutoTouch" album of iOS Photo Library
region	table	You make a screenshot of the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. {100,100,200,200} is an example. If you do not want to specify the area, just input nil.	YES	nil

Parameter	Type	Specification
message	string	Content to be showed.
delay	integer	How long time to keep showing, default is 2 seconds.

Parameter	Type	Specification
audioFile	string	Absolute path of audio document.
times	integer	Additional loops: `0` (default) plays once, `1` plays twice, `-1` repeats indefinitely.

Return	Type	Specification
width	Integer	Width of screen resolution.
height	Integer	Height of screen resolution.

Return	Type	Specification
R	Integer	Red color value.
G	Integer	Green color value.
B	Integer	Blue color value.

Parameter	Type	Specification	Optional	Default
controls	table	Array of self-defined controls. You can now use these dialog box controls.	NO
orientations	table	Orientations that dialog can be, see Types of orientations.	YES	auto

Parameter	Type	Specification
filePath	string	Path starts with "/" is a absolute path, otherwise it's a relative path.
on	boolean	Switch auto launch on or off, true means on, false means off.

Field	Type	Default	Meaning
method	integer	`OCR_METHOD.IOS_VISION`	`IOS_VISION` (`1`) is local; `AI_CLOUD` (`2`) explicitly sends the image/region to the remote service. `TESSERACT_LOCAL` (`3`) is unavailable and raises an error.
image	string	current screen	Image file path, relative to the script or absolute.
region	table	whole image/screen	`{x, y, width, height}` in source pixels.
timeout	integer	10	Recognition timeout in seconds, from `1` to `300`.
debug	boolean	false	Enable recognition diagnostics.
languages	table	`{"en-US"}`	Vision language strings, in priority order. Supported languages depend on iOS.
customWords	table	none	Vision: additional words to aid recognition.
minimumTextHeight	number	system default	Vision: minimum text height as a fraction of the searched image height, in `(0, 1]`.
level	integer	0	Vision: `0` for accurate recognition, `1` for fast recognition.
correct	boolean	false	Vision: enable language correction.
lang	string	service default	Cloud language code(s), such as `"eng"`. This differs from Vision's `languages` array.
whitelist / blacklist	string	none	Cloud character filters.

Parameter	Type	Specification	Optional	Default
filePath	string	A path starting with "/" is an absolute path; otherwise it is relative to the running script directory.	NO
fireTime	string or integer	When the timer should trigger. An integer means "after N seconds from now"; a string is an absolute datetime in the format "2019-09-17 08:12:52".	NO
repeat	boolean	Whether the timer should repeat.	YES	false
interval	integer	Repeat interval in seconds. Required (must be > 0) when `repeat` is true.	YES	0

Parameter	Type	Specification	Optional	Default
filePath	string	File relative path or absolute path	NO
albumName	string	Album name	YES

Return	Type	Specification
width	Integer	Screen width in points.
height	Integer	Screen height in points.

Parameter	Type	Specification	Optional	Default
func	function	Called on each iteration. Its return value is only used when `exit` is true.	NO
interval	number	Delay between iterations, in milliseconds.	YES	1000
exit	boolean	If true, stop once `func` returns a truthy value.	YES	false

Parameter	Type	Specification	Optional	Default
color	Integer	The color to search for.	NO
count	Integer	How many matches to find (0 = all).	NO	0
region	table	Restrict search to `{x, y, width, height}`, or nil.	NO	nil
func	function	Called with the found locations on each iteration.	YES	nil
interval	number	Delay between iterations, in milliseconds.	YES	1000
exit	boolean	Stop once the color is found.	YES	false

Parameter	Type	Default	Meaning
appIdentifier	string	required	App bundle identifier.
timeoutSeconds	number	30	Finite number in `(0, 300]`; sets the retry budget at approximately two attempts per second. Individual app-launch calls can add time.

# Lua Guide

# Usage

# Quick start

# API map

# Paths and packages

# Lua basics

# Coordinate, Size and Orientation System

# Extension Libraries

# LuaCURL

# LuaSocket

# LuaSec

# LuaSqlite3

# json.lua

# Plist

# Penlight

# LuaFileSystem

# WebSocket

# Extension Functions

# touchDown(id, x, y)

# touchMove(id, x, y)

# touchUp(id, x, y)

# keyDown(keyType)

# keyUp(keyType)

# unlockScreen([passcode]) 8.6+

# nativeUnlockScreen() 8.6+

# getColor(x, y)

# getColors(locations)

# findColor(color, count, region, debug, rightToLeft, bottomToTop)

# findColors(colors, count, region, debug, rightToLeft, bottomToTop)

# findImage(options)

# screenshot(filePath, region)

# appRun(appIdentifier)

# appKill(appIdentifier)

# appState(appIdentifier)

# rootDir()

# currentDir()

# botPath()

# usleep(microseconds)

# log(content)

# alert(message)

# toast(message, delay)

# vibrate()

# playAudio(audioFile, times)

# stopAudio()

# getOrientation()

# getScreenResolution()

# getSN()

# getVersion()

# frontMostAppId()

# frontMostAppOrientation()

# intToRgb(intColor)

# rgbToInt(r, g, b)

# copyText(text)

# clipText()

# inputText(text)

# dialog(controls, orientations)

# clearDialogValues(script)

# openURL(urlString)

# isLicensed()

# setAutoLaunch(scriptPath, on)

# listAutoLaunch()

# stop()

# ocr(options)

# appInfo(appIdentifier)

# setTimer(scriptPath, fireTime, repeat, interval)

# removeTimer(scriptPath)

# keepAutoTouchAwake(keepAwake)

# saveToSystemAlbum(filePath, albumName) 8.1.1+

# clearSystemAlbum(albumName) 8.1.1+

# execute(command)

# getLocalIP() 8.2.2+

# getScreenSize()

# getScreenScale()

# getScreenBitDepth()

# tap(x, y)

# keyPress(keyType)

# lockScreen()

# findColorTap(color, count, region)

# findColorsTap(colors, count, region)

# findImageTap(imagePath, count, threshold, region, debug, method)

Parameter	Type	Specification	Optional	Default
filePath	String	Output text file path.	NO
region	table	`{x, y, width, height}` region, or nil for the whole screen.	YES	nil
rgb	boolean	Write colors as `r,g,b` instead of a single integer.	YES	false
coordinates	boolean	Include the `x,y` of each pixel.	YES	false

Parameter	Type	Specification	Optional	Default
imagePath	String	Source image path.	NO
filePath	String	Output text file path.	NO
region	table	`{x, y, width, height}` region, or nil.	YES	nil
rgb	boolean	Write colors as `r,g,b`.	YES	false
coordinates	boolean	Include the `x,y` of each pixel.	YES	false

Parameter	Type	Specification
str	String	The string to test.
start/ending	String	The prefix or suffix.

Parameter	Type	Specification
t / tbl	table	The table to serialize.
pretty	boolean	(`table.toString` only) Indent the output.

Value	Specification
KEY_TYPE.HOME_BUTTON	Home Button
KEY_TYPE.VOLUME_DOWN_BUTTON	Volume – Button
KEY_TYPE.VOLUME_UP_BUTTON	Volume + Button
KEY_TYPE.POWER_BUTTON	Power Button

Value	Specification
CONTROLLER_TYPE.LABEL	Text label
CONTROLLER_TYPE.INPUT	Single-line input box
CONTROLLER_TYPE.PICKER	Picker (choose from options)
CONTROLLER_TYPE.SWITCH	Switch (on/off)
CONTROLLER_TYPE.BUTTON	Button
CONTROLLER_TYPE.REMEMBER	Switch to remember user inputs
CONTROLLER_TYPE.TEXTVIEW	Multi-line text view

Value	Specification
ORIENTATION_TYPE.UNKNOWN	Unknown orientation. Practical value is 0.
ORIENTATION_TYPE.PORTRAIT	Portrait screen. Home button is at the bottom. Practical value is 1.
ORIENTATION_TYPE.PORTRAIT_UPSIDE_DOWN	Upside-down portrait screen. Home button on the top. Practical value is 2.
ORIENTATION_TYPE.LANDSCAPE_LEFT	Landscape left screen. Home key is on the right. Value is 3.
ORIENTATION_TYPE.LANDSCAPE_RIGHT	Landscape right screen. Home key is on the left. Value is 4.

Value	Specification
OCR_METHOD.IOS_VISION	Local OCR using iOS Vision; requires iOS 13 or later. Value `1`. No automatic cloud fallback.
OCR_METHOD.AI_CLOUD	Use the remote AI service (Tesseract-based) to perform OCR. Requires a network connection and license. Practical value is 2.
OCR_METHOD.TESSERACT_LOCAL	Reserved compatibility value `3`; unavailable in current builds and raises an error. Does not fall back to cloud OCR.