MacroAI Designer Guide

1. Introduction

MacroAI is a Windows macro automation platform for script creation and distribution.

Build automation workflows through a visual node editor (20+ node types, tree-container architecture) or Lua scripting — covering mouse/keyboard, image recognition, OCR text recognition, screen change detection, and more. Built-in multi-resolution adaptation ensures the same script runs stably across different screen sizes and scaling ratios — the key enabler for sharing scripts with other users.

Supports background input simulation (no focus stealing), Windows OCR (zero install), screen change detection, and multi-threaded concurrent execution. Core features are permanently free with no ads.

Core workflow: Designer creates script → Export distribution package → End user imports and runs.

Use cases: Game assistance · Office automation · Software testing · IT operations · RPA

2. Quick Start

MacroAI organizes all content (nodes, scripts, images, recorded macros, etc.) into projects, so you must create a project first.

2.1 Create a New Project

Click menu Project → New (or press Ctrl+N):

1. The first time you use it, you'll be prompted to choose a working directory (where project files are stored)
2. Enter a project name
3. Set the design area — the effective range for your macro operations:
4. Full Screen: uses your current screen resolution
5. Custom Selection: drag to select a window or region

2.2 Interface Overview

The main window has 9 tabs (switch via Ctrl+1~Ctrl+9):

The toolbar provides mode switching (🔧 Design/🏃 Run), Run/Stop, Background/Foreground, Click Visualization (🔴), and log level controls.

2.3 Record & Play Back a Macro

Recording is the fastest way to create a macro — record first, then refine:

1. Switch to the Macro Manager tab (Ctrl+7), click + New Recording
2. A green border appears around the design area, with a 「■ Stop Recording」 button at the bottom-left
3. Perform the actions you want to automate (clicks, text input, etc.)
4. Click 「■ Stop Recording」 to finish and save to project
5. Select the recorded macro in the list and click ▶ Play to replay it

2.4 Enhance Your Workflow with the Node Editor

A recorded macro can only be replayed as-is. Want to add conditions, loops, image recognition, or other logic? Use the node editor:

1. Switch to the Node Editor tab (Ctrl+1)
2. In the left panel, click the Call Recorded Macro node to add it to the workflow
3. Double-click the node to open its configuration and select the macro you just recorded
4. Add other nodes before or after it (e.g., Wait, Find Image) to build smarter automation
5. Drag nodes to reorder them, or drag them into a Condition or Loop node to group them together

Changes in the node editor automatically generate script code, which you can view in the code preview (read-only, synced from the node editor).

2.5 Run Your Project

Click ▶ Run (or press F5) to execute the current project's node workflow / script code. Click ■ Stop (or press Shift+F5) to terminate at any time.

3. Design Mode & Run Mode

MacroAI introduces a dual-mode system that completely separates the designer and end-user interfaces.

3.1 The Two Modes

3.2 Switching

The toolbar's mode switch dropdown (🔧 Design / 🏃 Run) switches between modes with one click. Both modes are always visible.

• New project → defaults to Design mode
• Import normal project → restores last used mode
• Import distribution package → automatically enters Run mode (Design mode entry is grayed out)

3.3 Design Mode (Creating Scripts)

Design mode provides full editing capabilities:

• 9 tabs covering node editing, code, variables, images, functions, custom actions, macros, regions, and user config
• Menu Project → Settings opens the settings dialog
• ▶ Run button is available (for designer testing)
• Log displayed in a separate window

3.4 Run Mode (End User View)

Run mode provides a streamlined interface for end users, hiding all editing tools:

• Project Info Area: shows project name, design resolution, coordinate strategy, and description (collapsible)
• Area Calibration Card: prominently displays run area status with a calibration button (always visible)
• Personalized Config Area: end users fill in the config variables defined by the designer (see Chapter 5)
• Config Completeness Indicator 🟢🟡🔴: reflects configuration status in the toolbar in real-time
• Run Log: collapsible bottom panel, auto-expands during execution

3.5 Distribution Package

When exporting, a designer can choose to mark as distribution package:

• A distribution package defaults to Run mode upon import; the Design mode entry is grayed out and unclickable
• This flag identifies the project's origin and is reserved for future features (e.g., encrypted export, access control)
• Normal projects created on the designer's own machine do not have this flag

4. Core Features

Image Recognition

Find a specific image on the screen and perform actions:

1. In the Image Manager tab (Ctrl+4), upload a template image or take a screenshot
2. In the node editor, add a Find Image or Find and Click node
3. Configure: select the template image, search region, match threshold (default 0.85), and match method
4. Enable Click to automatically click when found; set a Timeout to keep searching until the image appears
5. The result is accessible via variables: result.center_x, result.center_y, etc.

Node Types:

Three match modes: Grayscale (classic, fast), Luminance (lighting-robust), OKLab Color (color-shift resistant, no re-screenshot needed).

OCR Text Recognition

Recognize text on the screen:

