USAGE.md 9.9 KB

GameUi 使用说明

模块结构

  • game_ui.py 公开导出 GameUi、NavigatorSession、Page,供任务继续按旧导入路径使用。
  • page.py 公开导出 Page、Transition、组合 matcher、组合 action,以及所有全局页面定义。
  • common.py 共享类型与内部工具函数。
  • matcher.py 页面识别条件组合器。
  • action.py 页面跳转动作与 hook 动作组合器。
  • page_definition.py Page 与 Transition 的核心定义。
  • registry.py 进程级静态页面注册表。
  • session.py 任务级导航 session,保存页面快照、边惩罚、局部未知页关闭规则。
  • navigator.py GameUi 导航引擎实现。
  • default_pages.py 全局页面定义。

新版 Page 怎么定义

1. 最基础的页面

from tasks.GameUi.page import Page
from tasks.SomeTask.assets import SomeTaskAssets

page_some_main = Page(SomeTaskAssets.I_CHECK_MAIN)

说明:

  • 第一个参数是页面识别条件 recognizer
  • 可以直接传 RuleImage、RuleGif、RuleOcr
  • 不显式传 category 时,会根据文件路径自动推断
  • priority 默认是 50,范围 1-100,值越大在多页面同时命中时越优先返回
  • tasks/GameUi 下定义的页面默认分类为 global

1.1 页面优先级

page_result = Page(
    SomeAssets.I_CHECK_RESULT,
    priority=70,
)

说明:

  • priority 仅影响“多个页面在同一帧同时命中”时的返回顺序
  • 系统会按 priority 降序判定;同优先级保持 session 注册顺序稳定
  • 超出 1-100 时会自动 clamp,并输出 warning 日志
  • 运行时修改 session 页面副本的 priority,不会污染全局注册表

2. 识别条件可以组合

from tasks.GameUi.page import Page, any_of, all_of, not_

page_reward = Page(
    any_of(
        SomeAssets.I_REWARD_A,
        SomeAssets.I_REWARD_B,
    )
)

可用组合器:

  • any_of(...) 任一条件命中即可
  • all_of(...) 所有条件都命中才成功
  • not_(...) 对条件取反

3. 识别条件可以使用自定义函数

def check_custom(task) -> bool:
    return task.appear(SomeAssets.I_CHECK_MAIN) and not task.appear(SomeAssets.I_DIALOG)


page_custom = Page(check_custom)

说明:

  • 自定义函数会收到当前运行时的 task
  • 可以直接调用当前任务对象上的所有公开方法
  • 返回值必须是布尔值

4. 页面 hook

page_main.add_enter_success_hooks(
    SomeAssets.I_CLOSE_DIALOG,
    lambda task: task.click(SomeAssets.C_SAFE_AREA, interval=0.5),
)

页面支持 4 个阶段:

  • on_enter_success 成功进入该页面后触发
  • on_enter_failure 尝试进入该页面失败后触发
  • on_leave_success 成功离开该页面后触发
  • on_leave_failure 尝试离开该页面失败后触发

可用写法:

  • page.add_enter_success_hooks(...)
  • page.add_enter_failure_hooks(...)
  • page.add_leave_success_hooks(...)
  • page.add_leave_failure_hooks(...)

旧版 additional 的语义,等价于新版 on_enter_success。

5. 页面跳转边

page_main.connect(page_shop, SomeAssets.I_GOTO_SHOP, key="page_main->page_shop")
page_shop.connect(page_main, SomeAssets.I_BACK_Y, key="page_shop->page_main")

说明:

  • connect(destination, action, ...) 用来声明一条有向边
  • action 是执行跳转时的动作
  • 推荐为边显式提供稳定的 key
  • 可以为边单独定义四阶段 hook

6. 动作组合

from tasks.GameUi.page import sequence, conditional_action

page_main.connect(
    page_event,
    sequence(SomeAssets.I_OPEN_PANEL, SomeAssets.I_GOTO_EVENT),
    key="page_main->page_event",
)

page_event.add_enter_success_hooks(
    conditional_action(SomeAssets.I_POPUP, SomeAssets.I_CLOSE_POPUP)
)

可用组合器:

  • sequence(...) 顺序执行多个动作
  • conditional_action(condition, action) 只有条件命中时才执行动作

页面分类规则

  • tasks/GameUi 内定义的页面默认属于 global
  • 其他任务的 page.py / inner_page.py 页面默认按任务目录名归类
  • 导航到目标页面时: 构图使用 当前页面分类 + 目标页面分类 + global
  • 当前页面未知时: 构图回退为 目标页面分类 + global
  • 识别当前页时: 使用 当前任务分类 + 目标页面分类 + global

这意味着:

  • 全局页面可作为所有任务的公共中转页
  • 不同任务页面不会在同一轮导航中互相污染

新公共方法

pages_in_category(category)

battle_pages = self.pages_in_category("battle")

说明:

  • 返回当前 task session 内指定分类的页面副本列表
  • 不会触发截图、识别或任何点击
  • 调用方可以安全修改返回页面的 priority / recognizer

detect_page_in(*targets, include_global=True)

