快速上手 NIKKEAutoScript 页面导航:Page 页面图模型与 ui_ensure 路由原理完整指南

原创2026-10-28 18:57:521,922 阅读

快速上手 NIKKEAutoScript 页面导航:Page 页面图模型与 ui_ensure 路由原理完整指南

NIKKEAutoScript 是《胜利女神:NIKKE》自动日常脚本,支持 PC 客户端与模拟器。它的日常、出击、竞技场等任务都依赖同一个能力——页面导航:脚本通过 ui_ensure 配合 Page 页面图模型,先模板匹配定位当前界面,再基于反向 BFS 规划路径,像人一样逐级点击按钮抵达目标页,全程无需写死坐标。本文完整剖析这套页面导航机制的设计原理。

NIKKEAutoScript 的任务调度器界面如下,日常、出击、限定作战等任务被排入队列后,脚本会自动在游戏的各个界面间"跑腿":

NIKKEAutoScript 任务调度器界面:自动日常脚本在多个游戏页面间导航执行任务

问题:脚本如何知道"我在哪、该点哪"?

NIKKE 的界面层级很深:主界面、每日奖励、前哨基地、方舟、竞技场、聊天、背包……每个界面里还有大量弹窗。对图像识别脚本来说,写死每一步坐标极其脆弱——分辨率、语言、版本更新都会让点击失效。

NIKKEAutoScript 的答案是维护一张完整的页面转移表:

  1. 用"页面特征图"(模板匹配)识别当前所在页面;
  2. 用图论方法算出从当前页到目标页的跳转路径;
  3. 沿路径逐步点击按钮,每点一步重新识别,直到抵达。

三个核心角色都在 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 参数控制"到达确认"时长——页面特征图持续出现该时长才判定真正到达,防止页面切换动画中的假阳性。

NIKKE 冠军竞技场活动界面:脚本通过页面图模型自动导航至竞技场页面执行任务

ui_ensure:三步完成"确认 + 导航"

业务模块从不直接操作坐标,只需要一行,比如日常模块在 module/daily/daily.py 中调用 self.ui_ensure(page_daily)。module/ui/ui.py 中 ui_ensure 的逻辑只有三步:

  1. 定位:ui_get_current_page 截图并遍历 ui_pages 中全部 40 个页面的特征图,谁匹配成功谁就是当前页(带 (30, 30) 像素的偏移容差,吸收不同客户端的细微像素漂移);
  2. 短路:当前页 == 目标页,直接返回 False,零操作;
  3. 寻路:调用 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:

  1. 用 dev_tools/ 目录下的模板捕获工具截取页面特征图与跳转按钮;
  2. 在 module/ui/assets.py 生成对应的 Button 定义;
  3. 创建 Page 节点,用 link() 把它接入现有图;
  4. 把节点加入 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 能跨语言、跨客户端稳定运行的关键基础。

登录后查看全文
NIKKEAutoScript