Template Matching

When you call findAndTap, getPosition, or getPositions, TapForge slides your saved template image across the screen and computes a similarity score at every position. The best-scoring location is returned as the match.

What does confidence mean?

It's a similarity score from 0.0 to 1.0 — not a probability. A score of 1.0 would be a pixel-perfect match; 0.70 (the default threshold) is a good general-purpose cutoff. In practice:

• 0.85 and above — reliable match, very unlikely to be a false positive
• 0.70–0.84 — good match, works well for most UI elements
• 0.65–0.69 — uncertain; may be correct but worth increasing the threshold if you're seeing mismatches
• below 0.65 — almost always noise or a partial coincidental overlap

Why isn't it finding my object?

The most common causes:

• Threshold too high — if the game renders the element slightly differently at runtime (different brightness, anti-aliasing, compression), the score may land just below your threshold. Try lowering it to 0.65 and check what confidence getPosition actually returns.
• Template captured at the wrong scale — if you recorded the template on a different device and adaptive scaling is off, the element may appear at a different size on screen. Enable adaptive scaling or re-capture the template on the target device.
• Template is too small — templates narrower or shorter than ~28 px after scaling don't contain enough pixels for a reliable score. Use a larger crop, or zoom in on the element before capturing.
• Background noise in the template — if the template includes surrounding UI (other buttons, background art), those pixels compete with the actual element you want. Use the segmentation tool in the editor to cut the background away.

Why is getPositions returning fewer matches than I expect?

Two filters run after matching to remove noise:

• Duplicate removal: if multiple hits cluster around the same position on screen, only the highest-scoring one is kept. This prevents a single object from appearing in the results more than once — it does not remove distinct objects that happen to have similar confidence scores.
• Gap filter: results are sorted by confidence. If there is a significant drop between two consecutive scores — for example 0.75, then 0.60 — everything from the drop downward is cut off. The idea is that a large gap separates real matches from weaker, likely-accidental hits. If you're losing matches you believe are genuine, lower your threshold so those items score higher and fall above the gap.

// Example: two identical icons on screen
// If one scores 0.81 and the other 0.62, the gap filter
// may discard the 0.62 hit. Lower the threshold to confirm:
var matches = getPositions("icon", { threshold: 0.55 });
print("found:", matches.length);
matches.forEach(function(m) { print(m.score); });

Does it work across different screen sizes?

Yes. Matching is attempted across a range of scales so a template captured on one device can still be found on a device with a different screen density. For best results, enable adaptive scaling in the macro settings — this tells the matcher the likely scale range up front and improves both accuracy and speed.