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().find("next_button");

region.find(objectName, options?)

Finds an image template within this region.

region.findAll(objectName, options?)

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

region.ocr()

Extracts all text directly inside this region's boundaries.

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.findColors(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 findColors().

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 true when found, or false on timeout.

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

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