MaaNTE是怎么自动化游戏的：MaaFramework图像识别Pipeline架构深度解析

MaaNTE是怎么自动化游戏的：MaaFramework图像识别Pipeline架构深度解析

【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE

MaaNTE 是一款面向游戏《异环》（NTE）的开源游戏自动化助手，基于 MaaFramework 图像识别引擎与声明式 Pipeline 架构构建。它不修改任何游戏数据，而是通过"截图 → 图像识别 → 模拟点击/按键"的循环，自动完成做咖啡、钓鱼、退钱、四格电波等重复性任务。本文带你用一篇看懂：MaaNTE 的 Pipeline 图像识别架构是如何把"看屏幕"变成"会操作"的。

🎮 先认识 MaaNTE：它到底自动化了什么

MaaNTE 支持的功能全部由"任务"驱动，每个任务背后是一套图像识别流程，例如：

下面这张"异晶开采凭证"月卡奖励界面，就是一个典型的自动化场景——MaaNTE 通过图像识别锁定"点击领取今日奖励"区域，无需人工盯着屏幕：

🏗️ 整体架构：四层分工的自动化引擎

MaaNTE 把自动化拆成四层，各司其职：

┌─────────────────────────────────────────────┐ │ ④ 任务配置层 tasks/*.json + interface.json │ 用户选什么任务、什么参数 ├─────────────────────────────────────────────┤ │ ③ Python 逻辑层 agent/custom/action/ │ Pipeline 表达不了的复杂算法 ├─────────────────────────────────────────────┤ │ ② Pipeline 流程层 assets/resource/base/pipeline│ 识别→动作→跳转 的声明式流程图 ├─────────────────────────────────────────────┤ │ ① 控制与识别层 MaaFramework + 模板/OCR 模型 │ 截图、找图、读字、鼠标键盘 └─────────────────────────────────────────────┘

• 控制层：MaaFramework 的 Win32 控制器负责截取游戏窗口画面并注入鼠标/键盘事件。四种控制器（前台、后台、云游戏等）统一在 assets/interface.json 中声明。
• 识别层：内置模板匹配（TemplateMatch）、OCR 文字识别、颜色匹配（ColorMatch）等算法，配合 assets/MaaNTEModels 中的识别模型工作。
• 流程层：用 Pipeline JSON 声明"什么画面该做什么动作"，是 MaaNTE 的核心表达层。
• 逻辑层：用 Python 编写 CustomAction，处理 Pipeline 难以表达的难点，如实时听音躲避、节奏游戏判帧。

官方开发者文档对这一分层有完整定义，见 AGENTS.md 与 getting-started.md。

📸 Pipeline 节点：识别 → 动作 → 再识别的闭环

MaaNTE 的第一铁律是：永远先识别、再操作，绝不假设"点了按钮后画面一定变成什么样"。每个 Pipeline 节点就是一个"当前画面是什么 + 我做什么 + 下一步去哪"的三元组：

"TouchDetect": { "recognition": { "type": "OCR", "param": { "expected": ["抚摸"] } }, "action": { "type": "DoNothing" }, "next": ["TouchPressF"] }

三个关键设计：

1. next列表覆盖所有可能画面。首个命中的节点被执行，因此节点会同时覆盖"正常主流程 + 弹窗 + 加载中 + 跑偏回退"，力争一次截图命中、不做盲目重试。
2. [JumpBack]中断处理。命中后先执行完该分支，再自动跳回父节点继续识别——弹窗、加载动画都靠它优雅消化。
3. 1280×720 基准坐标。所有模板图、ROI、点击坐标都基于 720p 窗口，其他分辨率由框架自动换算，这就是文档反复强调"游戏请设为 1280x720 窗口化"的原因。

完整的节点字段说明见官方 Pipeline 编写指南。

🔍 图像识别工具箱：6 种算法各管一摊

MaaNTE 的"眼睛"由 6 类识别算法组成，选型直接决定了流程的稳定度：

看下面这张"确认退出"弹窗就明白了：MaaNTE 可以用 OCR 识别"是否确认退出？"文字区域，或用 TemplateMatch 定位"取消/确认"按钮，进而决定点哪个——这正是自动退出流程（如 SceneExitComfirm.png 模板 所对应的识别资源）能稳定工作的基础：

一个容易忽略的工程细节：模板图必须从无损原图裁剪并缩放到 720p，且优先用 ROI 限定搜索区域——缩小搜索范围，既是准确率也是速度。

🧭 场景管理器：从任意界面"自动回家"

开放世界游戏最大的难题是"人不在正确的界面"。MaaNTE 的 SceneManager 用两层接口 + 层级回退解决这个问题：

• 公共接口层（Interface/Scene/）：如SceneAnyEnterWorld（从任意界面回大世界）、SceneLoading（等加载结束），Pipeline 任务只允许引用这些稳定接口。
• 私有实现层（SceneManager/，节点名以__ScenePrivate开头）：负责实际的点击导航，随版本变化而不影响上层任务。

工作原理是一个递归回退链：想进入都市大亨？先试直接进；不行就回退到"先进大世界"，进大世界再不行就回退到"点 Esc 菜单"，一层层兜底：

SceneAnyEnterCityTycoonsMenu ├── 直接进入都市大亨（按快捷键） ├── 确认已进入 └── [JumpBack] → SceneAnyEnterWorld → [JumpBack] → Esc菜单……

这就是为什么 Scene.json 里一个接口能挂着一长串[JumpBack]分支——每次识别失败都先"把环境整理干净"，再重新尝试，避免死循环。完整原理见 scene-manager.md。

🐍 Pipeline 管流程，Python 管难点

有些任务纯靠"找图+点击"表达不了：俄罗斯方块要识别整个棋盘并计算最优旋转，躲避技能要实时监听声音，钢琴演奏要处理 MIDI 时序。这时 MaaNTE 用Custom 节点桥接 Python：

"action": { "type": "Custom", "param": { "custom_action": "auto_make_coffee", "custom_action_param": { "count": 10 } } }

Python 侧通过@AgentServer.custom_action("auto_make_coffee")注册同名实现，就能在 agent/custom/action/ 里拿到当前截图（numpy 数组），任意调用 OpenCV/模板匹配/听音等库。约定很简单：只有 Pipeline 表达不了的逻辑才写 Python，识别结果用AnalyzeResult返回、动作用RunResult返回失败即优雅降级。详见 custom-action.md。

🚀 动手跑起来：如何阅读 MaaNTE 源码

想亲手验证这套架构，按下面三步走：

1. 拉取代码并初始化环境（依赖 Git 与 Python 3.11+，两个识别模型子模块必须初始化）：

   git clone --recurse-submodules https://gitcode.com/gh_mirrors/maa/MaaNTE cd MaaNTE && python -m venv .venv && pip install -r requirements.txt

2. 启动 Agent 服务：运行 agent/main.py，它会自动创建虚拟环境、安装依赖并连接 MaaFramework 的 socket。

3. 按层读源码，推荐路径：

   • 流程全貌 → assets/resource/base/pipeline/（每个任务一个目录，如AutoCoffee/、Fish/）
   • 场景回退 → Interface/Scene/
   • 任务选项 → assets/resource/tasks/（switch/input/select 三种参数类型）
   • 复杂逻辑 → agent/custom/action/（Tetris、Navi、SoundTrigger 等）
   • 开发规范 → docs/zh_cn/develop/

✅ 总结：MaaNTE 架构的三个关键设计

1. 状态驱动的闭环："识别 → 操作 → 再识别"是铁律，next列表全量覆盖画面状态，从根上消灭盲目重试。
2. 声明式与命令式分离：80% 的流程用 Pipeline JSON 声明，开发者可视化维护；剩下 20% 的难点交给 Python CustomAction，扩展互不干扰。
3. 分层接口隔离变化：SceneManager 的公共接口/私有实现分层，让"导航逻辑变了"不需要改动任何上层任务。

如果你想给 MaaNTE 加一个新任务，记住一句话就够了：先识别，后操作；流程写 JSON，难点写 Python。

【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE