---

name: maante description: "Repo-specific operating guidance for MaaNTE Neverness to Everness MaaFramework automation tasks, pipeline JSON, Python custom actions, navigation, audio, minigame, and maintainer workflows." disable-model-invocation: true metadata: disco-role: operating license: AGPL 3.0

MaaNTE Repo Skill

Purpose

Use this repo skill when working on MaaNTE, a MaaFramework-based automation assistant for Neverness to Everness (异环 / NTE). It helps future agents understand the repository's task catalog, Pipeline JSON conventions, Python CustomAction/CustomRecognition code, real-time navigation stack, audio and rhythm automation, packaging expectations, and common troubleshooting paths without reopening the original source documentation.

MaaNTE automates a live Windows game through image/OCR/color recognition and simulated input. Always respect the repository's disclaimer and user intent: keep changes limited to normal gameplay automation, do not help modify game files, bypass protections, or create unfair/unsafe tooling, and call out account-risk implications when relevant.

First Checks

1. Confirm the working tree is a MaaNTE checkout by checking for assets/interface.json, agent/main.py, assets/resource/tasks/, and assets/resource/base/pipeline/.
2. Read references/repo-provenance.md before relying on version-sensitive details; refresh this skill if the current checkout differs materially from the recorded snapshot.
3. For installation, build, and runtime constraints, read references/setup-and-runtime.md.
4. Run the safe environment/catalog helpers when useful:
   • python scripts/check_maante_environment.py --summary
   • python scripts/inspect_task_catalog.py --repo-root <checkout>
5. Choose the focused sub-skill below; do not keep all detailed context in the root.

Sub-Skill Routing

Need	Read
Add or modify Pipeline JSON nodes, task option JSON, i18n keys, controller restrictions, SceneManager routes, or JSON formatting	sub-skills/pipeline-development/SKILL.md
Add or modify Python CustomAction/CustomRecognition classes, action registration, MaaFramework Python APIs, logging, maafocus messages, controller input, or runtime state	sub-skills/custom-actions/SKILL.md
Understand or edit user-facing gameplay tasks such as fishing, coffee, rewards, fountain check-in, city-tycoon income/restock, furniture, bid king, pink paw heist, presets, touch, or character ability sync	sub-skills/gameplay-tasks/SKILL.md
Work on local route navigation, map teleport, online map WebSocket broadcasting, coordinate capture, real-time assistance, movement tests, or dataset collection	sub-skills/navigation-realtime/SKILL.md
Work on sound dodge/counter, rhythm game, auto piano MIDI playback, Tetris AI, BagelSpam posting, or AutoFScroll pickup automation	sub-skills/media-minigames/SKILL.md

Repo-Level Rules to Keep in Mind

• Runtime assets assume a 1280×720 game window. Pipeline coordinates, ROI rectangles, click targets, and screenshots are all designed for that baseline.
• MaaNTE uses MaaFramework Pipeline v2 style in newer nodes: nested recognition: {type, param} and action: {type, param}. Some older nodes still use flat shorthand; preserve local style unless refactoring the whole node family.
• Prefer recognition-driven transitions: identify a screen state, act once, then recognize again. Avoid blind multi-click chains and broad retry loops.
• Explicitly set rate_limit: 0, pre_delay: 0, and post_delay: 0 when a node truly needs no default MaaFramework waits.
• Public SceneManager interfaces live under Interface/Scene/; task pipelines should not jump directly to private __ScenePrivate* nodes.
• Python actions are for logic that Pipeline cannot express. Register actions with @AgentServer.custom_action("snake_case_name") or recognitions with @AgentServer.custom_recognition("snake_case_name"), then import them in agent/custom/action/__init__.py.
• User-facing messages from Python should go through utils.maafocus.Print() or PrintT(). Use utils.logger for developer/debug logging; avoid raw print() in user-facing actions.
• Long-running loops must check context.tasker.stopping and release held keys/buttons in finally blocks.
• New or changed tasks usually require updates in: a task JSON file, one or more Pipeline JSON files, five interface locale files, and assets/interface.json imports.

Installation and Validation Summary

Use Python 3.11+ for development. The runtime package set is requirements-driven and includes MaaFramework (maafw), OpenCV/Pillow/NumPy/SciPy/scikit-learn, librosa/soundcard/mido for audio/MIDI workflows, onnxruntime-directml for Windows DirectML navigation inference, networking packages for coordinate capture and WebSocket routes, and build packaging utilities.

Common safe checks:

python -m py_compile agent/custom/action/**/*.py
python scripts/check_maante_environment.py --summary
python scripts/inspect_task_catalog.py --repo-root .

Full UI/node validation still depends on Maa Pipeline Support, a Windows game window, MaaFramework resources, and the chosen Win32 controller mode. Do not claim real gameplay verification from Linux-only import checks.

References

• references/repository-map.md summarizes the repo layout and selected extraction scope.
• references/setup-and-runtime.md covers installation, build modes, controller/runtime assumptions, and backend notes.
• references/task-catalog.md maps MaaNTE task families, entries, options, and controllers.
• references/maa-framework-patterns.md records verified MaaFramework Python binding facts and Pipeline semantics used across sub-skills.
• references/troubleshooting.md covers cross-cutting failures: imports, paths, controller modes, resolution, OCR/assets, optional backends, and logs.
• references/repo-routing-metadata.json is structured metadata for managed repo-skill router import.