Back to Details

maante-game-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MaaNTE Game Automation Assistant

MaaNTE 游戏自动化助手

Skill by ara.so — Daily 2026 Skills collection.
MaaNTE is an automation assistant for the game Neverness to Everness (异环), built on MaaFramework (image-recognition-based black-box automation). It automates repetitive tasks: fishing (with auto-sell fish & auto-buy bait), coffee-making (with customer management), and cafe revenue extraction (with auto-restocking).
由 ara.so 开发的 Skill — 属于 Daily 2026 Skills 合集。
MaaNTE 是针对游戏《异环（Neverness to Everness）》的自动化助手，基于 MaaFramework（基于图像识别的黑盒自动化框架）构建。它可自动完成重复任务：钓鱼（包含自动卖鱼和自动买鱼饵）、制作咖啡（包含顾客管理）以及咖啡馆收益提取（包含自动补货）。

Requirements

运行要求

  • Windows OS
  • Python >= 3.11
  • Game running at 1280×720 resolution, windowed mode
  • Run as Administrator
  • Program path must not contain Chinese characters
  • Disable antivirus software if detection issues arise
  • Windows 操作系统
  • Python 版本 ≥ 3.11
  • 游戏需运行在1280×720 分辨率的窗口模式下
  • 以管理员身份运行
  • 程序路径不得包含中文字符
  • 若出现检测问题，请关闭杀毒软件

Installation (End Users)

安装（终端用户）

Download the latest release from GitHub Releases — no cloning needed:
https://github.com/1bananachicken/MaaNTE/releases
Extract and run the GUI executable directly.
从 GitHub Releases 下载最新版本，无需克隆仓库：
https://github.com/1bananachicken/MaaNTE/releases
解压后直接运行 GUI 可执行文件。

Installation (Developers)

安装（开发者）

1. Fork & Clone with Submodules

1. Fork 并带子模块克隆仓库

bash
git clone --recursive https://github.com/<your-username>/MaaNTE.git
cd MaaNTE
bash
git clone --recursive https://github.com/<your-username>/MaaNTE.git
cd MaaNTE

2. Install Python Dependencies

2. 安装 Python 依赖

bash
pip install -r requirements.txt
bash
pip install -r requirements.txt

3. Download MaaFramework

3. 下载 MaaFramework

Download the MaaFramework release and extract it into the 
deps/
folder:
MaaNTE/
  deps/
    MaaFramework/
      bin/
      include/
      lib/
下载 MaaFramework 发行版 并解压到 
deps/
文件夹中：
MaaNTE/
  deps/
    MaaFramework/
      bin/
      include/
      lib/

4. Recommended IDE Setup

4. 推荐 IDE 配置

Project Structure

项目结构

MaaNTE/
├── assets/
│   └── logo.png
├── deps/                  # MaaFramework binaries (not committed)
├── pipeline/              # JSON pipeline task definitions
│   ├── fishing/
│   ├── coffee/
│   └── cafe/
├── custom/                # Python custom action/recognizer scripts
├── docs/
│   └── README_en.md
├── interface.json         # MFAAvalonia GUI configuration
└── main.py                # Entry point (dev mode)
MaaNTE/
├── assets/
│   └── logo.png
├── deps/                  # MaaFramework 二进制文件（未提交到仓库）
├── pipeline/              # JSON 流水线任务定义
│   ├── fishing/
│   ├── coffee/
│   └── cafe/
├── custom/                # Python 自定义操作/识别器脚本
├── docs/
│   └── README_en.md
├── interface.json         # MFAAvalonia GUI 配置文件
└── main.py                # 入口文件（开发模式）

Key Concepts: MaaFramework Pipeline

核心概念：MaaFramework 流水线

Tasks are defined in JSON pipeline files. Each task node specifies how to find a UI element (via image template or OCR) and what action to take.
任务通过 JSON 流水线文件定义。每个任务节点指定如何查找 UI 元素（通过图像模板或 OCR）以及执行何种操作。

Pipeline Task Node Structure

流水线任务节点结构

