快速上手 NIKKEAutoScript 页面导航:Page 页面图模型与 ui_ensure 路由原理完整指南
快速上手 NIKKEAutoScript 页面导航:Page 页面图模型与 ui_ensure 路由原理完整指南
NIKKEAutoScript 是《胜利女神:NIKKE》自动日常脚本,支持 PC 客户端与模拟器。它的日常、出击、竞技场等任务都依赖同一个能力——页面导航:脚本通过 ui_ensure 配合 Page 页面图模型,先模板匹配定位当前界面,再基于反向 BFS 规划路径,像人一样逐级点击按钮抵达目标页,全程无需写死坐标。本文完整剖析这套页面导航机制的设计原理。
NIKKEAutoScript 的任务调度器界面如下,日常、出击、限定作战等任务被排入队列后,脚本会自动在游戏的各个界面间"跑腿":
问题:脚本如何知道"我在哪、该点哪"?
NIKKE 的界面层级很深:主界面、每日奖励、前哨基地、方舟、竞技场、聊天、背包……每个界面里还有大量弹窗。对图像识别脚本来说,写死每一步坐标极其脆弱——分辨率、语言、版本更新都会让点击失效。
NIKKEAutoScript 的答案是维护一张完整的页面转移表:
- 用"页面特征图"(模板匹配)识别当前所在页面;
- 用图论方法算出从当前页到目标页的跳转路径;
- 沿路径逐步点击按钮,每点一步重新识别,直到抵达。
三个核心角色都在 module/ui/ 目录下:Page 类(节点)、Button 类(边上的按钮)、ui_ensure 方法(路由器)。
Page 页面图模型:用模板匹配识别当前页面
每个游戏页面被抽象成一个 Page 节点,定义在 module/ui/page.py。节点的"身份证"是一个 check_button——该页面独有的特征模板图:
page_arena = Page(ARENA_CHECK) # 竞技场页:用 ARENA_CHECK 模板识别
page_arena.link(button=GOTO_BACK, destination=page_ark) # 按"返回"可回到方舟
page_ark.link(button=ARK_GOTO_ARENA, destination=page_arena) # 方舟里点按钮可进竞技场
Page(check_button):绑定页面识别模板。运行时用cv2.matchTemplate在截图上找这块特征图,相似度超过阈值就判定"我在该页面",见 module/base/button.py 的match()方法;link(button, destination):声明一条出边——在这个页面上点击button这个按钮,就能到达destination页面。所有边都存进节点的links字典,即links[destination] = button。
全部 40 个页面(主界面、每日、商店、邮件、招募、聊天、试炼塔、竞技场系、前哨基地设施……)及其跳转关系都在这一个文件里注册完毕,构成一张有向图。所有按钮的模板图片、坐标、颜色信息则由生成器统一维护在 module/ui/assets.py。
💡
Page的name属性很巧妙:它通过traceback读取创建语句的变量名(如page_arena),日志里直接打印人类可读的页面名,见 module/ui/page.py。
反向 BFS 寻路:ui_goto 如何规划跳转路径
识别到当前页后,剩下的问题是"怎么走"。核心算法在 module/ui/ui.py 的 ui_goto 中,分两阶段:
阶段一:反向广度搜索(BFS),算出每个页面的"父节点"。
从目标页出发,反复执行:"找所有 links 指向已访问页面的页面,把它们加入访问集合,并记录它们的 parent 指向"。例如目标为竞技场(page_arena):
visited = {竞技场}
第1轮: 谁的 links 里有竞技场? → 方舟 visited = {竞技场, 方舟}
第2轮: 谁的 links 里有方舟? → 主界面 visited = {竞技场, 方舟, 主界面}
第3轮: 无新增,结束
parent 关系: 主界面→方舟, 方舟→竞技场
结束后,每个页面只知道一件事:该点哪个按钮,就能朝目标靠近一步。这正是 module/ui/ui.py 中文注释所描述的过程。
阶段二:运行时逐跳逼近。 进入死循环,每轮先检查"目标页特征图出现了吗?",没有就在已访问页面里找当前所在的页,点击它通往 parent 的按钮,重新截图再来一轮。confirm_wait 参数控制"到达确认"时长——页面特征图持续出现该时长才判定真正到达,防止页面切换动画中的假阳性。
ui_ensure:三步完成"确认 + 导航"
业务模块从不直接操作坐标,只需要一行,比如日常模块在 module/daily/daily.py 中调用 self.ui_ensure(page_daily)。module/ui/ui.py 中 ui_ensure 的逻辑只有三步:
- 定位:
ui_get_current_page截图并遍历 ui_pages 中全部 40 个页面的特征图,谁匹配成功谁就是当前页(带(30, 30)像素的偏移容差,吸收不同客户端的细微像素漂移); - 短路:当前页 == 目标页,直接返回
False,零操作; - 寻路:调用
ui_goto沿 parent 链逐级点击,返回True。
这就是为什么任务调度器可以放心地连续派发任务——无论脚本上一步停在哪,ui_ensure 都能把"现场"接过来。
容错设计:弹窗、加载与未知页面
真实游戏从不"配合"脚本,ui_ensure 的健壮性来自三层防线:
| 场景 | 应对机制 | 代码位置 |
|---|---|---|
| 加载中转圈 | 识别 4 种 UI_LOADING 特征图并等待其稳定消失 |
ui_wait_loading |
| 未知页面/加载界面 | 点击通用的 GOTO_MAIN(主界面按钮),重置超时重试 |
ui_get_current_page |
| 等级提升、奖励、公告、月卡等弹窗 | ui_additional 逐个 handler 拦截处理,并通配 CONFIRM_A/B/C 三类确认按钮 |
ui_additional |
| 30 秒内仍无法识别 | 抛出 GamePageUnknownError,日志列出所有受支持页面,提示用户手动切到支持页再启动 |
ui_get_current_page |
另外,页面识别前会先校验游戏进程是否在运行、屏幕方向是否横屏(module/ui/ui.py),避免在异常状态下盲目点击。
扩展阅读:新增一个页面要做什么?
如果你想为脚本添加新页面,流程也非常直观,全部集中在 module/ui/page.py:
- 用 dev_tools/ 目录下的模板捕获工具截取页面特征图与跳转按钮;
- 在 module/ui/assets.py 生成对应的
Button定义; - 创建
Page节点,用link()把它接入现有图; - 把节点加入 UI.ui_pages 识别列表。
图结构自动接管后续导航,无需改动任何任务逻辑。
总结
NIKKEAutoScript 的页面导航体系可以概括为一张表和一条路由:
- Page 页面图模型:
check_button负责"我在哪"(模板匹配),links负责"我能去哪"(按钮边),共同构成 40 节点的游戏页面有向图,见 module/ui/page.py; - ui_ensure 路由:定位 → 短路判断 → 反向 BFS 寻路 → 逐跳点击,配合
confirm_wait到达确认与ui_additional弹窗拦截,实现稳定的全自动界面切换,见 module/ui/ui.py; - 业务解耦:日常、出击、竞技场等所有模块只调用一行
ui_ensure(page_xxx),完全不关心路径细节。
这种"图模型 + 反向 BFS"的设计,让脚本既避免了脆弱的坐标写死,又能在弹窗和加载中转场时自愈,是 NIKKEAutoScript 能跨语言、跨客户端稳定运行的关键基础。

