← tapforge.app

Script API

All functions available in the Script tab — QuickJS / ES2020

JavaScript Environment

Scripts run in QuickJS — a full ES2020 engine. Standard built-ins work as expected:

Math.random()                        // random float 0–1
Math.floor(Math.random() * 6) + 1   // random int 1–6

Date.now()                           // Unix timestamp in ms
new Date().getHours()                // current hour (0–23)

parseInt("42px")                     // → 42
parseFloat("3.14")                   // → 3.14

JSON.stringify({ a: 1 })             // → '{"a":1}'
JSON.parse('{"a":1}')                // → { a: 1 }

[1, 2, 3].map(x => x * 2)
"hello".toUpperCase()

Modern syntax is supported: let/const, arrow functions, destructuring, template literals, spread, optional chaining (?.), and try/catch.

Not available:

  • setTimeout / setInterval — use wait(ms) instead
  • fetch / XMLHttpRequest — no network access
  • console.log — use print() instead
  • require() / import — no module system

Input

tap(objectName, threshold?)

Finds an object on screen by image matching and taps its center.

  • objectName string — name of the UI object defined in the visual editor
  • threshold number — minimum match confidence 0.0–1.0 (default: 0.55)

Returns boolean — true if the object was found and tapped

tap("play_button");
tap("enemy_icon", 0.7); // stricter match

tapStatic(objectName)

Taps the fixed center of an object's bounding box without performing image matching.

  • objectName string — name of the UI object

Returns boolean — true if the tap was dispatched successfully

tapStatic("menu_icon");

tapXY(x, y)

Taps at exact screen coordinates.

  • x number — horizontal position in pixels
  • y number — vertical position in pixels

Returns boolean — true if the tap was dispatched successfully

tapXY(540, 960);

swipe(x1, y1, x2, y2, duration?)

Performs a swipe gesture from one point to another.

  • x1, y1 number — start coordinates
  • x2, y2 number — end coordinates
  • duration number — gesture duration in ms (default: 300)

Returns void

swipe(100, 500, 100, 200, 400); // swipe up

longPress(x, y, duration?)

Holds a finger at the given coordinates.

  • x, y number — coordinates to press
  • duration number — hold duration in ms (default: 500)

Returns void

longPress(300, 600, 1000);

pinch(cx, cy, amount, duration?)

Performs a zoom or pinch gesture around a center point.

  • cx, cy number — center of the gesture
  • amount number — positive = zoom in, negative = zoom out (pixel span delta)
  • duration number — gesture duration in ms (default: 300)

Returns void

pinch(540, 960, 200, 400);  // zoom in
pinch(540, 960, -200, 400); // zoom out

keyEvent(keyCode)

Sends an Android key event.

  • keyCode number — Android KeyEvent constant (e.g. 4 = Back, 3 = Home)

Returns void

keyEvent(4); // press Back

inputText(text)

Types text into the currently focused field.

  • text string — text to type

Returns void

inputText("Hello world");

Timing

wait(ms)

Pauses execution for the given number of milliseconds.

  • ms number — duration to wait

Returns void

wait(1000); // wait 1 second

Screen Reading

visible(objectName, threshold?)

Checks whether a UI object is currently visible on screen using image matching.

  • objectName string — name of the UI object
  • threshold number — minimum match confidence 0.0–1.0 (default: 0.55)

Returns boolean — true if found on screen

if (visible("error_dialog")) {
  tap("close_btn");
}
if (visible("rare_item", 0.8)) {
  tap("rare_item");
}

ocr(regionName)

Reads text from a named screen region using OCR.

  • regionName string — name of the region object defined in the visual editor

Returns string — recognized text, or "" if nothing was read

var score = ocr("score_region");
print("Score: " + score);

readColor(x, y)

Reads the color of a single pixel.

  • x, y number — pixel coordinates

Returns string — hex color string in the format "#RRGGBB"