json
{
  "TaskName": {
    "recognition": "TemplateMatch",
    "template": "fishing/float.png",
    "roi": [0, 0, 1280, 720],
    "action": "Click",
    "next": ["NextTask"],
    "timeout": 10000,
    "on_error": ["ErrorHandlerTask"]
  }
}
json
{
  "TaskName": {
    "recognition": "TemplateMatch",
    "template": "fishing/float.png",
    "roi": [0, 0, 1280, 720],
    "action": "Click",
    "next": ["NextTask"],
    "timeout": 10000,
    "on_error": ["ErrorHandlerTask"]
  }
}

Common Recognition Types

常见识别类型

TypeDescription
TemplateMatch
Find image template on screen
OCR
Optical character recognition
ColorMatch
Match pixel color
DirectHit
Always triggers (no recognition)
TypeDescription
TemplateMatch
在屏幕上查找图像模板
OCR
光学字符识别
ColorMatch
像素颜色匹配
DirectHit
直接触发（无需识别）

Common Action Types

常见操作类型

ActionDescription
Click
Click matched region
Swipe
Swipe gesture
Key
Press keyboard key
StartApp
Launch application
StopApp
Stop application
Custom
Call Python custom action
ActionDescription
Click
点击匹配区域
Swipe
滑动手势
Key
按下键盘按键
StartApp
启动应用程序
StopApp
停止应用程序
Custom
调用 Python 自定义操作

Python Custom Action Example

Python 自定义操作示例

Custom actions let you write Python logic triggered from pipeline tasks.
python
undefined
自定义操作允许你编写从流水线任务触发的 Python 逻辑。
python
undefined

custom/my_action.py

custom/my_action.py

from maa.agent.agent_server import AgentServer from maa.custom_action import CustomAction from maa.context import Context from maa.define import RectType import json
class MyCustomAction(CustomAction): def run( self, context: Context, argv: CustomAction.RunArg, ) -> CustomAction.RunResult: # Access current task arguments task_name = argv.task_name custom_param = json.loads(argv.custom_action_param)
    # Take a screenshot and find something
    image = context.tasker.controller.cached_image
    
    # Run a sub-pipeline task
    context.run_pipeline("AnotherTask")
    
    # Click at specific coordinates
    context.tasker.controller.post_click(640, 360).wait()
    
    return CustomAction.RunResult(success=True)
from maa.agent.agent_server import AgentServer from maa.custom_action import CustomAction from maa.context import Context from maa.define import RectType import json
class MyCustomAction(CustomAction): def run( self, context: Context, argv: CustomAction.RunArg, ) -> CustomAction.RunResult: # 获取当前任务参数 task_name = argv.task_name custom_param = json.loads(argv.custom_action_param)
    # 截图并查找目标
    image = context.tasker.controller.cached_image
    
    # 运行子流水线任务
    context.run_pipeline("AnotherTask")
    
    # 点击指定坐标
    context.tasker.controller.post_click(640, 360).wait()
    
    return CustomAction.RunResult(success=True)

Register and start agent server

注册并启动代理服务器

if name == "main": AgentServer.start_up(AgentServer.parse_argv()) server = AgentServer() server.register_custom_action("MyCustomAction", MyCustomAction()) server.join()
undefined
if name == "main": AgentServer.start_up(AgentServer.parse_argv()) server = AgentServer() server.register_custom_action("MyCustomAction", MyCustomAction()) server.join()
undefined

Referencing Custom Action in Pipeline

在流水线中引用自定义操作

json
{
  "TriggerMyAction": {
    "recognition": "DirectHit",
    "action": "Custom",
    "custom_action": "MyCustomAction",
    "custom_action_param": "{\"key\": \"value\"}"
  }
}
json
{
  "TriggerMyAction": {
    "recognition": "DirectHit",
    "action": "Custom",
    "custom_action": "MyCustomAction",
    "custom_action_param": "{\"key\": \"value\"}"
  }
}

Python Custom Recognizer Example

Python 自定义识别器示例

python
undefined
python
undefined

custom/my_recognizer.py

custom/my_recognizer.py

from maa.custom_recognizer import CustomRecognizer from maa.context import Context import numpy as np
class MyCustomRecognizer(CustomRecognizer): def analyze( self, context: Context, argv: CustomRecognizer.AnalyzeArg, ) -> CustomRecognizer.AnalyzeResult: image = argv.image # numpy array (H, W, C) BGR
    # Your image analysis logic here
    # Example: check average color in a region
    roi = image[300:400, 600:700]
    mean_color = np.mean(roi, axis=(0, 1))
    
    found = mean_color[2] > 200  # high red channel
    
    if found:
        # Return bounding box of found region
        return CustomRecognizer.AnalyzeResult(
            box=(600, 300, 100, 100),  # x, y, w, h
            detail="found red region"
        )
    
    return CustomRecognizer.AnalyzeResult(box=None, detail="not found")

