aradotso/maante-game-automation

MaaNTE Game Automation Assistant

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).

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

---

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.

---

Installation (Developers)

1. Fork & Clone with Submodules

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

2. Install Python Dependencies

pip install -r requirements.txt

3. Download MaaFramework

Download the MaaFramework release and extract it into the deps/ folder:

MaaNTE/
  deps/
    MaaFramework/
      bin/
      include/
      lib/

4. Recommended IDE Setup

• Use VSCode with the maa-support extension for pipeline debugging.

---

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)

---

Key Concepts: MaaFramework Pipeline

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.

Pipeline Task Node Structure

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

Common Recognition Types

| Type | Description | |---|---| | TemplateMatch | Find image template on screen | | OCR | Optical character recognition | | ColorMatch | Match pixel color | | DirectHit | Always triggers (no recognition) |

Common Action Types

| Action | Description | |---|---| | Click | Click matched region | | Swipe | Swipe gesture | | Key | Press keyboard key | | StartApp | Launch application | | StopApp | Stop application | | Custom | Call Python custom action |

---

Python Custom Action Example

Custom actions let you write Python logic triggered from pipeline tasks.

# 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)


# Register and start agent server
if __name__ == "__main__":
    AgentServer.start_up(AgentServer.parse_argv())
    server = AgentServer()
    server.register_custom_action("MyCustomAction", MyCustomAction())
    server.join()

Referencing Custom Action in Pipeline

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

---

Python Custom Recognizer Example

# 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")

---

Running in Development Mode

# Run with default config
python main.py

# The GUI is provided by MFAAvalonia (separate executable)
# For pipeline-only testing use MaaFramework CLI tools in deps/

---

interface.json Configuration

The GUI (MFAAvalonia) reads interface.json to build the task selection UI:

{
  "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.

---

Pipeline Development Workflow

1. Capture Template Images

Use the maa-support VSCode extension or MaaFramework's built-in screencap:

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)

2. Define Pipeline Task

{
  "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

The extension lets you run individual pipeline nodes and visualize recognition results directly in the editor.

---

Adding a New Feature (PR Workflow)

# Always branch from dev for new features
git checkout dev
git pull upstream dev
git checkout -b feature/my-new-task

# Add pipeline JSON in pipeline/
# Add any custom Python in custom/
# Update interface.json to expose task in GUI

git add .
git commit -m "feat: add auto-xxx task"
git push origin feature/my-new-task
# Open PR targeting the dev branch

---

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

"Mirror酱 not supported" popup

• Harmless — auto-update is not configured. Ignore it.

Template matching fails / tasks stuck

# 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]
  }
}

Controller connection fails

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}")

Coffee automation mouse issues

• Set input method to Seize in interface.json / GUI settings
• Do not move mouse while task is running

---

Key External References

• MaaFramework Docs
• MFAAvalonia GUI
• M9A Dev Docs (Chinese) — architecture and pipeline patterns reference
• maa-support VSCode Extension
• QQ Group 1 | QQ Group 2
• Official Bilibili