jokymouse.screen API

jokymouse.screen 模块通过 require("jokymouse.screen") 加载，提供屏幕尺寸、颜色判断和找图能力，适合在自动化流程中定位按钮、图标和状态标记，或者通过像素颜色确认界面状态。

local screen = require("jokymouse.screen")

可用函数

函数	签名	说明
size	`screen.size()`	返回主显示器宽高两个值
get_color	`screen.get_color(x, y)`	读取指定坐标颜色
is_color	`screen.is_color(x, y, color, tolerance?)`	判断指定坐标是否为目标颜色
wait_color	`screen.wait_color(x, y, color, opts?)`	等待某点变成目标颜色
find_color	`screen.find_color(color, opts?)`	在指定区域查找第一个目标颜色
find_image_one	`screen.find_image_one(template_path, opts?)`	返回首个匹配点；未找到返回 `nil`
find_image_all	`screen.find_image_all(template_path, opts?)`	返回全部匹配点数组

屏幕尺寸

size

local screen = require("jokymouse.screen")

local width, height = screen.size()
print(width, height)

颜色能力

颜色结构

颜色函数统一使用下面的颜色结构：

{
  r = 255,
  g = 204,
  b = 0,
  hex = "#ffcc00"
}

支持两种传参写法：

"#ffcc00"

或：

{ r = 255, g = 204, b = 0 }

get_color

local screen = require("jokymouse.screen")

local color = screen.get_color(640, 360)
print(color)

is_color

local screen = require("jokymouse.screen")

if screen.is_color(640, 360, "#ffcc00", 8) then
  print("按钮已点亮")
end

tolerance 表示每个颜色通道允许的最大误差，范围 0..255，默认 0。

wait_color

local screen = require("jokymouse.screen")

local ok = screen.wait_color(640, 360, "#52c41a", {
  timeout_ms = 3000,
  interval_ms = 100,
  tolerance = 6
})

if not ok then
  error("等待颜色超时")
end

支持字段：

字段	类型	默认值	说明
timeout_ms	`integer`	`3000`	最长等待时间
interval_ms	`integer`	`100`	每次轮询间隔
tolerance	`integer`	`0`	每个颜色通道容差

find_color

local screen = require("jokymouse.screen")

local point = screen.find_color("#ff4d4f", {
  region = { x = 100, y = 80, width = 800, height = 600 },
  tolerance = 10
})

if point then
  print(point)
end

返回值包含：

x：屏幕绝对坐标 x
y：屏幕绝对坐标 y
color：实际命中的颜色结构

find_color 支持的 opts 字段：

字段	类型	默认值	说明
region	`table`	`nil`	限定搜索区域
tolerance	`integer`	`0`	每个颜色通道容差

找图能力

找图函数都会在返回结果中包含：

x：屏幕绝对坐标 x
y：屏幕绝对坐标 y
score：匹配分数（范围 0 到 1，越高越接近模板）

template_path

类型：string
含义：模板图片路径
规则：
- 绝对路径会直接使用。
- 相对路径会以脚本目录为基准解析。

查找参数 opts

类型：table（可选）

支持字段：

字段	类型	默认值	说明
threshold	`number`	`0.95`	匹配阈值，范围 `0..1`
max_results	`integer`	`50`	最大返回条数，仅 `find_image_all` 使用
region	`table`	`nil`	限定搜索区域，减少耗时
grayscale	`boolean`	`true`	是否先转灰度再匹配
fast	`boolean`	`false`	`true` 使用快速算法，`false` 使用 imageproc

region 结构：

{
  x = 100,
  y = 200,
  width = 800,
  height = 600
}

width 与 height 必须为正整数。

find_image_one

local jm = require("jokymouse")
local screen = require("jokymouse.screen")

local hit = screen.find_image_one("assets/start_button.png", {
  threshold = 0.92,
  fast = false,
  region = { x = 120, y = 80, width = 1000, height = 700 }
})

if hit then
  jm.move_to(hit.x, hit.y)
  jm.mouse_click("left")
else
  jm.exit("未找到开始按钮")
end

find_image_all

local screen = require("jokymouse.screen")

local points = screen.find_image_all("assets/reward_icon.png", {
  threshold = 0.9,
  max_results = 20
})

for _, p in ipairs(points) do
  print(p)
end

约束与性能

模板图读取失败时会抛错（路径错误、格式不支持、文件损坏）。
在 macOS 上，如果未授予屏幕录制权限，截图阶段会失败。
匹配是像素级扫描，模板越大、搜索区域越大，耗时越高。
优先提供 region，避免全屏扫描。
使用尺寸较小且特征明显的模板图。
先用 find_image_one 做流程判断，确有需要再使用 find_image_all。
默认推荐保持 grayscale = true。
默认使用 fast = false，优先走更稳的 imageproc。
当搜索区域较大、需要更高速度时，再尝试 fast = true。

如果你需要配合输入控制或任务并发，请参考 jokymouse API。