MacroAI API 参考

图像识别

image_find(tmpl, region?, threshold?) -> ImageMatchResult | nil
image_wait(tmpl, timeout?, region?, threshold?) -> ImageMatchResult | nil
image_find_all(tmpl, region?, threshold?) -> table | nil
image_wait_all(tmpl, timeout?, region?, threshold?) -> table | nil
image_save_template(img, path) -> void

参数说明： - tmpl (string) — 模板图片文件名（如 "button.png"），图片需先在图像管理标签页中上传；也支持变量引用（如 var_get('btn_name')）或函数参数名 - region (table, 可选) — 搜索区域 {left, top, width, height}，不传则搜索全屏或默认区域 - threshold (number, 可选) — 匹配阈值，范围 0~1，默认 0.85，越低越容易匹配 - timeout (number, 可选) — 超时秒数，默认 10 - img — 图像数据（numpy 数组）

返回值 (ImageMatchResult)： - .success (boolean) — 是否找到 - .x, .y (number) — 匹配区域左上角坐标 - .center_x, .center_y (number) — 匹配区域中心坐标 - .width, .height (number) — 匹配区域尺寸 - .confidence (number) — 置信度 - .rect (table) — {left, top, width, height} - .template_name (string) — 匹配成功的模板文件名（多图查找时可判断哪个模板匹配上）

示例：

local r = image_find("login_btn.png", {100, 200, 800, 600}, 0.8)
if r and r.success then
    mouse_click(r.center_x, r.center_y)
end

返回全部匹配结果：

image_find_all(tmpl, region?, threshold?) -> table | nil
image_wait_all(tmpl, timeout?, region?, threshold?) -> table | nil

• 返回所有匹配结果的数组，无匹配则返回 nil
• 每个元素字段与 ImageMatchResult 相同
• 适用于同一模板在屏幕上出现多次的场景
• image_wait_all 轮询直到至少一个匹配出现，然后返回全部匹配

示例（查找并点击全部匹配）：

local results = image_find_all("icon.png")
if results then
    for _, r in ipairs(results) do
        mouse_click(r.center_x, r.center_y)
        wait(500)  -- 点击间隔
    end
end

多图查找示例：

local r1 = image_find("btn_ok.png", nil, 0.85)
local r2 = image_find("btn_cancel.png", nil, 0.85)
local best = nil
local best_conf = 0
for _, r in ipairs({r1, r2}) do
    if r and r.success and r.confidence > best_conf then
        best = r
        best_conf = r.confidence
    end
end
if best then
    -- 通过 template_name 判断匹配的是哪个模板
    if best.template_name == "btn_ok.png" then
        -- 确认按钮
    else
        -- 取消按钮
    end
end

OCR

ocr_recognize(region?, lang?) -> string
ocr_compare(text, region?, threshold?, lang?) -> OcrCompareResult
ocr_find_text(text, region?, lang?) -> number, number
ocr_log(msg) -> void

参数说明： - region (table, 可选) — 识别区域 {left, top, width, height}，不传则全屏 - lang (string, 可选) — 语言代码，如 "zh-CN"、"en-US"，不传则使用系统默认 - text (string) — 要匹配的文字 - threshold (number, 可选) — 相似度阈值，默认 0.8 - msg (string) — 日志消息

返回值 (OcrCompareResult)： - .matched (boolean) — 是否匹配 - .found_text (string) — 识别到的文字 - .similarity (number) — 相似度 - .confidence (number) — 置信度

ocr_find_text 返回值： - 成功: center_x, center_y (number, number) - 失败: nil, nil

示例：

local text = ocr_recognize({100, 100, 500, 100}, "zh-CN")
ocr_log("识别到文字: " .. text)

local r = ocr_compare("确定", {100, 100, 500, 100})
if r and r.matched then
    log("匹配成功，相似度: " .. r.similarity)
end

local x, y = ocr_find_text("提交", {100, 100, 500, 100})
if x then mouse_click(x, y) end

鼠标

mouse_click(x?, y?, button?, clicks?) -> void
mouse_move(x?, y?) -> void
mouse_double_click(x?, y?) -> void
mouse_right_click(x?, y?) -> void
mouse_scroll(clicks, x?, y?) -> void
mouse_drag(sx, sy, ex, ey, button?, duration?) -> void

