No-Code Workspace — Block Reference

ActionBlock usage recipeComing soonv1.0.51

Navigation (NAVIGATION)

Follows an ordered route on a reference map using measured player position

Documented for app version 1.0.51 (not on Google Play yet)Updated: October 2, 2026

What Does It Do?

Tracks the player marker on the live map or mini-map and corrects joystick commands from feedback against the saved route. It needs a reference map, a live map area, a joystick area and a taught player marker, and offers two control modes: Strict with a measured calibration and Live heading tracking without one. Full-map tracking is the default; Track mini-map uses a separately taught mini-map area and marker on the same reference map. Setups and routes belong to the macro.

When to Use?

Use it to follow an ordered route you draw when your player position is clearly visible on the map, including continuing after My Agent Routine has cleared a blocker.

How to Use?

In Map and route setup, choose a saved setup or tap Create new setup.

Choose the reference map, then Select live map area and Select joystick area on the full display.

Teach player marker: crop your own marker tightly and set the position anchor and the heading tip (required for Live heading tracking).

Draw the route in travel order, name it and choose One way, Loop or Back and forth.

Choose the Control mode: Strict mode calibrates when the macro starts (with Use saved calibration, run Calibrate movement first); Live heading tracking needs no calibration.

Check the setup with Observe without moving, then run it with a short duration limit.

Parameters

Map setup

Picked or created in Map and route setup; a macro holds up to 16 setups, and deleting one also deletes its routes and calibration.

Map and player marker

Reference image and a player crop taught from that map; Marker detection defaults to Automatic from taught marker.

Live area and joystick

Areas selected on the full display; the joystick selection must include the whole outer movement circle. The measurement must be revalidated when the display or app changes.

Tracking source

Track full map (the default) or Track mini-map. Mini-map setup teaches a separate screen area and player marker but uses the same reference map and routes; the position is verified against that map. A missing or ambiguous mini-map setup prevents movement instead of falling back to the full map; check it with Observe without moving in each game first. Mini-map tracking needs separate real-use validation in each game and on each device.

Route and traversal

Named ordered points; one way, explicitly closed loop, or back and forth. One way is one passage; one loop cycle follows the closed route once, and one back-and-forth cycle goes from start to end and returns along the same route.

Route repetition

Unlimited (the default) keeps loop and back-and-forth routes going until the duration limit and returns STOPPED; Number of cycles sets the total number of journeys and ends with ARRIVED after the last one. One-way routes finish after one pass. Starting near the middle completes the first back-and-forth cycle on the return. The duration limit and Stop still apply.

Point action

In the route editor, select Point action, tap a route point and choose the group with Call group. Movement stops at that point and the joystick is released before the group runs; the route continues when the group finishes, and each passage runs the group once. Reach radius is in reference-map pixels. Groups are bound by stable IDs; a missing or ambiguous group is refused before movement.

Scan group while moving

Runs the chosen group every Scan interval (ms) while navigation keeps steering; a new call waits until the previous one finishes, so calls do not accumulate. Only scan in this group (Image, Text, Color or detect-only Agent Detect). Before a tap or another screen action, add Stop navigation, which ends the journey after confirmed joystick release.

Control mode

Strict (default): continuous joystick control from a measured calibration. Live heading tracking: no calibration needed (it is optional); keeps the joystick pressed and steers by fresh marker positions and the heading tip.

Calibrate when the macro starts

Automatic calibration is the default in Strict mode and moves the character once per setup in each macro run; with Use saved calibration, calibrate in Map and route setup first.

Variable / Dialog selection

The saved setup and route can come from a variable or Dialog field bound with the lightbulb, by unique name or ID; a route chosen this way is followed with its own traversal and repetition settings.

Control bounds

Warning/hard corridors use original reference-map pixels, and speed uses map pixels per second. The hard corridor must exceed the warning corridor; the duration limit is separate.

Maximum duration

Defaults to 120000 ms (2 minutes); when it runs out, the joystick is released and the block returns STOPPED.

Output prefix

Defaults to navigation; 19 variables: state, progress, playerX/Y, heading, crossTrackError, routeIndex, speed, joystickX/Y, confidence, mapScore, markerScore, delay, stuck, lastFailure, headingKnown, playerKnown and resumePending.

Requirements

Android 8.0 or later, the accessibility service and screen capture permission; MediaProjection must be the screen capture method.