• OCR Recognize: select a region and read the text content
• OCR Compare: check if specified text appears in a region; enable Click to auto-click when matched
• Find Text: find specified text in a region and return its position
• Configure the default recognition language in Settings (Ctrl+,)

Screen Change Detection

Wait for specific changes on the screen, useful for monitoring UI states:

• Wait for Screen Change: detect content changes within a specified region. Supports sensitivity adjustment, periodic change filtering (e.g., blinking buttons), and timeout settings
• Wait for Bar Change: track length changes in bars (health bars, progress bars). Supports auto-detection of horizontal/vertical orientation and scrollbar interference filtering

Color Detection

• Get Color: get the color value at a specified position
• Find Color: search for a specific color within a region
• Dominant Color: analyze the dominant color in a region

Mouse & Keyboard Simulation

• Mouse Click / Mouse Move / Mouse Drag: supports direct coordinates and variable references; you can box-select to get coordinates
• Key Press / Type Text: simulate keyboard input and shortcut combinations
• Coordinate fields accept: direct numbers, variable references (e.g., result.center_x), or click-to-pick

Background Mode (default): simulates actions in the background without interfering with normal use. Foreground Mode: directly controls the mouse and keyboard, taking over control. Use when background mode doesn't work.

Flow Control

Every node can have an execution condition (previous success/failure, custom expression). Drag to adjust node order and nesting.

Variables & Data Passing

Define variables (name, type, default value) in the Variables tab (Ctrl+3). Insert variable references in node configuration via the ▼ menu:

Variable scope: local (script-local) or global (shared across scripts).

Audio & Notifications

• Play Sound: system sounds, do~si beeps, custom audio files
• Play Music: background music in common formats; the floating panel shows playback controls (pause/resume/mute); sound effects automatically lower music volume
• Show Notification: display a notification message at a specific step during execution

5. User Config Variables

Designers can use user config variables to allow end users to personalize settings without touching the script.

5.1 Concept

User Config Variables (UserConfigVar) let designers define "placeholders" that end users fill in before running:

5.2 Defining Variables

Manage variable definitions in the User Config tab (Ctrl+9):

1. Click + New to open the edit dialog
2. Fill in the variable ID (auto-prefixed with uc_), title, and description
3. Select type: text or image
4. Set a default value (as a reference for end users)
5. For image type, you can enable "Allow multiple images"

5.3 Referencing in Nodes

In the node configuration dialog, click the ◎ button to open the three-segment menu:

Variables
  my_var (variable)
  other_var (variable)
───
Parameters
  param1 (parameter)
───
User Config
  🖼 Your Avatar (uc_avatar)
  📝 Message Content (uc_message)

After selection, the field gets a u|var_id reference inserted. The engine resolves it to the end user's actual value at runtime.

5.4 Type Details

5.5 End User View

In Run Mode, end users see these variables in the personalized config area:

• ✅ Personalized: end user has set their own value
• ⚠️ Using default: not modified, using the designer's example value
• ❌ Not set: no value and no default (affects required fields only)

All changes are saved in real-time.

6. Export & Distribution

6.1 Export Project

Click menu Project → Export (Ctrl+E):

1. Choose the export path
2. Enter a version number
3. Check "Mark as distribution package": the imported project defaults to Run mode upon import
4. Leave unchecked for a normal project; end users can switch to Design mode

6.2 Distribution vs Normal Project

6.3 Best Practices

1. Write a detailed project description: help end users understand the script's purpose
2. Design user-friendly config variables: use clear display names and descriptions, provide reasonable defaults
3. Test your distribution package: verify all u| references work before exporting
4. Include all resources: ensure all template images are included
5. Version your releases: use version numbers so end users can track updates

7. Log Level Control

The toolbar provides three log levels for troubleshooting:

Trace mode output example:

[Image Find] Found "avatar" position=(520,340) confidence=0.95
[Mouse Click] Click (520,340) left button
[Mouse Move]  Move to (100,200)
[Text Input]  Typing "Hello"
[Wait]        Waiting 500ms
[Condition]   Condition: result.success → true
[Loop]        Loop start (count: 10)
[OCR]         Recognized: "hello" confidence: 0.92
[Color]       ✓ Matched color found
[Variable]    my_var = hello
[Notification] Operation completed (3s)
[Wait Change] ✓ Detected 3 changes

In Design mode, logs appear in a separate window. In Run mode, logs appear in a collapsible bottom panel — auto-expanding during execution and collapsible when idle.

8. Advanced Features

Functions & Custom Actions

Functions: package a group of nodes into a reusable sub-workflow with parameter support. Create and edit them in the Functions tab (Ctrl+5).

Custom Actions: bind a function to a one-click button on the floating panel. Configure them in the Custom Actions tab (Ctrl+6); the buttons appear on the floating panel when running.

Regions & Multi-Resolution Support

A region is a named rectangular area on the screen:

• Design Area: the reference coordinate space defined when creating the project
• Run Area: the actual screen region at runtime (can differ from the design area)
• Custom Regions: user-named areas that can be referenced in node configuration
• Coordinate Strategy: determines how coordinates are mapped from design area to run area

Coordinate Strategy

Switch in Project → Settings → Region Settings (Ctrl+,):

• Uniform Scaling (uniform) — games, full-screen apps: coordinates scale by the proportional size of design/run areas. During calibration, freely drag-select the area while maintaining the same aspect ratio as the design area
• Pan Adaptation (desktop) — browsers, Office windows: coordinates shift only by translation, no scaling. During calibration, only the position can be adjusted; width and height are fixed to the design area

Switching strategies changes how all existing coordinate points are interpreted. A warning is shown, and you may need to re-adjust existing coordinate points.

Calibrating the Run Area

When a script is created at one resolution but needs to run at another (or the window position changes), click Project → Settings → Region Settings → Calibrate to re-set the run area:

1. If the design area is Full Screen: the run area is automatically set to the current full screen — no manual selection needed
2. If the design area is Custom Selection:
3. Uniform mode: drag to select the run area, maintaining the same aspect ratio as the design area
4. Desktop mode: click or drag to specify the run area's position (top-left corner); width and height are fixed to the design area

After calibration, all coordinates are automatically recalculated according to the current coordinate strategy.

Each Find Image node can independently set its own coordinate strategy, overriding the project default (Follow Project / Uniform Scaling / Pan Adaptation).

Debugging Tools

• 🔴 Click Visualization: when enabled, a red dot appears at each click position (disappears after 0.5s) for verifying coordinates
• Log Level Control: switch between Concise/Trace/Debug
• Log Output node: write custom log messages at key steps

Settings

Click menu Project → Settings (Ctrl+,) to open the settings panel:

• Working Directory: default location for project files
• Interface Language: 中文 / English
• OCR Language: default language for text recognition
• Auto Save: automatically save changes to disk

9. Interface Reference

Toolbar

[ 🔧 Design ▼ ]  [▶ Run]  [■ Stop]  [🔄 Background]  [🔴 Click Vis]  [🐞 Debug: Concise | Trace | Debug]

• Mode Switch: dropdown menu, one-click toggle between Design and Run modes
• Run/Stop: execute or terminate the current project
• Background/Foreground: switch input simulation mode
• Click Visualization: show red dots at click positions
• Log Level: three-segment button controlling log verbosity
• Config Completeness Indicator (Run mode only): 🟢 Ready / 🟡 Some defaults / 🔴 Needs calibration

9 Tabs

Floating Control Panel

Automatically appears when running a macro — always on top, draggable. Provides pause/resume, custom action buttons, background music controls (visible when music is playing), and close to stop execution.

System Tray

Closing the window minimizes it to the system tray. Double-click the tray icon to show the main window. Tray menu: Show Window / Run Current Macro / Stop / Exit.

Keyboard Shortcuts

10. FAQ

Why does my recorded macro always click at the wrong position?

Make sure you set the correct design area when creating the project. If you change monitors or resolution, use the Calibrate feature to re-set the run area.

Image search keeps failing?

• Lower the match threshold (default 0.85, try 0.7)
• Narrow the search region for better speed and accuracy
• Ensure the template image matches the actual runtime environment
• Try different match modes (Grayscale/Luminance/OKLab Color)

What's the difference between Background and Foreground mode?

• Background Mode (default): simulates actions in the background without interfering with normal use
• Foreground Mode: directly controls the mouse and keyboard, taking over control

If background mode doesn't work for certain actions, switch to foreground mode. Use 🔴 Click Visualization to verify coordinates.

How do I debug my workflow?

Use the log level control in the toolbar to switch to Trace or Debug level for detailed logs, add Log Output nodes at key steps, and enable 🔴 Click Visualization to see where clicks land.

What is the relationship between the Code Preview and Node Editor?

Operations in the node editor automatically generate Lua script code. You can view the code in the code preview (read-only), synced from the node editor.

How do I allow end users to personalize settings?

Define config variables in the User Config tab (Ctrl+9), reference them in node configuration via the ◎ menu (u|var_id format), and mark the project as a distribution package when exporting. End users will see and fill in their values in Run mode.

What's the difference between a distribution package and a normal project?

A distribution package defaults to Run mode upon import (Design mode is grayed out), while a normal project restores the last used mode (freely switchable). The distinction is controlled by the "Mark as distribution package" checkbox during export.

11. Demo Projects

MacroAI comes with built-in demo projects to help you quickly understand the software's capabilities.

Included demo projects:

The system will ask on first working directory setup, or import anytime via menu Help → Import Demo Projects.

Use Project → Open to view and run them. Freely modify scripts and nodes as a starting point for learning and customization.

For detailed API reference, see menu Help → API Reference.

Feedback: If you encounter any errors or have suggestions, please email us at macroai@sowe.com. We look forward to your feedback!