参数说明： - x, y (number, 可选) — 屏幕坐标，不传则在当前位置操作 - button (string, 可选) — 鼠标键，可选："left"（默认）、"right"、"middle" - clicks (number) — 滚轮滚动格数，正数向上，负数向下 - sx, sy (number) — 拖拽起点 - ex, ey (number) — 拖拽终点 - duration (number, 可选) — 拖拽持续时间（秒），默认 0.3

示例：

mouse_click(500, 300)              -- 左键点击 (500,300)
mouse_click(500, 300, "right")     -- 右键点击
mouse_double_click(500, 300)       -- 双击
mouse_move(100, 200)               -- 移动到 (100,200)
mouse_drag(100, 100, 500, 300)     -- 从 (100,100) 拖拽到 (500,300)
mouse_scroll(3)                    -- 向下滚动 3 格

键盘

key_press(key) -> void
key_type(text) -> void
key_hotkey(key1, key2, ...) -> void
key_shortcut(combo) -> void

参数说明： - key (string) — 按键名，如 "enter"、"tab"、"escape"、"a"、"ctrl" 等 - text (string) — 要输入的文本，换行符将自动转为 Enter - key1, key2, ... (string...) — 组合键序列，如 ("ctrl", "c") - combo (string) — 快捷键组合，如 "ctrl+c"、"alt+tab"

示例：

key_press("enter")                  -- 按回车
key_type("Hello, World!")           -- 输入文本
key_hotkey("ctrl", "c")            -- 按 Ctrl+C（序列按键）
key_shortcut("ctrl+c")             -- 按 Ctrl+C（组合键）

屏幕

screen_capture(region?) -> Image (numpy array)
screen_size() -> width, height

参数说明： - region (table, 可选) — 捕获区域 {left, top, width, height}，不传则捕获全屏

示例：

local w, h = screen_size()
log("屏幕分辨率: " .. w .. "x" .. h)

local img = screen_capture({0, 0, 100, 100})  -- 捕获左上角 100x100
image_save_template(img, "screenshot.png")

等待

wait(milliseconds) -> void
wait_seconds(seconds) -> void

示例：

wait(1000)        -- 等待 1000 毫秒（1 秒）
wait_seconds(2.5) -- 等待 2.5 秒

变量

var_set(name, value, scope?) -> void
var_get(name) -> any
var_has(name) -> boolean

参数说明： - name (string) — 变量名 - value (any) — 变量值（支持 string、number、boolean、table） - scope (string, 可选) — 作用域，可选："local"（默认，仅当前脚本可见）、"global"（跨脚本共享）

示例：

var_set("count", 10)
var_set("name", "MacroAI", "global")

local c = var_get("count")
log("count = " .. c)

if var_has("name") then
    log("name 变量存在")
end

区域

region_set(name, left, top, width, height) -> void
region_get(name) -> Region | nil
getRegion(name?) -> {left, top, width, height} | nil
to_runtime_region(region) -> {left, top, width, height}
to_runtime_point(x, y) -> number, number

参数说明： - name (string) — 区域名称 - left, top, width, height (number) — 区域矩形（设计区域坐标） - region (table) — {left, top, width, height} 格式的区域

说明： - region_get 返回 Region 对象（带 .left, .top, .width, .height 属性） - getRegion 返回 Lua table，可指定名称，不传或传 "__effective__" 返回默认搜索区域 - to_runtime_region / to_runtime_point 将设计区域坐标转换为运行时坐标（多分辨率适配）

示例：

region_set("dialog", 100, 200, 500, 300)
local r = region_get("dialog")
if r then
    log("区域: " .. r.left .. "," .. r.top)
end

local rt = getRegion("dialog")           -- {left, top, width, height}
local eff = getRegion()                  -- 默认搜索区域
local pt_x, pt_y = to_runtime_point(500, 300)  -- 转换为运行区域坐标

变化检测

detect_change(kwargs?) -> table
wait_change(kwargs?) -> table
wait_bar_change(kwargs?) -> table

kwargs 参数表：

detect_change / wait_change 通用参数

wait_bar_change 参数

colors 配置格式：