Parameter	Description
Map setup	Picked or created in Map and route setup; a macro holds up to 16 setups, and deleting one also deletes its routes and calibration.
Map and player marker	Reference image and a player crop taught from that map; Marker detection defaults to Automatic from taught marker.
Live area and joystick	Areas selected on the full display; the joystick selection must include the whole outer movement circle. The measurement must be revalidated when the display or app changes.
Tracking source	Track full map (the default) or Track mini-map. Mini-map setup teaches a separate screen area and player marker but uses the same reference map and routes; the position is verified against that map. A missing or ambiguous mini-map setup prevents movement instead of falling back to the full map; check it with Observe without moving in each game first. Mini-map tracking needs separate real-use validation in each game and on each device.
Route and traversal	Named ordered points; one way, explicitly closed loop, or back and forth. One way is one passage; one loop cycle follows the closed route once, and one back-and-forth cycle goes from start to end and returns along the same route.
Route repetition	Unlimited (the default) keeps loop and back-and-forth routes going until the duration limit and returns STOPPED; Number of cycles sets the total number of journeys and ends with ARRIVED after the last one. One-way routes finish after one pass. Starting near the middle completes the first back-and-forth cycle on the return. The duration limit and Stop still apply.
Point action	In the route editor, select Point action, tap a route point and choose the group with Call group. Movement stops at that point and the joystick is released before the group runs; the route continues when the group finishes, and each passage runs the group once. Reach radius is in reference-map pixels. Groups are bound by stable IDs; a missing or ambiguous group is refused before movement.
Scan group while moving	Runs the chosen group every Scan interval (ms) while navigation keeps steering; a new call waits until the previous one finishes, so calls do not accumulate. Only scan in this group (Image, Text, Color or detect-only Agent Detect). Before a tap or another screen action, add Stop navigation, which ends the journey after confirmed joystick release.
Control mode	Strict (default): continuous joystick control from a measured calibration. Live heading tracking: no calibration needed (it is optional); keeps the joystick pressed and steers by fresh marker positions and the heading tip.
Calibrate when the macro starts	Automatic calibration is the default in Strict mode and moves the character once per setup in each macro run; with Use saved calibration, calibrate in Map and route setup first.
Variable / Dialog selection	The saved setup and route can come from a variable or Dialog field bound with the lightbulb, by unique name or ID; a route chosen this way is followed with its own traversal and repetition settings.
Control bounds	Warning/hard corridors use original reference-map pixels, and speed uses map pixels per second. The hard corridor must exceed the warning corridor; the duration limit is separate.
Maximum duration	Defaults to 120000 ms (2 minutes); when it runs out, the joystick is released and the block returns STOPPED.
Output prefix	Defaults to navigation; 19 variables: state, progress, playerX/Y, heading, crossTrackError, routeIndex, speed, joystickX/Y, confidence, mapScore, markerScore, delay, stuck, lastFailure, headingKnown, playerKnown and resumePending.
Requirements	Android 8.0 or later, the accessibility service and screen capture permission; MediaProjection must be the screen capture method.

Example Usage

Draw a short one-way route between two recognizable positions. Run it after calibration and observation without movement. In following Compare/Log blocks inspect navigation_state, navigation_stuck and navigation_lastFailure; use heading only when navigation_headingKnown is true.

Combinations / Used With

Use Compare for state and confidence, and Log for lastFailure. Continuation after an Agent (Strict mode only) requires an actually completed routine; skipped or unverified completion is insufficient.

Tip

A new reference map opens a separate setup. Old routes stay with their original map and can be reopened from Saved map setup.

Warnings / Cautions

Calibration moves the character: in Strict mode with Automatic calibration on (the default), this happens in every macro run before the route starts, so start in clear space. Position loss, stale frames, missing permissions or hard deviation release the joystick. Imported setups require fresh local calibration. Live heading tracking needs no calibration but does not predict braking distance. Try every new route with Observe without moving and a short duration limit first.

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

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

Basic

Navigation follows an ordered route using the player position measured in each fresh frame. Configure the reference map, live area, player marker and joystick in their setup windows. Draw and save the route; route preview produces no movement. Check position and heading with Observe without moving. Live heading tracking follows the taught heading tip and learns the joystick relationship while travelling. Strict mode instead requires measured local movement calibration; calibration measures the movement response rather than following the route.

Advanced