var color = readColor(540, 100);
if (color === "#FF0000") {
  print("Red pixel detected");
}

findText(query)

Searches the screen for the first occurrence of the given text using OCR.

  • query string — text to search for

Returns {x: number, y: number} | null — center coordinates of the match, or null if not found

var pos = findText("Start");
if (pos !== null) {
  tapXY(pos.x, pos.y);
}

findTextAll(query)

Searches the screen for all occurrences of the given text using OCR.

  • query string — text to search for

Returns Array<{x: number, y: number}> — array of center coordinates for every match (empty array if none found)

findTextAll("Delete").forEach(function(m) {
  tapXY(m.x, m.y);
  wait(300);
});

getPos(objectName, threshold?)

Finds a UI object by image matching and returns its screen position without tapping it.

  • objectName string — name of the UI object
  • threshold number — minimum match confidence 0.0–1.0 (default: 0.55)

Returns {x: number, y: number} | null — center coordinates of the match, or null if not found

var pos = getPos("enemy_icon");
if (pos !== null) {
  tapXY(pos.x + 50, pos.y); // tap slightly to the right
}

waitForObject(objectName, options?)

Blocks until the given object appears on screen or the timeout elapses.

  • objectName string — name of the UI object
  • options object — optional settings:
    • timeout number — max wait time in ms (default: 5000)
    • interval number — polling interval in ms (default: 500)
    • threshold number — minimum match confidence 0.0–1.0 (default: 0.55)

Returns boolean — true if the object appeared within the timeout

waitForObject("spinner");
waitForObject("spinner", { timeout: 10000 });
waitForObject("spinner", { threshold: 0.8 });
waitForObject("spinner", { timeout: 10000, interval: 250, threshold: 0.7 });

Match Iteration

forEachMatch(objectName, threshold?)

Finds all image matches of a UI object on screen by template matching.

  • objectName string — name of the UI object
  • threshold number — minimum match confidence 0.0–1.0 (default: 0.55)

Returns Array<{x: number, y: number}> — array of center coordinates for every match (empty array if none found)

var matches = forEachMatch("item_icon");
for (var i = 0; i < matches.length; i++) {
  tapXY(matches[i].x, matches[i].y);
  wait(200);
}
Note: nextMatch(), tapCurrentMatch(), and ocrCurrentMatch() are used internally by the visual editor's generated code and do not need to be called in handwritten scripts.

Variables

Variables persist across steps and are shared with the visual editor's variable panel.

setGlobalVar(name, value)

Sets a named variable.

  • name string — variable name
  • value any — value to store (stored as a string internally)

Returns void

setGlobalVar("counter", 0);
setGlobalVar("counter", Number(getGlobalVar("counter")) + 1);

getGlobalVar(name)

Gets the value of a named variable.

  • name string — variable name

Returns string — the stored value, or "0" if the variable has not been set

var count = Number(getGlobalVar("counter"));
if (count >= 10) {
  print("Done");
}

Utilities

print(text)

Displays a message in the macro status / log output.

  • text string — message to display

Returns void

print("Step reached: " + getGlobalVar("counter"));

startMacro(id)

Runs another macro synchronously by its ID. The called macro runs to completion before this script continues.

  • id string — the macro's internal ID

Returns boolean — true if the macro was found and started

startMacro("abc-123-def");

Tips

  • All screen-capture calls (tap, visible, ocr, findText, …) briefly hide the overlay to take a clean screenshot.
  • Coordinates are in physical screen pixels. Use tapXY when you know exact positions, tap when you want image-based matching.
  • getGlobalVar always returns a string — wrap with Number(...) before doing arithmetic.
  • findTextAll and forEachMatch serve the same looping purpose but use different detection methods: OCR vs. image template matching.
  • visible() and ocr() can be combined freely: if (visible("a") && ocr("b") === "ready").
  • Standard JS built-ins (Math, Date, JSON, Array, …) are fully available.