Region Class

Region limits image and text searches to a rectangle.

`new Region(x, y, w, h)`

Create a region.

let region = new Region(x, y, w, h);

`region.getX()`

The region's own position and size. getWidth() and getHeight() are aliases of the last two.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.getX();
console.log(result);

`region.getY()`

The region's own position and size. getWidth() and getHeight() are aliases of the last two.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.getY();
console.log(result);

`region.getW()`

The region's own position and size. getWidth() and getHeight() are aliases of the last two.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.getW();
console.log(result);

`region.getH()`

The region's own position and size. getWidth() and getHeight() are aliases of the last two.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.getH();
console.log(result);

`region.centerX()`

The coordinates of the region's midpoint.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.centerX();
console.log(result);

`region.centerY()`

The coordinates of the region's midpoint.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.centerY();
console.log(result);

`region.centerPoint()`

That midpoint as a Point, so you can pass it straight to click().

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.centerPoint();
console.log(result);

`region.randomPoint()`

A random Point inside the region.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.randomPoint();
console.log(result);

`region.contains(x, y)`

Whether a coordinate falls inside the region.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.contains(500, 1200);
console.log(result);

`region.find(template, options?)`

Find one image match in the region. Returns a Match, or null if nothing matched, always null-check before reading .x/.y. Defaults to a 5000ms timeout, pass { timeout: 0 } for a single instant pass. Options: timeout, scanRate, minScore, fastScan, strict. template also takes an array, see below.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.find('reward', { timeout: 3000, scanRate: 5.0, minScore: 0.8, fastScan: true, strict: true });
console.log(result); // {"x":120,"y":240,"cx":145,"cy":265,"score":0.95,"template":"reward"} or null

`region.intercept(template, options?)`

Track a moving target across frames and return its predicted future position (adds vx/vy velocity fields).

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.intercept('reward', 'demo');
console.log(result);

`region.follow(template, options?)`

Grab a moving target and drag the finger to stay on it until a stop condition.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.follow('reward', 'demo');
console.log(result);

`region.findAll(template, options?)`

Find all image matches in the region.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.findAll(['reward', 'reward_alt'], { timeout: 3000, scanRate: 5.0, minScore: 0.8 });
console.log(result); // [{"x":120,"y":240,"cx":145,"cy":265,"score":0.95,"template":"reward"}, ...]

`region.waitFor(template, options?)`

Wait for a template to appear.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.waitFor('reward', { timeout: 5000, scanRate: 5.0, minScore: 0.8 });
console.log(result); // {"x":120,"y":240,"cx":145,"cy":265,"score":0.95,"template":"reward"} or null

`region.waitUntilGone(template, options?)`

Wait for a template to disappear.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.waitUntilGone('reward', { timeout: 5000, scanRate: 5.0, minScore: 0.8 });
console.log(result); // true or false

`region.exists(template, options?)`

Existence check. No options → instant single pass. Pass a timeout to keep retrying.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.exists('reward', 'demo');
console.log(result);

`region.findText(text, options?)`

Find text in the region. Single-pass by default (timeout: 0). Options: timeout, mode (exact/fuzzy/contains/regex), scanRate.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.findText('Play', { mode: 'exact', timeout: 3000, scanRate: 5.0 });
console.log(result); // {"x":120,"y":240,"cx":145,"cy":255,"text":"Play"} or null

`region.waitForText(text, options?)`

Wait for text to appear (default 5000ms timeout). Returns a MatchText or null.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
region.waitForText('Daily Reward Ready', 'demo');

`region.waitUntilTextGone(text, options?)`

Wait until text disappears. Returns true if gone, false on timeout.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
region.waitUntilTextGone('Daily Reward Ready', 'demo');

`region.readText(options?)`

Read all OCR text in the region. Returns a plain string or null.

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.readText('demo');
console.log(result);

`region.clickText(text, options?)`

Find and click text inside the region (default 5000ms timeout).

let region = new Region(0, 0, Screen.getWidth(), Screen.getHeight());
let result = region.clickText('Play', { mode: 'exact', timeout: 3000, scanRate: 5.0 });
console.log(result); // true or false

Example:

let toolbar = new Region(0, 0, 1080, 260);
let closeBtn = toolbar.find("close_icon", { timeout: 2000 });
if (closeBtn) closeBtn.click();

Searching for several templates at once

Every method above that takes a template also accepts an array of them: find, findAll, waitFor, waitUntilGone, exists, intercept and follow. The Screen equivalents do too, since they are the same calls scoped to the whole screen.

This is faster than calling find once per template, because all templates are checked against the same screenshot.

// Any of these three buttons, whichever is on screen
let btn = region.find(["accept", "confirm", "ok_button"], { timeout: 3000 });
if (btn) {
    console.log("matched " + btn.template);   // which one it was
    btn.click();
}

Array order is priority order. find returns the first template in the list that matched, not the highest-scoring one, so put the template you would rather have first. The .template field on the returned Match tells you which one it was.

You can mix colours into the array: an entry of the form #RRGGBB or #AARRGGBB is treated as a colour search rather than a template lookup.