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 (.zip format) from its creator:

1. Click menu Project → Import (or press Ctrl+I)
2. Select the zip file
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):

• Pause/Resume: temporarily stop or continue execution
• Custom Action Buttons: quick actions defined by the designer (e.g., "Pause and adjust window")
• Music Controls: if the script includes background music, shows pause/resume/mute buttons
• Close Panel: stops script execution

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.

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!