Search Regions

A search region is a rectangle that limits where TapForge looks for a template. Pixels outside the rectangle are not examined at all — only the area inside is searched.

Why use one?

• Speed — matching a 300×400 px region is much faster than scanning a full 1080×2400 screen, especially when adaptive scaling is on and many scale levels are being tried.
• Avoiding false matches — if the same icon appears in multiple places on screen (e.g. a resource icon in both the HUD and in a shop panel), constraining the search to the relevant area prevents the wrong one from being returned.

Two levels: scene and object

Search regions can be set at two levels:

• Scene-level — applies to every object in the scene that doesn't have its own region. Useful when your whole scene is confined to one panel or area of the screen.
• Object-level — set on an individual object and overrides the scene-level region for that object only. Use this when most objects share a region but one needs a different area.

The precedence is: object-level → scene-level → full screen (no region).

It's a hard boundary — no fallback

If you set a search region and the element appears outside it, the match returns nothing. There is no automatic fallback to a full-screen search. The editor warns you if an object's bounding box sits outside its own configured region, which would cause it to never be found.

Search regions are scaled cross-device

Regions configured in the editor are stored in the screenshot's pixel space and scaled to the current device's screen dimensions at runtime — the same way the automatic pyramid widening works. You don't need to reconfigure them when running the same macro on a different device.

Overriding the region from a script

You can pass a region option to almost any visual search function — including getPosition, getPositions, findAndTap, findColor, findAllText, and waitForObject — to override whatever region is configured for that object. The coordinates must be in the current device's pixel space (no automatic scaling is applied to JS-supplied regions).

// Only search the top half of the screen
var pos = getPosition("coin_icon", { region: new Region(0, 0, 1080, 1200) });

// Different region per call
var inShop  = getPosition("buy_button", { region: new Region(200, 800,  680, 600) });
var inChest = getPosition("buy_button", { region: new Region(200, 1500, 680, 600) });

// findAndTap also accepts region
findAndTap("confirm", { region: new Region(300, 900, 480, 300) });

An override is only active for that single call. It doesn't change the region saved in the scene and has no effect on subsequent calls.

Cross-device regions with Region.fromScene()

To define a search region that automatically scales to the current device's resolution, use Region.fromScene(sceneName). This creates a Region from a bounding box you've drawn and saved in the visual editor, and scales it to the current screen size at runtime.

// Get the "shop_area" bounds as drawn in the editor, scaled to this device
var shopArea = Region.fromScene("shop_area");
if (shopArea) {
  var pos = shopArea.find("buy_button");
}