Running & Debugging

MacroAI's log panel shows all information generated during a run:

• Windows version: the log area at the bottom of the main window. Errors are shown in red.
• Android version: tap the 📋 button on the run bubble to open the log page.

Common errors and what they mean:

• "Image xxx.png not found" → the template image isn't within the search range, or the threshold is too high
• "Execution timed out" → wait-for-image / wait-for-change exceeded the configured timeout
• "Lua syntax error" → there's a code error in a custom code node
• "Variable xxx is undefined" → you used a variable that isn't defined in the Variables tab

If the log isn't detailed enough, switch the log level to "Debug" to see more internal information.

The log level on the toolbar controls how much information is shown:

• Concise (default) — shows only the content of "Log Output" nodes and error messages. The cleanest option, suited for normal runs.
• Trace — additionally shows each node's execution progress (e.g. "[Find Image] found xxx at position=(500,300)"). Suited for troubleshooting "which step is the script on" or "did a certain node run".
• Debug — additionally shows engine internals (screenshot dimensions, scaling ratios, match scores, etc.). Suited for diagnosing deep technical issues.

Recommendation: use "Concise" for normal runs; switch to "Trace" when troubleshooting; use "Debug" and capture a log screenshot when reporting bugs to the developers.

After the script starts, a floating control panel appears in the top-right of the screen (on Android it's a floating bubble):

• Status label (▶ Running / ⏸ Paused / ⏹ Finished / ⚠ Error) — shows the current state
• ⏸ Pause / ▶ Resume — pauses or resumes script execution
• ■ Stop — fully terminates the script
• Custom action buttons (if defined) — trigger extra operations with one tap (e.g. "Emergency Stop", "Switch Target")
• ✕ Close — closes the panel and stops all running tasks

Windows version: the panel can be dragged around. When the script finishes and there are no custom actions, the panel disappears automatically after 3 seconds.

Android version: the bubble can be dragged; tap it to expand the menu. It auto-expands for 3 seconds when it first appears.

This is a concept specific to the Windows version, controlling how mouse and keyboard actions are simulated:

• 🔄 Background running (default) — sends clicks/keystrokes via the Windows message mechanism, without moving the real mouse or stealing focus. You can keep using your computer for other things while the script runs.
• Foreground running — directly controls the physical mouse/keyboard. The mouse actually moves while running, and you can't operate the computer at the same time. But it has better compatibility.

How to choose?

• In most cases, background (the default) is fine
• If in background mode the target program "doesn't receive" the clicks (some games, remote desktop) → switch to foreground
• While running in foreground, don't touch the mouse or keyboard, or you'll interfere with the script

Switch it via the "🔄 Background" button on the toolbar.

If you're currently in foreground running mode, the script directly controls the physical mouse and keyboard, so you can't operate them at the same time.

Solution: switch to background running mode (click the "🔄 Background" button on the toolbar). Then the script sends actions via the message mechanism and won't occupy your mouse and keyboard.

Note: some programs (such as certain games and remote desktop software) don't support background messages and require foreground mode. In that case, you'll have to wait for the script to finish before operating, or use another computer/phone to control things.

Click Visualization is a debugging aid in the Windows version. When enabled, every time the script performs a mouse click, a red dot is shown at the click position (disappearing after 0.5 seconds).

Uses:

• Confirm whether the script is clicking the right position
• Troubleshoot "found the image but clicked the wrong spot" issues
• In background mode you can't see the mouse move — the red dot shows you "where it clicked"

Toggle it with the "🔴" button on the toolbar. We recommend turning it off during normal runs (to avoid visual distraction) and turning it on while debugging.

• Pause: click the "⏸ Pause" button on the floating panel. The script pauses after the current node finishes.
• Resume: click "▶ Resume" to continue execution.
• Stop: click "■ Stop" or press Shift+F5. Fully terminates and cannot be resumed.

Notes:

• If a "Wait" node is timing when you pause, it resumes from where it paused
• Stopping is irreversible — you'll need to click "▶ Run" again to run it once more
• Android version: expand the bubble menu to operate

Custom actions are "shortcut buttons" bound to the floating panel. They let you independently trigger a sequence of operations while the main script is running.

Typical scenarios:

• The main script is auto-farming, and you want to press a button at any time to "return to town" → create a "Return to Town" custom action
• The main script is looping, and you need to temporarily "pause and take a screenshot"
• You have several helper operations that need to be triggered manually at any time (e.g. switching targets, using a special skill)

How to set up:

1. Create an action in the "Custom Actions" tab (Ctrl+6)
2. Build the action's node flow (edited the same way as the main flow)
3. After running the script, the corresponding button appears on the floating panel
4. Tap the button at any time to trigger the action, without affecting the main script