self.detect_page_in("battle")
self.detect_page_in("battle", "exploration")
self.detect_page_in("battle", include_global=False)
self.detect_page_in(page_battle_prepare, page_battle_result, include_global=False)

说明:

  • targets 可以传分类字符串,也可以直接传 Page
  • 使用与 get_current_page() 相同的“两帧稳定识别”逻辑
  • 默认自动把 global 加入识别范围,便于识别意外弹回主页等全局页面
  • 只传 Page 时,仅在这些显式页面副本中识别
  • 传 include_global=False 时,只在显式给定分类内识别
  • 多个候选同时命中时,同样按 priority 降序返回

动态页面怎么写

动态页面不要直接注册到全局表,必须只放在当前任务 session 中。

from tasks.GameUi.page import Page

page_dynamic = self.navigator.add_page(
    Page(
        self.I_CHECK_DYNAMIC,
        key="page_dynamic",
        name="page_dynamic",
        register=False,
    )
)

说明:

  • register=False 表示不要进入全局 PageRegistry
  • self.navigator.add_page(...) 表示把该页面加入当前任务 session
  • 动态页的跳转边也应该只连接到 session 页面对象

运行时改链怎么做

如果任务需要临时修改页面图,不要改全局定义,必须改当前 session 副本。

page_main = self.navigator.resolve_page(pages.page_main)
page_records = self.navigator.resolve_page(pages.page_shikigami_records)

page_main.remove_transition(key="page_main->page_shikigami_records")
page_records.clear_transitions()
page_records.connect(page_main, self.I_BACK_Y, key="page_shikigami_records->page_main")

说明:

  • resolve_page(...) 会把静态页面定义解析成当前任务 session 中的页面副本
  • 所有运行时改链都只改 session,不会污染别的任务

未知页关闭规则怎么加

self.navigator.add_unknown_closer(self.I_CUSTOM_CLOSE)

说明:

  • 任务级规则会优先于全局默认规则执行
  • 只在当前任务 session 生效
  • 任务结束后自动失效

goto_page 的流程是什么

goto_page(destination) 的执行流程如下:

  1. 先把 destination 解析成当前任务 session 中的页面对象
  2. 优先确认缓存的 current_page 是否仍然成立
  3. 如果缓存页失效,则在允许分类集合里做两帧稳定识别
  4. 如果当前页未知:
    • 先尝试 close_unknown_pages()
    • 成功则重置无进展超时计时器
    • 失败且超过超时则抛 GamePageUnknownError
  5. 如果当前页就是目标页:
    • 再做一次两帧稳定确认
    • 成功后触发进入成功 hook,并打印到达日志
  6. 如果当前页不是目标页:
    • 在 当前页分类 + 目标分类 + global 图中运行 Dijkstra
    • 计算代价 = 页面 cost + 边 cost + 边失败惩罚
  7. 如果能构建路径:
    • 按最小总代价路径执行每一条边
    • 每次成功推进到下一页,都重置无进展超时
  8. 如果某条边执行失败:
    • 触发页面/边的失败 hook
    • 给该边增加惩罚
    • 重新识别当前页并重新规划路径
    • 如果同一条边连续失败 3 次,则额外主动尝试一次 close_unknown_pages()
    • 主动关闭成功才重置无进展超时;关闭 miss 仍沿用原有惩罚、重规划和超时链路
  9. 如果连续 timeout 秒没有任何有效进展:
    • 输出当前页、目标页、候选页命中结果、重复失败边、连续失败次数、边惩罚、未知页关闭历史等诊断日志
    • 抛出 GamePageUnknownError

页面判定规则

  • 当前页识别: 连续 2 帧命中才算成功
  • 页面进入成功: 连续 2 帧识别到目标页面才算成功
  • 页面离开成功: 以识别到下一页面为准,不是以“动作已经点击”为准

推荐写法

静态任务页面

from tasks.GameUi.page import Page, page_main

page_my_task = Page(MyAssets.I_CHECK_MAIN)
page_main.connect(page_my_task, MyAssets.I_ENTER, key="page_main->page_my_task")
page_my_task.connect(page_main, MyAssets.I_BACK, key="page_my_task->page_main")

任务运行

class ScriptTask(GameUi, MyAssets):
    def run(self):
        self.goto_page(page_my_task)

动态页 + 运行时改链

class ScriptTask(GameUi, MyAssets):
    def before_run(self):
        self.page_dynamic = self.navigator.add_page(
            Page(self.I_CHECK_DYNAMIC, key="page_dynamic", name="page_dynamic", register=False)
        )
        page_main = self.navigator.resolve_page(pages.page_main)
        page_main.connect(self.page_dynamic, self.I_ENTER_DYNAMIC, key="page_main->page_dynamic")

注意事项

  • 不要再使用旧接口: ui_goto、ui_goto_page、ui_get_current_page、try_close_unknown_page、run_additional
  • 不要再直接操作旧运行时字段: ui_current、ui_close、links
  • 动态页一定要使用 register=False
  • 任务级改链一定要通过 self.navigator.resolve_page(...) 获取 session 页面后再修改
  • 如果页面是临时弹层,优先写成进入成功 hook 或未知页关闭规则,不要把它误建成主导航页面