Image Search & Matching

Troubleshoot in the following order:

1. Is the target actually on screen? The target image must be visible at runtime. If it's obscured, off-screen, or hasn't loaded yet, it can't be found.
2. Debug with "Match Test" in Image Manager! This is the best way to troubleshoot: open the Image Manager tab, select the image, and click the "Match Test" button. It captures the screen in real time and shows whether each of the three modes (grayscale / perceptual luminance / color) can find it, and you can adjust the threshold to observe the effect.
3. Is the template image accurate? Re-capture the template: in the node configuration, click the capture button and precisely select the target (don't include extra background).
4. Is the matching threshold too high? The default is 0.85. If the view changes slightly (anti-aliasing, animation), try lowering it to 0.75–0.80.
5. Is the search region restricting the range? If you've set a region, the target must be inside it. If unsure, leave the region unset (empty = full-screen search).
6. Has the resolution changed? If you switched computers or changed the scaling, you'll need to re-capture the template or recalibrate the run region.
7. Is the matching mode appropriate? Compare the results of the three modes in Match Test and choose the one that matches successfully.

Debugging tip: turn on "🔴 Click Visualization" in the toolbar. While running, you can see where MacroAI actually clicks (red dots), which helps you tell whether it "didn't find it" or "found it but clicked the wrong spot".

The matching threshold (threshold) controls "how similar is similar enough to count as a match", ranging from 0 to 1:

• 1.0 = must be pixel-perfect identical (nearly impossible to achieve)
• 0.85 = default value, suitable for most scenarios
• 0.70–0.75 = loose matching, suitable for views with slight variations
• Below 0.60 = too loose, may falsely match unrelated areas

Recommendations:

• Generally, keep the default of 0.85
• If the target has animation effects, translucency, or lighting changes → lower to 0.75
• If you get frequent false matches (finding the wrong position) → raise to 0.90
• Don't go below 0.65, or reliability will be poor

The three modes determine "how two images are compared for similarity":

• Grayscale (grayscale) — looks only at shape and brightness, completely ignoring color. Fastest, and insensitive to color changes.
  👉 Use this for 80% of scenarios: locating buttons, icons, and UI elements.
  ℹ️ Grayscale mode works best for images that "can be distinguished by shape alone, without looking at color".
• Perceptual luminance (perceptual) — also looks only at brightness, but is more sensitive to dark areas (the human eye is more sensitive to differences in dark regions).
  👉 If grayscale mode matches dark targets inaccurately, try this one.
• Color (color) — compares both shape and color. A red button and a blue button will be distinguished.
  👉 Use it when you need to tell colors apart: finding a red health bar, finding a green button, distinguishing markers of different colors.

Simple selection guide:

• Target is distinguishable by shape alone (doesn't rely on color) → grayscale (fastest and most stable)
• Target color changes (highlight / grayed out / reskinned) → grayscale
• You must rely on color to distinguish different targets → color
• Grayscale matches dark targets inaccurately → perceptual luminance

The quality of your template image directly determines the match success rate. Key tips:

• Select the target precisely — select only the target itself, without extra background. For example, if you're finding a button, select just the button, not the blank space around it.
• Avoid including dynamic content — don't capture parts that change (numbers, countdowns, animation frames). If a button has changing text on it, capture only the button's border/icon portion.
• Capture in the normal state — capture while the game/program is running normally, not while paused, loading, or in a special state.
• Don't capture too small — images that are too small (e.g. 10×10 pixels) lack distinctive features and are prone to false matches. Generally use at least 30×30.
• Don't capture too large — images that are too large include too much background, and the match will fail if the target shifts even slightly.

Common mistakes: capturing the mouse cursor, capturing changing numbers, or having the selection include translucent edges.

The Find Image node has a built-in "click after found" option. When enabled, it automatically clicks once the image is found. Three click targets:

• Match position (the found image) — clicks the center of the found image. Most common, e.g. "find the Start button and click it".
• Specified coordinates — after finding the image, clicks a different coordinate you've preset. Suited for "when a certain marker appears, click the spot next to it".
• Specified image — after finding image A, clicks the position of another image B. Suited for "after a confirmation dialog appears, click the OK button".

If "click after found" is not enabled, the node only performs the search and stores the result in a variable, so you can use a condition to decide the next action.

These two parameters control "what to do when it's not found":

• Timeout = 0 (default): search only once. If found, continue; if not found, immediately treat it as failed and move to the next node.
• Timeout > 0 (e.g. 5000 ms): search repeatedly, once every "interval" milliseconds, until it's found or the timeout is exceeded.

Interval (e.g. 200 ms): how long to wait between searches. Too small wastes CPU; too large reacts slowly. Generally 200–500 ms is fine.

Use cases:

• Waiting for loading to finish → set timeout to 10000 (10 s), interval to 500, and continue once the "loading complete" image is found
• Checking whether a certain button exists → set timeout to 0; a single search is enough

The search region limits the search range of image search. When set, it only searches within that rectangular area and completely ignores everything outside.

Not set (empty) = search the entire design region (usually full screen).

When should you set it?

• The target can only appear in a fixed position (e.g. the health bar is always in the top-left) → setting a region speeds up the search
• There are multiple similar patterns on screen and you only want the one in a specific position → use a region to rule out interference
• Full-screen search is too slow (high resolution + large template) → shrink the region to improve performance

When shouldn't you set it?

• The target position isn't fixed (e.g. a randomly appearing popup) → don't restrict the region
• You're unsure where the target is → leave it unset at first; once you confirm it can be found, add a region to optimize performance

Multi-image mode lets a single node search for multiple different template images at once. It counts as a success if any one of them is found.

Typical scenarios:

• The same button looks different in different states (normal / hover / pressed) → capture three images and click when any one matches
• The target looks different under different skins/themes → capture one image per theme
• You want to act when any one of several different targets appears → e.g. "click OK whether a 'Victory' or 'Defeat' dialog appears"

How to use: in the node configuration, click the "+" next to the template image to add multiple images. Set the search mode to "multi-image search".

Matching order: it tries them one by one from top to bottom of the list; the first successful match is used as the result.

When it finds something but clicks the wrong spot, it's usually caused by inconsistent coordinate systems or matching a similar image:

• Matched a similar image — the interface contains a visually similar image that looks obviously different to you but still got matched. This is very likely caused by grayscale mode, which ignores color and only considers shape similarity. → Solution: try switching to color matching mode.
• Run region not calibrated — image search found the target on the "current screen" (returning screen coordinates), but if the coordinate strategy applies additional conversion when clicking, it will be offset.
  → Solution: calibrate the run region to make sure the relationship between the design region and run region is correct.
• Click target is set to "specified coordinates" — the coordinates you entered are design coordinates, but the actual run may require an offset.
  → Solution: confirm the coordinate strategy is correct, or switch to "match position" to click the found image directly.

How to debug: turn on "🔴 Click Visualization" and observe the red dot's position. If the red dot is in the right place but the actual click is offset → it's a coordinate strategy/calibration issue. If the red dot itself is in the wrong place → it may have matched a similar image; try switching the matching mode.