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
全局页面定义。from tasks.GameUi.page import Page
from tasks.SomeTask.assets import SomeTaskAssets
page_some_main = Page(SomeTaskAssets.I_CHECK_MAIN)
说明:
recognizerRuleImage、RuleGif、RuleOcrcategory 时,会根据文件路径自动推断priority 默认是 50,范围 1-100,值越大在多页面同时命中时越优先返回tasks/GameUi 下定义的页面默认分类为 globalpage_result = Page(
SomeAssets.I_CHECK_RESULT,
priority=70,
)
说明:
priority 仅影响“多个页面在同一帧同时命中”时的返回顺序priority 降序判定;同优先级保持 session 注册顺序稳定1-100 时会自动 clamp,并输出 warning 日志session 页面副本的 priority,不会污染全局注册表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_(...)
对条件取反def check_custom(task) -> bool:
return task.appear(SomeAssets.I_CHECK_MAIN) and not task.appear(SomeAssets.I_DIALOG)
page_custom = Page(check_custom)
说明:
taskpage_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。
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 是执行跳转时的动作keyfrom 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 内定义的页面默认属于 globalpage.py / inner_page.py 页面默认按任务目录名归类当前页面分类 + 目标页面分类 + global目标页面分类 + global当前任务分类 + 目标页面分类 + global这意味着:
pages_in_category(category)battle_pages = self.pages_in_category("battle")
说明:
priority / recognizerdetect_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 可以传分类字符串,也可以直接传 Pageget_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
表示不要进入全局 PageRegistryself.navigator.add_page(...)
表示把该页面加入当前任务 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 中的页面副本self.navigator.add_unknown_closer(self.I_CUSTOM_CLOSE)
说明:
goto_page(destination) 的执行流程如下:
destination 解析成当前任务 session 中的页面对象current_page 是否仍然成立close_unknown_pages()GamePageUnknownError当前页分类 + 目标分类 + global 图中运行 Dijkstraclose_unknown_pages()timeout 秒没有任何有效进展:
GamePageUnknownErrorfrom 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_additionalui_current、ui_close、linksregister=Falseself.navigator.resolve_page(...) 获取 session 页面后再修改