Choose one way, an explicitly closed loop, or back and forth. One way is one passage; one loop cycle follows the closed route once, and one back-and-forth cycle is one complete outward and return journey along the same route. In Route repetition, Unlimited (the default) keeps loop and back-and-forth routes going until the duration limit, while Number of cycles sets the total number of journeys; the duration limit and Stop still apply. Nearest-route entry may shorten the first outward leg, but the return still reaches the saved start. Points can be moved or deleted, with undo/redo and smoothing that preserves corners; point actions are kept through these edits. A drawing alone cannot say which branch comes first at a crossing, so the saved point order is authoritative. Control mode decides how the joystick is driven. Strict mode uses a measured movement model: Calibrate movement sends directional probes in clear space and records how fast the marker moves and with how much delay; while Calibrate when the macro starts is set to Automatic calibration (the default), the block repeats this once per macro run before it follows the route. Live heading tracking needs no calibration (a movement calibration is optional): it keeps the joystick pressed, corrects the direction from fresh marker positions and the heading tip, learns the joystick relationship while travelling, releases input when tracking is missing or feedback expires, and stops when the response becomes inconsistent. The Tracking source defaults to full-map tracking (Track full map); Track mini-map follows the same reference map and routes with a separately taught mini-map area and marker, and the position is verified against that reference map. A missing or ambiguous mini-map setup prevents movement instead of falling back to the full map. Control settings show corridors in original reference-map pixels and speed in map pixels per second; display DPI does not change these units. Imported measurements are retained but grant no movement until a fresh local calibration.

Pro

The default output prefix is navigation. state and lastFailure are text: state names the outcome in capitals (ARRIVED when a one-way route or the last counted cycle is finished; STOPPED after Stop, Stop navigation or the duration limit; PLAYER_LOST or MAP_LOST when tracking fails; CALIBRATION_REQUIRED when Strict mode has no valid calibration), and lastFailure holds the reason code. progress, playerX/Y, heading, crossTrackError, routeIndex, speed, joystickX/Y, confidence, mapScore, markerScore and delay are numeric; stuck, headingKnown, playerKnown and resumePending are booleans. When playerKnown or headingKnown is false, numeric zero is not a measurement. With Route repetition set to Unlimited, loop and back-and-forth routes do not end by themselves: they keep going until the duration limit and then return STOPPED. A Point action runs its group after the joystick is released, and the route continues when the group finishes. A Scan group while moving runs at the selected Scan interval (ms) while steering continues; screen actions in that group require Stop navigation first, and this explicit stop ends the current journey. Groups are resolved by stable IDs before movement; missing or ambiguous groups are refused. Strict mode bounds movement by confidence, frame age, latency and the hard corridor. With Continue after an Agent set to After verified completion (Strict mode only), a route that stopped as STUCK continues from its saved progress on the next Navigation call of the same run, but only after an Agent routine has actually completed; skipped routines and unverified plans cannot resume movement.

Real-World Scenarios — Step-by-Step Recipes

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

First short route

1Choose the reference map; teach the live map area, player marker and joystick.
2Draw a one-way route between two recognizable positions and inspect the preview.
3Verify position and heading without movement.
4Choose Live heading tracking; if using Strict mode, first calibrate in clear space.
5Run with a short timeout and inspect state and lastFailure.

Use an imported route on another device

1Open the macro and transferred map/route setup; check that point and observation groups were included.
2Verify live areas, joystick and marker teaching on the new device.
3Strict mode needs fresh local calibration even if a measurement record is present; transfer does not carry movement authority.
4After observing without movement, try a short route; verify the separate mini-map area if selected.

A route without calibration: Live heading tracking

1When you teach the player marker, set the heading tip together with the position anchor; this mode does not work without the heading tip.
2Choose Live heading tracking as the Control mode; Calibrate when the macro starts and Continue after an Agent are hidden in this mode.
3In Live heading settings, keep Joystick strength above the joystick dead zone; for slow characters, raise Steering segment (default 180 ms) and Movement learning timeout (default 60000 ms).
4Keep Maximum unverified movement small: this mode does not predict braking distance and stops when it reaches that limit.
5Start the macro with a short duration limit and log the block’s outputs with a Log block to see why it stopped.

Let the user pick the map and route from a Dialog

