How To Call It
Region:agentDetect(macroScopeId, referenceSetId, options?) is called with a colon on a Region object; that Region is the search area unless options.searchRegions lists several areas. Requires Macro Handler 1.0.51 or later.
Object MethodScanning and DetectionComing soonv1.0.51
Region:agentDetect(macroScopeId, referenceSetId, options?)
Searches this region offline for targets that visually resemble a reference set saved by an Agent Detect block; returns a table with status (found/not_found/error), a typed code, count, selected and targets. Expected failures come back as a result instead of an error, and the call never taps by itself.
Documented for app version 1.0.51 (not on Google Play yet)Updated:
When To Use It
Use it in code-editor scripts that need the detector of an Agent Detect block: set the block up in the no-code editor first, then call region:agentDetect with the macroScopeId and referenceSetId that appear in the code it generates. The detector captures its own fresh frames, so Snap.screenRefresh() and FindParam are not needed; the Region you call it on is the search area.
Parameters and Return
macroScopeId and referenceSetId identify the reference set an Agent Detect block saved; options is an optional table read by the host, for example selection = "closest_to_center", threshold = 0.8 or maxTargets = 4. The call returns a table: status is "found", "not_found" or "error"; code is OK or a typed code such as NO_TARGET, AMBIGUOUS_TARGET, TARGET_LOST or REFERENCE_MISSING; count, selected and targets describe the detections, and nextDelayMs suggests how long to wait before the next call. Expected failures come back in this table instead of raising an error.
Options and Limits
Options the host reads: mode = "hybrid" (default), "identity", "classic" or "shape". "shape" (Shape only) finds every target with a similar body whatever its colours, cannot tell species apart and needs references saved with "Prepare colour-independent search"; otherwise r.code is MODEL_UNAVAILABLE. selection = "highest_confidence" (default), "closest_to_center", "largest", "leftmost", "rightmost", "topmost", "bottommost", "current_track", "index" (with selectionIndex) or "nearest_point" (with nearX and nearY). Also threshold, maxTargets (default 16), minStableFrames, scaleMin and scaleMax (default 0.3 and 2.2), tracking (default true), intent = "revalidate" (needs revalidateTrackId) or "verify" (needs a baseline table; without it r.code is RUNTIME_ERROR), budgetMs and excludeRegion, an area the scan skips. searchRegions = { { region = Region(...), excludeRegion = Region(...) }, ... } scans several areas, each with its own exclusion, in one call. All codes: OK; NO_TARGET, AMBIGUOUS_TARGET, TARGET_LOST (status "not_found"); CAPTURE_UNAVAILABLE, REFERENCE_MISSING, INVALID_ROI, MODEL_UNAVAILABLE, TIMEOUT, PERMISSION_REVOKED, RUNTIME_ERROR (status "error").
Best Combined With
Tap only when r.status is "found", with click(r.targets[r.selected].clickMatch); wait between calls (r.nextDelayMs is a good minimum) and log r.code on the error path. The call itself never taps, and a script tap uses the position from the frame of that call; when the target must be revalidated on a fresh frame right before the tap, use the Agent Detect block with Detect + Tap.
Example Usage
The snippet below is a starter pattern that can be applied directly in runtime flow.
-- Region:agentDetect
local region = Region()
-- The ids come from the code an Agent Detect block generates
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
elseif r.status == "error" then
print("agentDetect: " .. r.code)
endCopyable Progressive Examples
From foundation to combined usage, each level is provided as a separate code block so you can copy the level you need and adapt it directly.
-- Region:agentDetect
local region = Region()
-- The ids come from the code an Agent Detect block generates
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
elseif r.status == "error" then
print("agentDetect: " .. r.code)
endlocal stepOk = true
-- Region:agentDetect
local region = Region()
-- The ids come from the code an Agent Detect block generates
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
elseif r.status == "error" then
print("agentDetect: " .. r.code)
end
if stepOk then
wait(200)
endlocal ok, err = pcall(function()
-- Region:agentDetect
local region = Region()
-- The ids come from the code an Agent Detect block generates
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
elseif r.status == "error" then
print("agentDetect: " .. r.code)
end
end)
if not ok then
print("API step failed: Region:agentDetect: " .. tostring(err))
requestStop()
end-- Agent Detect captures its own fresh frames; the Region is the search area
local function run_agentdetect_step()
-- Region:agentDetect
local region = Region()
-- The ids come from the code an Agent Detect block generates
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
elseif r.status == "error" then
print("agentDetect: " .. r.code)
end
end
local ok, err = pcall(run_agentdetect_step)
if not ok then
toast("Step failed")
print(err)
end-- Region:agentDetect with a bounded retry loop
local region = Region()
for attempt = 1, 5 do
local r = region:agentDetect(macroScopeId, referenceSetId, { selection = "closest_to_center" })
if r.status == "found" then
click(r.targets[r.selected].clickMatch)
break
elseif r.status == "error" then
print("agentDetect: " .. r.code)
break
end
wait(math.max(250, r.nextDelayMs or 0))
end