Tips

Practical advice for writing reliable scripts

Coordinates are in physical screen pixels. Use tapAt(x, y) when you know exact positions, findAndTap when you want image-based matching, and tapAt("name") to tap an object's stored center without searching.
Coordinate convention: Region objects always use the top-left corner and operate in current screen pixel space. Match objects returned by search functions expose both cx/cy (center) and x/y/w/h (bounding box, top-left origin) — since Match extends Region, you can chain further searches directly on a match result.
Coordinate portability: raw coordinates (tapAt(x, y), swipe, longPress) are device-specific — they hit the same pixel regardless of screen size or density, which is rarely the right position on another device. Apps also don't scale their UI elements proportionally to resolution, so no coordinate-scaling formula is reliably accurate. For macros you intend to share, prefer image-matching (findAndTap, getPosition) or named objects (tapAt("name")).
findText("x") is a shortcut for findAllText("x")[0] ?? null — use it when you only need the first match.
getGlobalVar returns the value with its original type — no Number() or String() wrapper needed. Objects and arrays must be stored via JSON.stringify and parsed back with JSON.parse.
findAllText and getPositions serve the same looping purpose but use different detection methods: OCR vs. image template matching.
getPosition() and ocr() can be combined freely: if (getPosition("a") !== null && ocr("b") === "ready").
Standard JS built-ins (Math, Date, JSON, Array, …) are fully available.
Use spawnThread to separate vision work (slow, ~100–200 ms) from motor control (fast, ~20 ms) — the background thread updates globals, the main thread reads and acts.