1Save each setup and route with a unique name in Map and route setup first.
2In a Dialog block, add a Navigation setup editor field, or a text or selection field that holds a setup name or ID.
3In the Navigation block, bind "Saved setup from variable / Dialog" to that field with its lightbulb; a Navigation setup editor value already carries the chosen route, while for other fields you also bind "Saved route from variable / Dialog".
4The route must belong to the selected setup and is followed with its own traversal; a value that does not identify exactly one saved setup or route ends the block with state ERROR and a message that explains why.
5The Navigation setup editor does not move the character; if the map or marker changed there, a new movement calibration is needed (Automatic calibration does it when the macro starts).

Clear a blocker with the Agent, then continue the route

1In the Navigation block, choose Strict mode and set Continue after an Agent to After verified completion.
2Inside a bounded GROUP loop, put the Navigation block, then a Compare on navigation_resumePending; it is true when the route stopped as STUCK and is waiting.
3Put My Agent Routine on the Compare’s true branch to clear the blocker (for example with the Clear all recipe); on the next pass of the loop the same Navigation block continues from where it stopped.
4Add a second Compare that checks navigation_state for ARRIVED and put Break (BREAK) on its true branch, so the loop ends when the route is finished; otherwise the next pass calls Navigation again.
5It continues only when the Agent outcome is exactly completed; completed_with_skips, completed_unverified and plan results are not enough, and the route keeps its original duration limit.

Teach a marker with a clean background

1Open Teach player marker and choose a tight crop of your own marker with a small border (2–256 pixels on each side).
2Tap inside the marker first, then Remove background; the preview keeps only the connected coloured part around that point.
3Fix marker pixels that the automatic cut removed with Brush: Restore, and leftover background with Brush: Erase; edits apply only when you Save.
4An off-centre position anchor shifts as the marker turns; if its direction cannot be told apart, use Place position at foreground centre and check the heading tip again.
5Save: transparent pixels are ignored during detection and the marker’s direction is searched over a full turn; recalibrate movement, because the marker changed.

Which Blocks to Pair With — Pro Combinations

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

+ Compare (COMPARE)

Choose the next step from state, stuck or confidence; check headingKnown before using heading.

+ Log (LOG)

Use navigation_state and navigation_lastFailure to distinguish position loss, boundary violations and setup failures.

+ Agent

Use continuation after verified routine completion on the next Navigation call. agent_ok alone is insufficient: skipped and unverified completions can also make it true.

+ Dialog

A Navigation setup editor field lets the user pick or edit the saved map, marker and route when the macro starts; it does not move the character and hands the selection to the Navigation block as a variable.

Common Mistakes and Fixes

Starting calibration in a menu or beside an obstacle. Measure in clear space with the target app map visible; calibration produces movement.

Treating Colour + reference as colour-independent search. This mode verifies taught colour candidates with the reference; teach the player marker from the same map.

Treating an unknown heading as zero degrees. When headingKnown is false, no heading is available.

Assuming any profileId field is sufficient for a Code export. Code sharing needs a resolvable Navigation.run dependency; a dynamically constructed profile ID cannot be packaged automatically.

Expecting a loop or back-and-forth route to end by itself while Route repetition is Unlimited. It then keeps going until the duration limit and returns STOPPED; for a fixed number of laps, enter a Number of cycles in Route repetition and the route returns ARRIVED after the last cycle. Maximum duration still applies.

Choosing Live heading tracking without teaching the heading tip. This mode steers by the marker’s direction; mark the heading tip together with the position anchor.

Troubleshooting: What the App Says → What to Do

Each row starts with the message the app shows or the block’s output, followed by what to do.

