MacroAI User Guide

1. Introduction

MacroAI is a Windows macro automation tool for running scripts created by others. It can automatically perform mouse clicks, keyboard input, image recognition, and many other operations.

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

2. Quick Start

2.1 Import a Project

Once you receive a project file (.macroai format) from its creator:

1. Click menu Project → Import (or press Ctrl+I)
2. Select the .macroai package (legacy .zip packages still import)
3. If the creator marked it as a distribution package, the app will automatically enter Run mode

What is a distribution package? A special project package exported by designers. When imported, it locks into Run mode — you only need to focus on the configuration required to run the script.

2.2 Run Mode Interface

After importing a distribution package, you'll see the streamlined Run mode interface with three main areas:

┌── ① Project Info (collapsible) ──────────────────┐
│  📁 Project Name                                  │
│  Design Resolution: 1920×1080  Strategy: Uniform  │
│  ───────────────────────────────────────────────  │
│  Description: Auto-match game board, click        │
│  identical patterns. Customizable avatar & name.  │
└────────────────────────────────────────────────────┘

┌── ② Area Calibration (always visible) ────────┐
│  🖥 Run Area: ── Not Calibrated ──  [ Calibrate ]│
│  🖥 Design Area: 1920×1080 (reference)           │
│  Coordinate Strategy: Uniform (auto-adapt)       │
└──────────────────────────────────────────────────┘

┌── ③ Personalized Config (collapsible) ────────┐
│  ⚠️ Nickname: Using default                      │
│  ✅ Avatar: Set                                   │
│  ❌ Signature: Not set                            │
└──────────────────────────────────────────────────┘

The toolbar provides Run/Stop, Background/Foreground mode, and log level controls.

2.3 Step 1: Calibrate the Run Area

Calibration is the first step — it ensures the script's operations match your screen:

1. Click the [ Calibrate ] button on the area calibration card
2. Follow the on-screen instructions to select the window or area where the script will run
3. After calibration, the card will display the run area's dimensions and position

If the design area is full-screen, the system automatically adapts to your current screen — no manual selection needed.

2.4 Step 2: Fill in Personalized Config

If the designer set up user config variables (e.g., nickname, avatar), fill them in:

• Text type: type your value in the input field
• Image type: click [Screenshot] or [Choose File] to upload an image

The status icon next to each item shows:

All changes are saved automatically.

2.5 Run the Script

Once configured, click ▶ Run (or press F5) to execute the script. Click ■ Stop (or press Shift+F5) to terminate at any time.

During execution, the log panel at the bottom auto-expands to show progress and results.

3. Config Completeness Indicator

The indicator on the toolbar shows your configuration status at a glance:

Click the indicator to expand a detailed checklist. Click [Jump] to navigate directly to any pending item.

4. Log Panel

The run log appears in a collapsible panel at the bottom:

• Idle: panel is collapsed, only the run button is visible
• Running: panel auto-expands, logs stream in real-time
• Finished: last state is preserved, you can manually collapse it

The 🐞 Simple Debug dropdown on the toolbar controls log verbosity:

5. Floating Control Panel

When a script is running, a floating control panel appears (always on top, draggable):

• Pause/Resume: temporarily stop or continue execution
• Custom Action Buttons: quick actions defined by the designer (e.g., "Pause and adjust window"). The designer can also set an action as a standalone floating button — a small independent window you can drag anywhere; its position is remembered. Actions set to "hidden" don't appear in the runtime UI
• Task Zone (Pro feature): shows the status wall and to-do count of periodic tasks — see below
• Music Controls: if the script includes background music, shows pause/resume/mute buttons
• Close Panel: stops script execution

Task Zone: Status Wall & To-Do Button

When the designer configured periodic tasks (e.g., "daily check-in", "drink water every 2 hours"), a task zone appears in the panel:

• Status Wall: one small square per task. Solid = has a result this round, hollow = not yet done; green = completed, blue = waiting to run, yellow = currently running, gray = idle or disabled. Hover over a square to see the task name and progress
• To-Do Button: shows "To-Do N" or "✓ All Done"

Click any square or the to-do button to open the task popup panel:

• Click a row to run: tasks bound to an action run on click (click again while running = stop)
• Confirm completion: reminder-only tasks are confirmed done with one click on the row
• Right-click a row: run once manually and other operations
• ⚙ Settings: quick switches — show status wall, reminder channels (tray bubble / in-app toast / sound), all-done notification, auto-execution master switch

Task Reminders

When a task falls due or enters a new cycle, you are notified through the channels enabled in ⚙ Settings:

If the designer set a task to "auto-execute when due", the bound actions run automatically in sequence when due, as long as the auto-execution master switch is on — no need for you to be present. Every due event, queue entry, and execution result can be traced in the execution log.

6. FAQ

I made a mistake during calibration — what now?

Simply click the [ Calibrate ] button again to re-select the area.

I filled in the wrong value in config — how do I reset?

For text fields, click [Restore Default] to revert to the designer's example. For images, click [Clear] and re-select.

The indicator keeps showing 🔴?

The run area hasn't been calibrated yet. Complete the calibration first.

The script is clicking at the wrong position?

The run area calibration might be inaccurate. Try recalibrating. If the problem persists, contact the script's designer.

What's the difference between Background and Foreground mode?

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

Switch to foreground mode if background mode doesn't work for certain actions.

What do the squares in the status wall mean?

Solid = has a result this round, hollow = not yet done. Green = completed, blue = waiting to run, yellow = currently running, gray = idle or disabled. Solid red = the period ended without completion; hollow red = the action bound to the task is missing (reminders and counting pause; contact the script's designer to fix it).

I'm not receiving task reminders?

Open the task popup panel's ⚙ Settings and check whether the corresponding channel is enabled (in-app toast and tray bubble are on by default; sound is off by default). Note: reminders pause while a task shows the hollow-red "missing action" state.

Why didn't my task auto-execute when due?

Two conditions must hold: the designer selected "auto-execute" for the task, and the auto-execution master switch in the popup panel's ⚙ Settings is on. Auto-execution also requires the app to be open — missed due times are not made up afterwards; you can trace what happened in the execution log.

7. Keyboard Shortcuts

For more detailed information, see Help → Designer Guide (for script creators).

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