Coordinate Strategy & Resolution Adaptation

The coordinate strategy determines "how coordinates are converted when the runtime environment differs from the design environment". MacroAI offers two strategies:

• Uniform scaling (uniform) — the entire view is enlarged or shrunk. Coordinates are scaled proportionally, and template images are scaled proportionally too.
  Best for: games and full-screen apps. These programs stretch the whole view proportionally at different resolutions.
• Desktop offset (desktop) — the view isn't scaled; it's simply shifted in position. Coordinates are only translated, and templates are not scaled.
  Best for: browsers, Office, and file managers. When these windows get larger, the content doesn't enlarge — you just see more of it.

Quick rule of thumb: if your target program "looks the same size at different resolutions, just in a different position" → use desktop offset. If "the whole view gets bigger or smaller" → use uniform scaling.

Switch it in Project Settings (Ctrl+,) → Region settings.

This is the most common issue, and it's usually caused by the run region not being calibrated. Follow these steps:

1. Switch to run mode (toolbar → 🏃 Run)
2. Find the Region Calibration section and click the "Calibrate" button
3. In the full-screen overlay that appears, select the actual display area of the target program
   • Uniform scaling mode: select freely, keeping the same aspect ratio as the design region
   • Desktop offset mode: you can only move the position; the width and height stay fixed
4. Confirm, then run the script again

If it's still offset after calibration:

• Check that the coordinate strategy is correct (uniform scaling for games, desktop offset for desktop programs)
• If only certain images aren't found, it may be an image quality issue — try re-capturing the template images
• Android users: check whether the game has black bars (if so, select the actual view area inside the bars)

MacroAI has two region concepts:

• Design region — the screen area you used while building the script (set when creating the project, rarely changed)
• Run region — the screen area where the target program actually sits when the script runs

If you run on the same computer with the window in the same position, the two are identical and no calibration is needed.

Situations that require calibration:

• You've moved to a computer/phone with a different resolution
• The target window's position or size has changed (e.g. moved from the left side to the right)
• The Windows DPI scaling has changed (e.g. from 100% to 125%)

Calibration only needs to be done once — the result is saved with the project. You won't need to recalibrate the next time you open the same project (unless the environment changes again).

Android phones have highly fragmented aspect ratios (16:9, 19.5:9, 20:9...), so a game usually behaves in one of three ways on different devices:

• Black bars (content centered, with black bars on top/bottom or left/right) → during calibration, select the actual view area inside the bars, and use uniform scaling mode
• Proportionally enlarged view (content gets bigger, no black bars) → just use full screen with uniform scaling mode
• Expanded viewport (content doesn't get bigger, you just see more background) → use desktop offset mode; UI button positions usually stay the same

Practical advice:

1. First, confirm how the game displays on your phone (whether there are black bars)
2. Black bars present → calibrate the region in the run settings, selecting only the view area
3. No black bars → the default full screen is fine; calibration is usually unnecessary

MacroAI has built-in DPI correction. DPI is already factored into the coordinate scaling system, so under normal circumstances you don't need to worry about it.

When an image isn't found, it's usually unrelated to DPI and more likely an image quality issue. If certain images aren't found, try re-capturing the template images.

Multi-monitor note: if your two monitors use different DPI scaling (e.g. primary at 125%, secondary at 100%), avoid moving the target window across screens.

Because the core assumption of uniform scaling is: the view scales by the same factor in both the X and Y directions (scale_x = scale_y).

If the design region is 1920×1080 (16:9) but you calibrate a 1920×1200 (16:10) region, then X scales by 1.0× while Y scales by 1.11× — the view is stretched non-uniformly, and coordinate conversion will be wrong.

That's why MacroAI locks the aspect ratio during calibration. You can only adjust the region's size and position, not its ratio. This protects the accuracy of coordinate conversion.

If your target program really does stretch non-uniformly (very rare), consider switching to desktop offset mode, or recreate the design region at the actual ratio.

Signs that you should switch:

• Using uniform scaling, but on another computer the script is "shifted as a whole" rather than "scaled bigger/smaller as a whole" → you should use desktop offset
• Using desktop offset, but on another computer the click positions are "offset proportionally" → you should use uniform scaling

Impact of switching:

• The interpretation of all existing coordinate points changes (the same numbers produce different actual positions under scaling vs. offset)
• A warning dialog is shown when you switch
• You may need to recalibrate the run region
• Already-captured template images are unaffected (the images themselves don't change)

Advice: choose the right strategy when you create the project. If unsure, pick uniform scaling for games/full-screen and desktop offset for windowed programs. After switching, it's best to test the entire flow once.

By default, every node follows the project's global coordinate strategy. But individual nodes can set a different strategy on their own — this is the "coordinate strategy override" (transform_policy).

Example scenarios:

• The project as a whole uses uniform scaling (a game), but one node needs to click a button on the system taskbar (which doesn't scale with the game) → set that node alone to desktop offset
• The project as a whole uses desktop offset (a browser), but one image search targets video content (which does scale) → set that node alone to uniform scaling

In the node configuration dialog, find the "Coordinate Strategy" dropdown and select "Uniform scaling" or "Desktop offset" to override. Selecting "Follow project" uses the global setting.

Note: this is a Pro feature. In most cases you won't need it — it's only necessary when "a single project mixes scaled and non-scaled content".