The player marker was not found.: Keep the live map open and teach a tight crop of your own marker again. Observe without moving shows the map and marker score of every frame.
More than one marker matches.: Teach a distinctive crop of your own marker (remove its background) and check that the live map area covers only the map.
The marker’s off-centre position depends on a direction that cannot be distinguished.: In Teach player marker, use Place position at foreground centre, Save and observe again.
The live map could not be matched to the reference.: Select the same map and crop its live area again. If needed, lower Minimum map score in Map and marker detection; this change needs a new movement calibration.
This setup has no valid movement calibration. (state: CALIBRATION_REQUIRED): Use Calibrate movement in clear space in Map and route setup, or set Calibrate when the macro starts to Automatic calibration.
Movement could not be measured reliably.: Keep the character in clear space, check that the joystick selection covers its whole outer movement circle, and choose a higher Probe strength for the next attempt.
The image or input is too delayed for this route.: Check device load and map visibility, then measure again; close heavy apps running in the background.
The measured stopping distance does not fit this route tolerance.: Review the movement settings (for example a wider hard corridor) and measure again in an open area.
The game or screen layout changed.: Return to the selected game, then check the live map and joystick areas; select them again if the screen rotated.
Choose MediaProjection screen capture and grant permission.: Navigation needs a trustworthy capture time: choose MediaProjection as the screen capture method and allow screen sharing when Android asks.
The Dialog or variable value does not identify one saved setup or route.: Use the unique name or ID of the setup or route; the route must belong to the selected setup.
The marker direction is not clear enough. (Live heading tracking): Keep the map visible and teach the marker’s heading tip accurately.
Stopped after reaching the limit for movement without confirmed progress. (Live heading tracking): Check the joystick area and marker accuracy before restarting; raise Maximum unverified movement only in open space.
Joystick release could not be confirmed.: Check in the game that the movement stopped before trying again.
state: GESTURE_FAILED, lastFailure: continued_gesture_requires_api26: The Navigation block needs Android 8.0 or later in every control mode, Live heading tracking included; on older Android versions, move with Swipe or Touch blocks instead.
state: STOPPED, lastFailure: navigation_timeout: Maximum duration ran out (default 120000 ms). Shorten the route or raise Maximum duration; loop and back-and-forth routes with Route repetition set to Unlimited always end this way, while a Number of cycles ends with ARRIVED after the last cycle.
The route point was passed before arrival within its radius could be confirmed.: Check the Point action’s point and its Reach radius in the route editor, then restart before this point.
The point action is missing its group connection.: Select the group again with Call group in the route editor, save the route and restart the macro.
NAVIGATION_STOP_REQUIRED_BEFORE_SCREEN_ACTION (Scan group while moving): A screen action (for example Click, Swipe, Touch, Replay, Dialog, Custom code or another Navigation) ran in the scan group before Stop navigation. Add Stop navigation before it on that branch, or move the work to a Point action, whose group runs with the joystick released.

Pro Tips

Leave screen space outside the map and joystick for the Stop button and the preview. Calibration and route following need trustworthy frame times, so MediaProjection must be the screen capture method and its permission must be granted. The Navigation block needs Android 8.0 or later in every control mode; on Android 7.x it returns GESTURE_FAILED (continued_gesture_requires_api26) before any movement.

Editing a route does not change the measured movement model; recheck calibration after changing the map, marker, joystick or display setup.

Navigation.run uses the macro’s own storage scope. Copying a profile ID from another macro or Logic workspace does not share its setup.

For slowly moving games, raise Probe strength in the Calibrate movement panel. When the speed sample stays uncertain, increase Maximum duration per movement, and when movement after the joystick release cannot be measured, increase Maximum settling observation after release. Live observation stays open until you select Disable; after a measurement, Disable finishes saving the calibration.

Marker detection offers Automatic from taught marker (default), Colour and shape, Colour + reference and Combined evidence, while Map and marker detection holds Minimum map score, Minimum marker score and Marker size multiplier. Scores are comparison thresholds: a higher value needs a closer match, a negative value accepts more matches and a value above 1 accepts none. A multiplier of 1.00 means the marker appears at the reference map’s size. Recalibrate movement after changing any of them.

Live heading settings: Joystick strength (must exceed the dead zone), Steering segment (default 180 ms), Response observation wait (80 ms), Direction response timeout (1500 ms), Direction correction tolerance, Maximum direction uncertainty, Maximum unverified movement and Movement learning timeout (60000 ms). In Strict mode, Pause releases a calibration that is being measured and restarts it after you resume; Stop does not restart it.

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 →

local navigation_state = nil
local navigation_progress = nil
local navigation_playerX = nil
local navigation_playerY = nil
local navigation_heading = nil
local navigation_crossTrackError = nil
local navigation_routeIndex = nil
local navigation_speed = nil
local navigation_joystickX = nil
local navigation_joystickY = nil
local navigation_confidence = nil
local navigation_mapScore = nil
local navigation_markerScore = nil
local navigation_delay = nil
local navigation_stuck = nil
local navigation_lastFailure = nil
local navigation_headingKnown = nil
local navigation_playerKnown = nil
local navigation_resumePending = nil

