No-Code Workspace — Block Reference

SearchBlock usage recipe

Color (COLOR)

Searches for a specific color on screen

Documented for app version 1.0.50Updated: October 2, 2026

What Does It Do?

Searches HEX color inside the selected region. You choose the speed/accuracy profile with the exact, tolerant, cluster, gradient and dominant engines. TRUE when found, FALSE otherwise.

Pro note: tolerance may vary across devices

In COLOR, tolerance, region size, and optional exclude regions must be tuned together. Otherwise the search may be fast but brittle.

Shared Mechanics for Search Blocks

Multiple search regions and excluded regions

IMAGE, TEXT, COLOR and the other search blocks that use the Search Regions editor can define several search regions with + Add Region; OCR_VALUE tries its read regions in order. Inside a search region, Exclude Region skips noisy areas such as a HUD or a badge, and it applies only to the search region it belongs to. From 1.0.51 one search region can hold several excluded regions, each with its own shape and its own variable or Dialog binding.Coming soonv1.0.51

Sticky anchors for edge-aware scaling

You can now assign a sticky anchor to each search region. This brings Region.sticky into the no-code surface so the region can stay aligned to anchors such as top_left, bottom_right, or center when screen geometry changes.

Scan rate, duration, and retry behavior

Search Duration (ms) defines one search window; 0 means a single look. Retry Mode in the Retry & Wait section is Off, Infinite Loop, Retry On True, Retry On False, Wait Until Found, or Wait Until Gone, so a block becomes a one-shot check, a controlled polling step, or a step that waits for a target to appear or to disappear. Retry Timeout (ms, 0 = unlimited) bounds the loop; Scan Rate (Hz) sets scans per second.

Match tuning and device variance

mScore, scale, and scan engine choices matter across themes, display sizes, and rendering differences. Smaller regions plus the right engine dramatically improve builder stability.

When to Use?

Use when color-based detection is needed:

Check if a button is active (colored) or inactive (gray)

Monitor bar/indicator color (green/yellow/red)

Check if notification badge (red dot) exists

Detect if an area has loaded by color

Much faster than IMAGE, prefer when color is sufficient

How to Use?

Add "Color (COLOR)" block

