maante-game-automation

# MaaNTE Game Automation Assistant

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

MaaNTE is an automation assistant for the game **Neverness to Everness (异环)**, built on [MaaFramework](https://github.com/MaaXYZ/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

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

### 2. Install Python Dependencies

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

### 3. Download MaaFramework

Download the [MaaFramework release](https://github.com/MaaXYZ/MaaFramework/releases) and extract it into the `deps/` folder:

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

### 4. Recommended IDE Setup

- Use **VSCode** with the [maa-support extension](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 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

```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

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

```python
# 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

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

---

## Python Custom Recognizer Example

```python
# 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

```bash
# 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:

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

---

## Pipeline Development Workflow

### 1. Capture Template Images

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

# Save screenshot for template
image = controller.cached_image
import cv2
cv2.imwrite("assets/template/my_element.png", image)
```

### 2. Define Pipeline Task

```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

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

---

## Adding a New Feature (PR Workflow)

```bash
# 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
```python
# 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
```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}")
```

### 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](https://github.com/MaaXYZ/MaaFramework)
- [MFAAvalonia GUI](https://github.com/SweetSmellFox/MFAAvalonia)
- [M9A Dev Docs (Chinese)](https://1999.fan/zh_cn/develop/development.html) — architecture and pipeline patterns reference
- [maa-support VSCode Extension](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
- [QQ Group 1](https://qm.qq.com/q/1103323319) | [QQ Group 2](https://qm.qq.com/q/1101147419)
- [Official Bilibili](https://space.bilibili.com/3546893080594665)