窗口与窗口上下文
SRA 的所有识别与操作都发生在「目标窗口」内。为了在本地游戏窗口与云游戏网页之间共用同一套逻辑,
SRA 用 WindowContext 描述窗口的位置、尺寸与标识,由 Operator 统一维护,任务与扩展只关心相对窗口的坐标。
本文介绍窗口的定位方式、坐标系约定、整屏模式与截图行为。
WindowContext
Section titled “WindowContext”WindowContext 定义在 SRACore/operators/model.py,是一个普通的 dataclass:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
top |
int |
0 |
目标区域左上角的屏幕 Y 坐标(由 SRA 自动刷新) |
left |
int |
0 |
目标区域左上角的屏幕 X 坐标(由 SRA 自动刷新) |
width |
int |
0 |
目标区域宽度(像素) |
height |
int |
0 |
目标区域高度(像素) |
window_title |
str |
崩坏:星穹铁道 |
目标窗口标题,用于查找窗口 |
executable |
str |
StarRail.exe |
目标进程名,用于启动与结束游戏 |
full_screen |
bool |
False |
整屏操作模式:忽略窗口,以整个屏幕为操作区域 |
top / left / width / height 不需要手动填写:每次截图前 SRA 都会重新读取窗口客户区的实际位置与尺寸并写回,
因此窗口被拖动、缩放后仍能正确定位。
Operator 的所有坐标参数(click_point、move_to、mouse_down、drag_to 等)遵循统一规则:
| 写法 | 含义 | 示例 |
|---|---|---|
int |
窗口客户区内的像素坐标(原点为客户区左上角) | click_point(960, 540) |
float |
相对窗口宽高的比例(0–1) | click_point(0.5, 0.5) |
偏移量 x_offset / y_offset 同样按类型解释:int 为像素,float 为窗口比例,因此可以只对单个方向使用比例。
click_point 还提供 mode 参数以强制指定解释方式,适合从 JSON / 配置读入坐标、无法区分 1 与 1.0 的场景:
auto(默认):按参数类型推断;abs:强制按像素;rel:强制按窗口比例。
识别类方法(locate、ocr_boxes、detect_color 等)返回的 Box 同样是客户区坐标,
可直接交给 click_box 使用,无需再换算。
窗口的查找与刷新
Section titled “窗口的查找与刷新”本地实现(Operator)通过 pygetwindow 按 window_title 查找窗口,行为如下:
- 标题需与
window_title完全一致(忽略首尾空格),避免误匹配到标题相近的其他窗口; - 句柄会被缓存,每次使用前用
IsWindow校验,句柄失效(例如游戏重启)时自动重新查找; - 找不到窗口时句柄为
0,hwnd属性返回0;云游戏等无窗口实现固定返回0。
is_window_active() / active_window() 用于判断与切换前台窗口。
active_window() 会先模拟按一次 ctrl,让系统将该操作视为用户输入,从而允许 SetForegroundWindow 生效。
from SRACore.operators.factory import OperatorFactory
operator = OperatorFactory.get_operator()operator.window_context.window_title = "崩坏:星穹铁道"
if not operator.is_window_active(): operator.active_window() # 切换到游戏窗口获取窗口区域
Section titled “获取窗口区域”Operator.get_win_region(active_window=True) 返回当前操作区域 Region:
active_window=True(默认):先把窗口切到前台,再读取客户区(不含标题栏与边框)的屏幕坐标;active_window=False:不激活窗口,仅刷新句柄,配合后台截图使用。
读取失败时抛出 RuntimeError 并给出原因,常见于:
- 游戏未启动:句柄为
0; - 窗口被最小化:客户区宽或高为
0。
整屏操作模式
Section titled “整屏操作模式”将 full_screen 置为 True(通常通过 set_window_context(full_screen=True))后:
- 操作区域退化为整个屏幕,
left/top归零,width/height取屏幕尺寸; - 比例坐标按整屏而非窗口计算;
- 截图强制走屏幕抓取,因为后台截图只能拿到窗口自身的内容。
该模式适合独占全屏、无法按窗口定位的场景;窗口化运行时保持默认值 False 即可。
operator.set_window_context( window_title="崩坏:星穹铁道", executable="StarRail.exe", full_screen=False,)set_window_context 只覆盖传入的参数,其余字段保留原值。注意参数为 None 或假值(如 False、空字符串)时同样保留原值,
因此无法用它把已开启的整屏模式改回 False,需要直接修改 operator.window_context.full_screen。
截图方式由两个开关共同决定:调用参数 background 控制是否激活窗口,实例属性 screenshot_background
控制采用哪种截图实现。
| 开关 | 作用 |
|---|---|
background=True(调用参数) |
不激活窗口(get_win_region(active_window=False)),配合后台截图使用 |
screenshot_background=True |
默认值,本地实现使用 Win32 PrintWindow(PW_CLIENTONLY + PW_RENDERFULLCONTENT),可后台截取且不被遮挡 |
screenshot_background=False |
使用 pyscreeze.screenshot(region=...) 抓取屏幕,要求窗口可见且在前台 |
即默认配置(screenshot_background=True、窗口化)下始终走后台截图,截图不要求窗口在前台;
StartGameTask 会在登录阶段临时把 screenshot_background 设为 False,改用屏幕抓取获取登录界面。
此外:
- 整屏模式下始终使用屏幕抓取;
- 传入
from_x/from_y/to_x/to_y时,在窗口客户区内按比例裁剪; resize可缩放输出,save_path可落盘;jpeg_quality仅建议用于预览等体积敏感场景, OCR / 模板匹配等内部调用不要使用有损压缩。
模板匹配依赖固定分辨率,SRA 要求游戏客户区为 1920×1080:
- 1080p 下可直接使用全屏;
- 更高分辨率的显示器可将游戏窗口化到 1920×1080。
任务失败时 BaseTask.on_failed 会检查 window_context 的宽高,若不符合要求会输出警告,
例如 可能的失败原因:游戏分辨率不符合要求:1920x1080,当前:2560x1440。
云游戏(BrowserOperator)
Section titled “云游戏(BrowserOperator)”基于浏览器云游戏的实现使用同一套 WindowContext,差异如下:
type为"Browser",hwnd固定为0,is_window_active()恒为True;- 启动时先设为 1920×1080,拿到驱动后以页面实际视口(
window.innerWidth/window.innerHeight) 为准更新宽高,避免浏览器边框、工具栏造成比例偏差; - 无头模式通过 CDP 把渲染视口直接设为目标分辨率。
因此任务代码中尽量不要硬编码绝对像素坐标,优先使用比例坐标,才能在本地与云游戏之间通用。
Region:带parent的矩形区域,sub_region()可在当前区域内按比例划分子区域;Box:识别结果矩形,提供center(中心点)、text/source(来源,模板路径或 OCR 文本)与distance()。
from tasks.img import IMG
box = operator.wait_img(IMG.ENTER, timeout=30)if box is not None: operator.click_box(box, y_offset=-10) # 点击中心点上方 10 像素处