{
    {
        label = "hp_full",             -- 模版名称，同时也是文件名
        template_path = "resources/bar_templates/hp_full.png",
        color_swatch = {255, 50, 50}   -- 由系统自动生成，可不填
    },
    {
        label = "hp_half",
        template_path = "resources/bar_templates/hp_half.png",
        color_swatch = {50, 50, 255}
    }
}

返回值： - detect_change / wait_change 返回变化区域数组： lua { { center_x = 350, center_y = 250, rect = {340, 240, 20, 20} }, ... } - wait_bar_change 返回条块变化数组： lua { { rect = {100, 200, 300, 20}, -- 条块边界框 center_x = 250, -- 条块中心 X center_y = 210, -- 条块中心 Y color = "hp_full", -- 匹配上的模版标签 state = "changed", -- changed/resized/disappeared/appeared delta = 0.5, -- 宽度比例变化（新 label 宽度 / 旧 label 宽度） reference_value = 1.0, -- 旧 label 宽度比例 curr_value = 0.5, -- 新 label 宽度比例 orientation = "horizontal" }, ... }

示例：

-- 检测条块变化（上传两个宽度不同的模版，引擎自动匹配）
local bar_changes = wait_bar_change({
    region = {100, 50, 300, 20},
    timeout = 15,
    colors = {
        {
            label = "full",
            template_path = "resources/bar_templates/full.png",
        },
        {
            label = "half",
            template_path = "resources/bar_templates/half.png",
        }
    }
})

-- 只处理真实变化，忽略移入移出
for _, bc in ipairs(bar_changes) do
    if bc.state == "changed" or bc.state == "resized" then
        log("条块变化: " .. bc.color .. " delta=" .. bc.delta)
    end
end

reset_bar_detector() -> void

重置所有条块追踪缓存。进入新界面时调用，避免旧追踪状态干扰新场景。

示例：

-- 进入新场景时重置追踪
reset_bar_detector()

local bars = wait_bar_change({
    region = {100, 50, 300, 20},
    colors = {
        { label="full", template_path="resources/bar_templates/full.png" },
        { label="half", template_path="resources/bar_templates/half.png" },
    }
})

音频

play_warning(sound_type, custom_file?) -> void
play_music(filepath) -> void
is_music_playing() -> boolean

参数说明： - sound_type (string) — 音效类型： - 系统音效："ding"、"error"、"warning"、"question"、"info" - 系统声音："startup"、"shutdown"、"chimes"、"tada" - 音符："do"、"re"、"mi"、"fa"、"sol"、"la"、"si"（蜂鸣器） - 自定义："custom" - custom_file (string, 可选) — 自定义 WAV 文件路径（sound_type 为 "custom" 时使用） - filepath (string) — 音乐文件路径（支持 MP3、WAV 等格式）

示例：

play_warning("ding")              -- 播放提示音
play_warning("custom", "C:\\alert.wav")  -- 播放自定义 WAV

play_music("C:\\bgm.mp3")        -- 播放背景音乐
if is_music_playing() then
    log("音乐正在播放")
end

日志

log(message) -> void
ocr_log(msg) -> void
print(...) -> void

示例：

log("脚本开始执行")
ocr_log("OCR 识别结果: " .. text)
print("变量值:", x, y, z)  -- 输出: 变量值: 100 200 300

其他

macro_call(macro_id) -> void

说明： - macro_id (string) — 要调用的录制宏 ID - 在运行时会回放该宏中记录的所有事件（鼠标点击、按键、等待等） - 坐标会自动根据当前运行区域缩放适配

示例：

macro_call("macro_12345678")  -- 回放指定录制宏

检查停止

check_stop() -> void

在执行循环或长时间操作时调用，使脚本能够响应暂停和停止信号。如果用户在运行中点击了暂停或停止，check_stop() 会立即中断当前操作。

引擎在部分长时间操作中会自动注入此调用，但自定义循环中建议主动调用。

示例：

for i = 1, 100 do
    check_stop()  -- 让用户可以随时中止
    -- 执行操作...
    wait(500)
end

通用约定

坐标系统

• 所有坐标单位为像素
• 区域格式统一为 {left, top, width, height}
• 坐标会自动根据设计区域和运行区域缩放适配（多分辨率）

返回值约定

• 成功返回有效值，失败返回 nil
• ImageMatchResult 可通过 if r and r.success 判断是否匹配成功