Regions & Advanced Matching

new Region(x, y, w, h)

Creates a new rectangular Region with precise coordinates in current device pixels.

// Create a region in the top left corner, 200px wide and 100px high
var r = new Region(0, 0, 200, 100);

Region.fromScene(sceneName)

Creates a region based on a bounding box drawn and saved in the visual editor. This is automatically scaled to the current device's screen size.

// Get the bounds of the minimap as defined in the editor
var minimap = Region.fromScene("minimap_area");

Region.fullscreen()

Returns a Region that encompasses the entire device screen.

region.expand(pixels) / region.inset(pixels)

Returns a new Region expanded or shrunk by the given number of pixels in all directions. Useful for giving a search some "breathing room".

var r = Region.fromScene("health_bar").expand(20);

region.offset(dx, dy)

Returns a new Region shifted by the given x and y offsets. Useful for finding an element relative to a known landmark.

var titleMatch = Region.fullscreen().findText("Score:");
if (titleMatch) {
  // Read the score directly to the right of the title text
  var scoreText = titleMatch.offset(100, 0).ocr();
}

region.topHalf() / region.bottomHalf() / etc.

Quick geometry helpers that slice the current region in half. Includes topHalf(), bottomHalf(), leftHalf(), and rightHalf().

// Optimizes performance by only searching the bottom half of the screen
var btn = Region.fullscreen().bottomHalf().findObject("next_button");

region.findObject(objectName, options?)

Finds an image template within this region.

region.findAllObjects(objectName, options?)

Finds all instances of an image template within this region, returning an Array of Match objects.

region.ocr(options?)

Extracts all text directly inside this region's boundaries. Pass { numeric: true } to read it as a number (digit-confusion correction) or { binarize: true } to force thresholding — same options as the global ocr().

Returns string | null — recognized text; "" when the region was read successfully but holds no text; or null when the read failed (capture or OCR-engine error). The ""-vs-null split lets you tell "nothing there" (don't retry) from "couldn't read" (safe to retry).

region.findText(query, options?)

Finds specific text within this region.

region.findColor(colorHex, options?)

Finds the first pixel matching the given color within this region.

region.findAllColors(colorHex, options?)

Finds all pixels matching the given color within this region, returning an array of Match objects. Accepts the same tolerance and maxResults options as the global findAllColors().

region.findColorRegions(colorHex, options?)

Groups adjacent matching pixels within this region into connected blobs, returning one Match per blob (bounding box + centroid). Accepts the same tolerance, minSize and maxResults options as the global findColorRegions().

region.findAllText(query, options?)

Finds all occurrences of the given text within this region via OCR, returning an array of Match objects. Accepts the same wholeWord option as the global findAllText().

region.waitForObject(objectName, options?)

Waits until an image template appears within this region. Equivalent to the global waitForObject() with a pre-scoped region. Returns a Match on success, or null if the timeout is reached.

var panel = Region.fromScene("inventory_panel");
var item = panel.waitForObject("rare_sword", { timeout: 10000 });
if (item) item.tap();

region.waitForText(query, options?)

Waits until the given text appears within this region via OCR. Returns a Match at the found text on success, or null on timeout. A returned Match is truthy, so if (region.waitForText(…)) checks keep working.

var dialog = Region.fromScene("dialog_box");
if (dialog.waitForText("Are you sure?", { timeout: 8000 })) {
  tapAt("confirm_button");
}

region.waitUntilGone(objectName, options?)

Waits until an image template disappears from this region. Returns true once gone, or false on timeout. Accepts the same options as region.waitForObject().

var loadingRegion = Region.fromScene("loading_spinner");
loadingRegion.waitUntilGone("spinner", { timeout: 15000 });

region.waitUntilTextGone(query, options?)

Waits until the given text disappears from this region via OCR. Returns true once gone, or false on timeout.

var statusBar = Region.fromScene("status_bar");
statusBar.waitUntilTextGone("Loading...", { timeout: 10000 });

region.waitForColor(colorHex, options?)

Waits until a pixel matching the given color appears within this region. Equivalent to the global waitForColor() with a pre-scoped region. Returns a Match (1×1, at the found pixel) on success, or null on timeout.

var bar = Region.fromScene("health_bar");
var low = bar.waitForColor("#FF0000", { tolerance: 20, timeout: 10000 });
if (low) print("health dropped into the red");

region.waitUntilColorGone(colorHex, options?)

Waits until no pixel matching the given color remains within this region. Returns true once gone, or false on timeout. Accepts the same options as region.waitForColor().

var indicator = Region.fromScene("loading_dot");
indicator.waitUntilColorGone("#FF0000", { tolerance: 20, timeout: 15000 });

region.highlight(durationMs?, color?)

Draws a temporary visual overlay box around the region on your screen. Extremely helpful for debugging your scripts to ensure you are searching exactly where you think you are.

Region.fromScene("health_bar").highlight(2000, "#FF0000");

Match Properties

match.tap() / match.longPress(options?)

Directly taps or long presses the center coordinates (cx, cy) of the match. Each returns boolean — true if the gesture was dispatched successfully — so findObject("x")?.tap() doesn't silently discard the result.

var inventory = Region.fullscreen().findObject("inventory_panel");
if (inventory) {
  // Search for the potion STRICTLY inside the inventory panel
  var potion = inventory.findObject("health_potion");
  if (potion) {
    potion.tap(); // Taps the potion!
  }
}