---
from maa.custom_recognizer import CustomRecognizer from maa.context import Context import numpy as np
class MyCustomRecognizer(CustomRecognizer): def analyze( self, context: Context, argv: CustomRecognizer.AnalyzeArg, ) -> CustomRecognizer.AnalyzeResult: image = argv.image # numpy 数组 (H, W, C) BGR 格式
    # 此处编写你的图像分析逻辑
    # 示例：检测某区域的平均颜色
    roi = image[300:400, 600:700]
    mean_color = np.mean(roi, axis=(0, 1))
    
    found = mean_color[2] > 200  # 红色通道值较高
    
    if found:
        # 返回目标区域的边界框
        return CustomRecognizer.AnalyzeResult(
            box=(600, 300, 100, 100),  # x, y, w, h
            detail="找到红色区域"
        )
    
    return CustomRecognizer.AnalyzeResult(box=None, detail="未找到目标")

---

Running in Development Mode

开发模式运行

bash
undefined
bash
undefined

Run with default config

使用默认配置运行

python main.py
python main.py

The GUI is provided by MFAAvalonia (separate executable)

GUI 由 MFAAvalonia 提供（独立可执行文件）

For pipeline-only testing use MaaFramework CLI tools in deps/

仅测试流水线可使用 deps/ 中的 MaaFramework CLI 工具


---

---

interface.json Configuration

interface.json 配置

The GUI (MFAAvalonia) reads 
interface.json
to build the task selection UI:
json
{
  "name": "MaaNTE",
  "version": "1.0.0",
  "tasks": [
    {
      "name": "自动钓鱼",
      "entry": "StartFishing",
      "option": [
        {
          "name": "自动卖鱼",
          "cases": [
            {"name": "开启", "pipeline_override": {"SellFish": {"enabled": true}}},
            {"name": "关闭", "pipeline_override": {"SellFish": {"enabled": false}}}
          ]
        }
      ]
    },
    {
      "name": "自动做咖啡",
      "entry": "StartCoffee"
    }
  ],
  "controller": [
    {
      "name": "Win32",
      "type": "Win32",
      "screencap": "FramePool",
      "input": "Seize"
    }
  ]
}
⚠️ Auto-coffee requires 
input: "Seize"
 — this takes over mouse control while running.
GUI（MFAAvalonia）读取 
interface.json
来构建任务选择界面：
json
{
  "name": "MaaNTE",
  "version": "1.0.0",
  "tasks": [
    {
      "name": "自动钓鱼",
      "entry": "StartFishing",
      "option": [
        {
          "name": "自动卖鱼",
          "cases": [
            {"name": "开启", "pipeline_override": {"SellFish": {"enabled": true}}},
            {"name": "关闭", "pipeline_override": {"SellFish": {"enabled": false}}}
          ]
        }
      ]
    },
    {
      "name": "自动做咖啡",
      "entry": "StartCoffee"
    }
  ],
  "controller": [
    {
      "name": "Win32",
      "type": "Win32",
      "screencap": "FramePool",
      "input": "Seize"
    }
  ]
}
⚠️ 自动制作咖啡需要设置 
input: "Seize"
 — 运行时会接管鼠标控制权。

Pipeline Development Workflow

流水线开发流程

1. Capture Template Images

1. 捕获模板图像

Use the maa-support VSCode extension or MaaFramework's built-in screencap:
python
from maa.toolkit import Toolkit
from maa.controller import Win32Controller

Toolkit.init_option("./")
controller = Win32Controller(
    hWnd=Toolkit.find_window("", "NTE_WindowTitle")
)
controller.post_connection().wait()
使用 VSCode 的 maa-support 扩展或 MaaFramework 内置的截图功能：
python
from maa.toolkit import Toolkit
from maa.controller import Win32Controller

Toolkit.init_option("./")
controller = Win32Controller(
    hWnd=Toolkit.find_window("", "NTE_WindowTitle")
)
controller.post_connection().wait()

Save screenshot for template