Pick a color or enter HEX (#RRGGBB); with several colours pick the Search Mode: Any / All / Sequential

SCAN REGION: Keep area narrow

SCAN ENGINE: tolerant_color is the default; the others are under Parameters

Set timeout and Scan Rate (Hz) if retry is needed

Configure TRUE/FALSE branches

Parameters

Color (HEX)

#RRGGBB format. Pick from screen or enter manually; several colours can be added

Scan Region

Area to search. Keep NARROW!

Scan Engine

exact_color needs an exact RGB match; tolerant_color (default) tolerates brightness and gamma differences; cluster_color needs a local colour cluster instead of one pixel; gradient_color uses a wider tolerance for changing bars; dominant_color needs a fully filled 3×3 patch

Scan Rate (Hz)

Attempts per second inside the retry window: 1–30 Hz; 0 = fastest

Match / Timeout / Wait

Same parameters as IMAGE; COLOR has no Scale setting

Score Variable (Advanced)

Writes the 0.0–1.0 confidence to the variable named in Advanced; COMPARE it to drop weak matches (same as IMAGE)

Match Position (matchX/Y/W/H) (Advanced)

Writes the match box into your own variables such as matchX/Y/W/H; CLICK {matchX},{matchY} to act there (same as IMAGE)

Item conditions and multiple exclusionsComing soonv1.0.51

Same as IMAGE: a Condition in each entry's lightbulb; several exclusions per region

Parameter	Description
Color (HEX)	#RRGGBB format. Pick from screen or enter manually; several colours can be added
Scan Region	Area to search. Keep NARROW!
Scan Engine	exact_color needs an exact RGB match; tolerant_color (default) tolerates brightness and gamma differences; cluster_color needs a local colour cluster instead of one pixel; gradient_color uses a wider tolerance for changing bars; dominant_color needs a fully filled 3×3 patch
Scan Rate (Hz)	Attempts per second inside the retry window: 1–30 Hz; 0 = fastest
Match / Timeout / Wait	Same parameters as IMAGE; COLOR has no Scale setting
Score Variable (Advanced)	Writes the 0.0–1.0 confidence to the variable named in Advanced; COMPARE it to drop weak matches (same as IMAGE)
Match Position (matchX/Y/W/H) (Advanced)	Writes the match box into your own variables such as matchX/Y/W/H; CLICK {matchX},{matchY} to act there (same as IMAGE)
Item conditions and multiple exclusionsComing soonv1.0.51	Same as IMAGE: a Condition in each entry's lightbulb; several exclusions per region

Example Usage

Scenario 1: Wait for button to become active

COLOR → pick button active color (e.g., green #00CC00)

Scan region: Only the button area

Retry Mode: "Wait Until Found", Retry Timeout: 5000 ms

TRUE: Button active, click with CLICK

Scenario 2: Alert when status bar turns red

COLOR → pick red (#FF0000)

Scan region: Bar area

TRUE: LOG "Red alert!" + start other actions

Combinations / Used With

MOST COMMON COMBINATIONS:

COLOR + CLICK: Click when color appears

COLOR + IMAGE: Check color first (fast), then verify with image

COLOR + WAIT: Wait for color change

COLOR + LOG: Log color status

COLOR + COMPARE: Compare color status with variable

Tip

Searches for a specific color on screen

Warnings / Cautions

WARNING:

A new block starts with #FFFFFF; remember to pick the real target colour

Same color may exist in many places — keep scan region NARROW

Screen brightness changes can affect colors

Very similar colors may mix — adjust the match ratio; exact_color ignores it

Step-by-Step Mastery: Basic → Advanced → Pro

The same block at three levels: a quick start, the real options, and professional techniques.

Basic

The COLOR block searches the scan region for a specific HEX colour (#RRGGBB). TRUE if the colour exists, FALSE otherwise. It is much faster than IMAGE and TEXT, ideal for tasks like detecting whether a button is active (coloured) or inactive (grey). Simplest use: pick the button's active colour, shrink the scan region to just that button, and add a CLICK on TRUE.

Advanced

ENGINE SELECTION (scanEngine) is the most decisive choice in this block; when to pick each: • exact_color (Exact Color) — needs an exact RGB match, and Match Ratio does not widen it. Use it only when the colour is truly constant (pure #FFFFFF, no anti-aliasing or shadow); otherwise it is the easiest engine to miss with. • tolerant_color (Tolerant Color, default) — combines per-channel and perceptual tolerance for brightness and gamma differences; the right choice for most daily work. • cluster_color (Cluster Color) — rejects an isolated pixel and requires a supported local colour cluster; the most reliable trigger for targets larger than one pixel, such as a badge, a glow or a small coloured marker. • gradient_color (Gradient Color) — uses a wider hybrid tolerance for changing bars and indicators such as a progress-bar fill. • dominant_color (Dominant Color) — requires a fully filled 3×3 local patch with a wider tolerance; it ignores thin lines and single pixels and suits solid colour areas. Lighting/anti-aliasing rule: colours drift as brightness changes, so tolerant_color + a sensible mScore is almost always more robust than exact_color. Match Ratio (mScore) tunes how close a colour must be to count. The COLOR block has no Scale setting. Timing matches IMAGE: searchTimeout = 0 is a single attempt and > 0 rescans within that window; scanRateHz = 0 is the fastest pace with a 1 ms pause between attempts, while an explicit low Hz is the battery-friendly choice. Add multiple colours (searchColors) and Search Mode (colorSearchMode) becomes "any" (Any), "all" (All) or "sequential" (Sequential, each colour with its own branch). Keep the scan region NARROW: the same colour can appear in many places on screen.

Pro

The COLOR engine does not grayscale; it is the right tool for solid/bright colours, and for luma-flat templates you should choose COLOR over IMAGE. Very similar colours (#FF0000 vs #FF0101) can blur together; to prevent this, write the confidence with scoreVar and use COMPARE matchScore >= 0.90 to reject the false match. Capture the coloured region's position with contextX/Y/W/H and CLICK {matchX},{matchY} right on it. When screen brightness changes, colours drift; tolerant_color plus a sensible mScore is more robust than a hard threshold. Doing a fast COLOR pre-filter then verifying with IMAGE builds a hybrid that is both fast and reliable.

Real-World Scenarios — Step-by-Step Recipes

Small, reproducible examples that combine several blocks — build them straight into your own macro.

Click when a button turns its active colour

1Add a COLOR block and pick the button's active colour (e.g. #00CC00) from screen
2Shrink the scan region to ONLY the button area
3Scan Engine = tolerant_color
4Retry Mode = Wait Until Found, Retry Timeout = 5000 ms
5Add a CLICK on the TRUE branch

Fast colour pre-filter + visual verify (hybrid)

1Add COLOR: search the target's dominant colour with cluster_color
2On the TRUE branch add an IMAGE block: verify the same element by template
3On IMAGE's TRUE branch perform the action with CLICK
4On COLOR's FALSE branch WAIT briefly and retry from the top

Which Blocks to Pair With — Pro Combinations

This block is useful on its own — but it shines when paired with the right partners.

+ IMAGE

Pre-filter quickly with COLOR, then verify precisely with IMAGE; since colour scanning is cheap you only run the expensive visual scan when needed.

+ CLICK (Click on Match)

When the colour is found, click the contextX/Y location or directly on the coloured area via clickOnMatch.

+ COMPARE (score)

Compare the scoreVar matchScore against a 0.90 threshold to prevent very similar colours from mixing.

+ WAIT

While waiting for an indicator to turn from green to red, WAIT inserts spacing between passes.

+ Sticky Anchor (stickyAnchor)

Because the same colour appears in many places, a tight region matters even more for COLOR; the anchor keeps that tight region on the right corner even on rotation, preventing false positives.

Common Mistakes and Fixes

Leaving the scan region wide: the same colour found elsewhere yields a false TRUE. Fix: shrink the region to only the target element.

Searching solid/bright colours with exact_color and losing the match when brightness shifts. Fix: use tolerant_color and keep mScore sensible.

Searching a luma-flat (single-colour) element with IMAGE; the grayscale matcher may reject it. Fix: use the COLOR block for such elements.

Pro Tips

cluster_color accepts a supported local colour cluster rather than an isolated pixel, so it triggers far more reliably than a single-pixel match on targets such as a glow or a red badge.

dominant_color requires a fully filled 3×3 colour patch, so it ignores thin edges and single pixels; use it to confirm a solid colour area (such as a lit status light). To watch an area's overall colour change, use the colour difference mode of MH_VISUAL_DECISION.

In any mode add both the active and warning colours, then branch with COMPARE or SWITCH_CASE on which state was caught.

Match the engine to the content: if there is anti-aliasing on an icon edge or a slight gradient, pick tolerant_color/cluster_color; reserve exact_color only for a truly pure, constant colour. The wrong engine keeps returning FALSE even on the right colour.

Coming soonv1.0.51Each colour can get a Condition from its lightbulb (same rules as IMAGE); for example, only the colour that matches the theme chosen in a Dialog is searched.

This Block's Code (Editor View)

Lua

The Lua below is what the Code Editor generates for this block with sample settings. Adding cases, branches, actions or loops, or changing settings, extends the generated code accordingly. Study it to see what the block does under the hood, to learn Lua, or to copy and adapt it. Use the Copy button (top-right) to paste it into the Code Editor, or “Try in Editor →” to run it in the live editor.

lua

Try in Editor →

Snap.screenRefresh()
local _reg2 = Region():noScale()
local m1 = (function()
 local _scanOk, _scanValue = pcall(function() return _reg2:find(Asset.color("#00FF00"):mScore(0.8), {engine="tolerant_color"}) end)
 if not _scanOk then
  _lastMatch = nil
  error(_scanValue, 0)
 end
 return _scanValue
end)()
_lastMatch = m1

Note: generated code can evolve across versions; helper names (e.g. _reg1, m1) and internal optimizations may change. The logic and the called APIs reflect the block’s behavior.

Block ↔ Lua Mapping →

Shared Controls for This Block Family

The guidance below is not identical for every block. It summarizes the professional controls that most often repeat in the selected block family.

🔎Scan Region

Keep the search close to the target. Smaller regions are faster and more stable.

🚫Exclude Region

Exclude static noise, badges, animations, or reflective areas to reduce false matches.

⏱Timeout and Scan Rate

Timeout and scan rate define whether the block acts as a single check or controlled polling step.

🎯Match Tuning

mScore, scale, and engine choice must be tuned together for theme, resolution, and rendering differences.

🧭Result Variables

OCR_VALUE writes the number it reads to its result variable (default ocr_val); TEXT writes the text it passed through its find/replace step to the Save Read Value variable (default ocr_val). In Match Variables, the score variable (0.0–1.0 confidence) and the X/Y/W/H variables carry the match confidence and position into later blocks: branch on the score with COMPARE, and in CLICK bind the coordinates to them with {x} or turn on Click on match. _lastMatch is the last match that Click on match uses; _lastOcrText is kept only for older CUSTOM_CODE scripts.

Builder vs Lua Boundary

Raw touch pointer lifecycle stays code-first

TOUCH and TOUCH_BREAK cover recipe-style touch flows. Raw pointer choreography such as Touch.down, Touch.move, Touch.up, Touch.dispatch, Touch.reset, Touch.breakAll, and Touch.releaseAfter is not exposed as a first-class builder block.

Touch.downTouch.moveTouch.upTouch.dispatchTouch.resetTouch.breakAllTouch.releaseAfter

Bounded dialog design is builder-backed; freer composition stays code-first

The DIALOG block and dialog designer cover a bounded field set in the builder: Info Text, Text Input, Checkbox, Description, Radio Group, Dropdown, Multi Select, Tab Group, Date Time, Number Range, Slider, Image Picker, Color Picker, File Picker, Recorder Picker, Tag, Signature, and Spacer. The buttons are designed too: the Positive button and Negative button tabs set each button’s text, background, and border color, corner radius, and minimum height next to a preview. Freer Setting.builder composition, multi-step wizard flows, and mixed HUD/dialog choreography still do not map 1:1 into the builder.

Coming soonv1.0.51Two more fields: Agent Detect references (agent_detect_editor) lets the user pick a saved reference set or add and edit references, and Save confirms the selection; Navigation setup editor (navigation_editor) edits a saved map, marker and route from the Dialog and returns the setup and route selection without moving the character.

Setting.builderDialogHudTextViewAgentDetectEditorNavigationEditor

Advanced HTTP request chaining stays code-first

HTTP_GET, HTTP_POST, and HTTP_PUT cover common fixed-method flows; HTTP_REQUEST covers one bounded request with method, header lines, body, content type, query parameters (GET and DELETE), timeout, and a bounded retry. These blocks never throw; they write the status code (-1 on a network failure). Cookie handling, chained request objects, and lower-level client flows still need the code editor.

Request()Request.setCookieRequest.getCookiesCUSTOM_CODE

General programming surfaces stay code-first

The MAP, LIST, JSON_PARSE, REGEX_MATCH, and METRICS blocks cover the everyday cases: map actions, a static list, reading a value from a JSON path, regex match, find, replace, and split, and metrics actions. The rest of the Map, Array, JSON, Regex, and Metrics APIs (for example Array sort, filter, and map) is broader than the builder recipe model and stays on the CUSTOM_CODE and code editor side.

MapArrayJSONRegexMetrics

Low-level runtime and Lua composition stays code-first

Runtime helpers, raw Request objects, Lua built-ins such as print/pcall/xpcall, and free-form object chaining patterns are represented through CUSTOM_CODE or the code editor.

RuntimeRequestprintpcallxpcallCUSTOM_CODE

Debug Mode and Breakpoints

Each block card now exposes an independent breakpoint toggle. When enabled, the breakpoint preference is stored with the block.

Breakpoints are only emitted into runtime code when Debug Mode is enabled from Visual Builder settings. When Debug Mode is off, breakpoints stay saved but do not pause execution.

Use ASSERT for fail-fast validation, and use breakpoints for step-by-step tracing and controlled pauses in the same flow.

Variable Scope

Variables defined with SET_VARIABLE are accessible throughout the macro (global scope). All blocks can read/write the same variable.

However, a variable defined inside a GROUP will be 'nil' (undefined) until the GROUP executes. Blocks outside the GROUP using this variable may produce unexpected results.

FOR_EACH loop variables (item and index) only carry valid values inside the loop body. Outside the loop they are outside local scope and should not be used.

TRY_CATCH error variable is only valid within the catch block. If the try block succeeds, the catch branch is not entered and the error variable remains undefined.

TIP: Before using a variable inside a GROUP, assign a default value with SET_VARIABLE outside the GROUP. This way the variable won't be nil even if the GROUP has not run.

Inline Expressions

You can embed variable values and calculations into text fields using {{ expression }} syntax. Expressions inside double curly braces are evaluated as Lua code and the result is inserted into the text.

Syntax

{{ expression }}

Examples

Skor: {{ score + 1 }} → "Skor: " .. tostring(score + 1)

{{ name }} kazandı! → tostring(name) .. " kazandı!"

X:{{ x }} Y:{{ y }} → "X:" .. tostring(x) .. " Y:" .. tostring(y)

Supported Blocks

SET_VARIABLELOGCOMPARECLIPBOARD_WRITENOTIFY_TOASTKV_SET

Security Note

Expressions are checked by the sandbox policy. Security-sensitive calls like loadstring, require, debug are automatically blocked.

General Tips

Keep scan regions as small as possible — improves speed, reduces false matches.

Always add an exit condition when using infinite loops (BREAK, timeout, or conditional exit).

Use network operations and error-prone steps inside TRY_CATCH.

If you need global error handling, use the Error Handler (ERROR_HANDLER) block as a singleton in the project.

Small coordinate offsets (CLICK/SWIPE) improve tap accuracy across different DPI and screen scales.

Customize macros with Dialog block — different parameters each run.

Define repeating steps once with GROUP_CALL, call from many places.

Cross-macro local library

Local Shared Macro Area

The Local Shared Macro Area moves blocks, variables, dialog fields, gallery assets, and imported media dependencies between macros on the same device. It is device-local, not cloud sync, not Firebase sharing, and not a replacement for public macro sharing.

Professional usage model: put a reusable login flow, common scan region, shared dialog form, variable group, template image, color profile, replay recording, or imported PLAY_SOUND media file into the shared area from one macro, then import it from the relevant + menu in another macro.

VISUAL_BLOCKSVARIABLESDIALOG_FIELDSTEMPLATE_IMAGECOLOR_SWATCHREPLAY_RECORDMEDIA_FILE

Send to the shared area

When one item or a multi-selection is active, the shared-area button can copy the selected part from the workspace, group, true/false action branch, dialog, and variables surfaces into the device-local library.

Import into another macro

The shared-area entry under the + menu imports the selected item into the surface that opened it. Main workspace, group, action branch, dialog, and variables each receive the compatible item type.

Share gallery assets

Gallery items include template images, color swatches, replay records, and imported audio/media files. They can move between macros on the same device so repeated templates, colors, recordings, and PLAY_SOUND media assets do not need to be captured again.

Keep it clean

The shared area is not a permanent dumping ground. Delete stale shared items from the shared-library panel; imports create a copy in the target macro and do not rewrite the source macro flow.

Checkpoint: after importing, review block names, linked template/image/color/record/media assets, and variable names in the target macro. The shared area creates a copy; delete stale shared items from the shared-library panel to keep the library clean.

AI assistant

Build a block chain with MH AI in natural language

Tell MH AI what you want in plain language; it proposes the right block sequence and lands it in the workspace after you approve. In the current release it works with cloud providers such as Gemini, Claude, and OpenAI; on-device local models are on the roadmap.

Learn more →