if Navigation and Navigation._observing then error("NAVIGATION_STOP_REQUIRED_BEFORE_SCREEN_ACTION") end
do
  local _navOnCheckpoint = function(_navCheckpoint)
 if type(_navCheckpoint) ~= "table" or type(_navCheckpoint.groupId) ~= "string" then error("NAVIGATION_CHECKPOINT_INVALID") end
 if _navCheckpoint.validateOnly ~= true and type(_navCheckpoint.values) == "table" then
   navigation_state = _navCheckpoint.values.state or ""
   navigation_progress = _navCheckpoint.values.progress or 0
   navigation_playerX = _navCheckpoint.values.playerX or 0
   navigation_playerY = _navCheckpoint.values.playerY or 0
   navigation_heading = _navCheckpoint.values.heading or 0
   navigation_crossTrackError = _navCheckpoint.values.crossTrackError or 0
   navigation_routeIndex = _navCheckpoint.values.routeIndex or 0
   navigation_speed = _navCheckpoint.values.speed or 0
   navigation_joystickX = _navCheckpoint.values.joystickX or 0
   navigation_joystickY = _navCheckpoint.values.joystickY or 0
   navigation_confidence = _navCheckpoint.values.confidence or 0
   navigation_mapScore = _navCheckpoint.values.mapScore or 0
   navigation_markerScore = _navCheckpoint.values.markerScore or 0
   navigation_delay = _navCheckpoint.values.delay or 0
   navigation_stuck = _navCheckpoint.values.stuck or false
   navigation_lastFailure = _navCheckpoint.values.lastFailure or ""
   navigation_headingKnown = _navCheckpoint.values.headingKnown or false
   navigation_playerKnown = _navCheckpoint.values.playerKnown or false
   navigation_resumePending = _navCheckpoint.values.resumePending or false
 end
 error("NAVIGATION_CHECKPOINT_GROUP_MISSING")
  end
  local _nav = Navigation.run({
 profileId="11111111-2222-3333-4444-555555555555", routeId="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
 routeType="one_way", controlMode="strict", timeoutMs=120000,
 resumePolicy="restart",
 autoCalibrate=true,
 repeatCount=0, mapSource="full_map",
 observationGroup={groupId="", groupName="", intervalMs=1000},
 headingFeedback={fixedMagnitude=0.35, pulseDurationMs=180, responseWaitMs=80,
   responseTimeoutMs=1500, headingToleranceRadians=0.2, maxHeadingErrorRadians=0.7,
   maxUnverifiedTravel=0.04, learningTimeoutMs=60000, startPolicy="nearest_route"},
 controller={warningCorridor=0.012, hardCorridor=0.025, cruiseSpeed=0.05,
   correctionGain=2.0, lookAheadDistance=0.01, arrivalRadius=0.004,
   confidenceFloor=0.75, maxPoseAgeMs=250, commandDurationMs=50,
   processBudgetMs=25, captureBudgetMs=100, stuckWindowMs=1500, minimumProgress=0.001, acquisitionDistance=0.015}
  }, _navOnCheckpoint)
  navigation_state = _nav.state or ""
  navigation_progress = _nav.progress or 0
  navigation_playerX = _nav.playerX or 0
  navigation_playerY = _nav.playerY or 0
  navigation_heading = _nav.heading or 0
  navigation_crossTrackError = _nav.crossTrackError or 0
  navigation_routeIndex = _nav.routeIndex or 0
  navigation_speed = _nav.speed or 0
  navigation_joystickX = _nav.joystickX or 0
  navigation_joystickY = _nav.joystickY or 0
  navigation_confidence = _nav.confidence or 0
  navigation_mapScore = _nav.mapScore or 0
  navigation_markerScore = _nav.markerScore or 0
  navigation_delay = _nav.delay or 0
  navigation_stuck = _nav.stuck or false
  navigation_lastFailure = _nav.lastFailure or ""
  navigation_headingKnown = _nav.headingKnown or false
  navigation_playerKnown = _nav.playerKnown or false
  navigation_resumePending = _nav.resumePending or false
end

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.

📍Target Point or Match Center

Choose clearly between a fixed coordinate, "act on match" (the position the previous search found), or an {x}-bound variable/dialog value to define where the action executes. Binding {matchX},{matchY} does not break across devices or resolutions.

🎛Duration and Repeats

Hold time, repeat count, and inter-action delay shape how aggressive or natural the action feels.

🎲Small Offset

Random offsets or waypoints help validate fixed-coordinate tests across different screen layouts. "In-Match Jitter" randomizes the tap inside the match box and uses the configured margin to stay away from target boundaries. Keep repeated UI tests bounded and record a visible result.

🪜Before and After Waits

Before-waits let UI settle before the action; after-waits let the next block see the updated screen state.

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 →