保存截图作为模板

image = controller.cached_image import cv2 cv2.imwrite("assets/template/my_element.png", image)
undefined
image = controller.cached_image import cv2 cv2.imwrite("assets/template/my_element.png", image)
undefined

2. Define Pipeline Task

2. 定义流水线任务

json
{
  "DetectFishBite": {
    "recognition": "TemplateMatch",
    "template": "fishing/fish_bite_indicator.png",
    "threshold": 0.85,
    "roi": [500, 400, 300, 200],
    "action": "Click",
    "next": ["RecastLine"],
    "timeout": 30000
  }
}
json
{
  "DetectFishBite": {
    "recognition": "TemplateMatch",
    "template": "fishing/fish_bite_indicator.png",
    "threshold": 0.85,
    "roi": [500, 400, 300, 200],
    "action": "Click",
    "next": ["RecastLine"],
    "timeout": 30000
  }
}

3. Test with VSCode maa-support

3. 使用 VSCode maa-support 测试

The extension lets you run individual pipeline nodes and visualize recognition results directly in the editor.
该扩展允许你运行单个流水线节点，并在编辑器中直接可视化识别结果。

Adding a New Feature (PR Workflow)

添加新功能（PR 流程）

bash
undefined
bash
undefined

Always branch from dev for new features

始终从 dev 分支创建新功能分支

git checkout dev git pull upstream dev git checkout -b feature/my-new-task
git checkout dev git pull upstream dev git checkout -b feature/my-new-task

Add pipeline JSON in pipeline/

在 pipeline/ 中添加流水线 JSON

Add any custom Python in custom/

在 custom/ 中添加自定义 Python 代码

Update interface.json to expose task in GUI

更新 interface.json 在 GUI 中暴露任务

git add . git commit -m "feat: add auto-xxx task" git push origin feature/my-new-task
git add . git commit -m "feat: add auto-xxx task" git push origin feature/my-new-task

Open PR targeting the dev branch

发起指向 dev 分支的 PR


---

---

Troubleshooting

故障排查

Fishing not working

钓鱼功能无法正常工作

  • ✅ Run as Administrator
  • ✅ Game resolution exactly 1280×720, windowed
  • ✅ Auto-fishing checkbox enabled in GUI
  • ✅ Path to MaaNTE has no Chinese/special characters
  • ✅ Antivirus disabled or MaaNTE whitelisted
  • ✅ 以管理员身份运行
  • ✅ 游戏分辨率严格设置为1280×720，窗口模式
  • ✅ GUI 中已勾选自动钓鱼选项
  • ✅ MaaNTE 的路径不含中文或特殊字符
  • ✅ 已关闭杀毒软件或将 MaaNTE 加入白名单

"Mirror酱 not supported" popup

弹出“Mirror酱 not supported”提示

  • Harmless — auto-update is not configured. Ignore it.
  • 无影响——未配置自动更新，可忽略该提示。

Template matching fails / tasks stuck

模板匹配失败/任务卡住

python
undefined
python
undefined

Debug: lower threshold temporarily

调试：临时降低阈值

{ "MyTask": { "recognition": "TemplateMatch", "template": "my_template.png", "threshold": 0.7, # default 0.8, lower = more lenient "roi": [0, 0, 1280, 720] } }
undefined
{ "MyTask": { "recognition": "TemplateMatch", "template": "my_template.png", "threshold": 0.7, # 默认 0.8，值越低匹配越宽松 "roi": [0, 0, 1280, 720] } }
undefined

Controller connection fails

控制器连接失败

python
from maa.toolkit import Toolkit
python
from maa.toolkit import Toolkit

List all available windows

列出所有可用窗口

windows = Toolkit.find_window_list("", "") for w in windows: print(f"hwnd={w.hwnd} class={w.class_name} title={w.window_name}")
undefined
windows = Toolkit.find_window_list("", "") for w in windows: print(f"hwnd={w.hwnd} class={w.class_name} title={w.window_name}")
undefined

Coffee automation mouse issues

咖啡自动化鼠标问题

  • Set input method to 
    Seize
    in interface.json / GUI settings
  • Do not move mouse while task is running
  • 在 interface.json 或 GUI 设置中将输入方式设为 
    Seize
  • 任务运行时请勿移动鼠标

Key External References

核心外部参考资源