[!NOTE] This document is a machine-translated version of the original Chinese text. In case of any discrepancies, omissions, or ambiguities, the Chinese version shall prevail.

Introduction

MaaFramework is a next-generation automation black-box testing framework, completely rewritten and refined based on image recognition technology and the development experience of MAA.

It offers low-code simplicity while maintaining high extensibility. The framework aims to create a rich, leading-edge, and practical open-source library, empowering developers to easily write better black-box test programs and promoting widespread use.

Get Started

[!TIP] Visit our website for a better documentation experience.
Can't find the relevant documents? Try asking AI !
Discover more community-contributed skills, pipelines, customs, and experiences on MaaHub.

• Quick Start & Terms
• Integration & API
• Pipeline Low-code Protocol
• Project Interface Protocol

Community Project

Generic UI

• MFAAvalonia
  A generic GUI based on Avalonia. Powered by MaaFramework!

• MFW-PyQt6
  A generic GUI based on PyQt6. Powered by MaaFramework!

• MXU
  A lightweight cross-platform generic GUI based on Tauri 2 + React. Powered by MaaFramework!

• MWU
  A lightweight cross-platform generic WebUI based on Vue + FastAPI. Powered by MaaFramework!

• MaaFwApp
  An Android generic GUI based on Kotlin + Jetpack Compose. Powered by MaaFramework!

Development Tool

• MaaDebugger
  MaaFramework Pipeline Debugger

• maa-support-extension
  MaaFramework VSCode Extension

• MFAToolsPlus
  A cross-platform development toolbox built on the Avalonia framework, providing convenient data acquisition and simulation testing methods.

• MaaPipelineEditor
  Visual reading and construction Pipeline, fully functional, extremely lightweight cross-platform, progressive local function extension, seamless compatibility between old and new projects.

• MaaInspector
  A visual editor based on vue-flow — a simple and user-friendly MaaFramework Pipeline Editor that integrates node preview, editing, and debugging all in one.

• MaaLogAnalyzer
  MaaFramework log analysis tool, providing user-friendly, multi-perspective visual analysis of task execution processes.

• prettier-plugin-maafw-sort
  Prettier plugin that sorts pipeline keys according to lifecycle order.

• Auto Green Background
  An automatic green screen painting tool (Python/OpenCV, for TemplateMatch), supporting multi-algorithm segmentation, fixed canvas output, real-time preview, and a portable, out-of-the-box package.

• maafw-cli
  A MaaFramework command-line interface (CLI) for AI Agents.

• maaframework-skills
  Claude Code skill for MaaFramework — structured reference docs for AI-assisted pipeline development.

• MaaOWM
  A MaaFramework multi-resource-pack development tool. Mount: merges base+mod into a full-field workspace; Unmount: diffs out a minimal mod delta.

• create-maa-project
  MaaFW project scaffolding CLI & MCP Server for interactive creation and incremental maintenance of Pipeline / Agent projects.

• MaaEvidenceKit
  Extracts deterministic evidence from MaaFramework logs and project configurations for AI agents, with runtime and static analysis, source location, and task-flow correlation.

• Everything-Maa
  A MaaFramework toolkit for AI-assisted development, providing reusable skills, versioned MCP profiles, and a CLI installer for project creation, Pipeline authoring, testing, and analysis.

• MaaCtl
  A command-line client for MaaFramework / ProjectInterface v2, running PI projects and Pipeline nodes in a fully parameterized way, distributed as a Go single-file executable and an npm (npx / global install) package.

Application

• M9A
  A 1999 Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MSBA
  A Snow break Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MaaYYs
  A brand new Onmyoji assistant powered by advanced architecture. Combining image recognition and simulated control, it automates daily tasks and frees your hands like a cyber-helper! Powered by MaaFramework!

• MPA
  A Punishing Gray Raven Assistant. Image technology + simulation control, freeing your hands! Powered by MistEO's Black Coffee 2.0.

• MRA
  A Warship Girls R Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MaaYuan
  An Ashes of the kingdom Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• Maa-HBR
  An assistant for Heaven Burns Red/HBR. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MaaGF2Exilium
  An automation assistant for Girls' Frontline 2: Exilium, built on a brand-new architecture. Featuring image recognition technology and simulation control to free up your hands! Powered by MaaFramework!

• MaaXuexi
  The Xuexi automation assistant based on a new architecture.Image technology + analogue control to free your hands!Powered by MaaFramework!

• MAA_MHXY_MG
  Fantasy Westward Journey Mobile Assistant Based on New Architecture. Image technology + analogue control to free your hands! Powered by MaaFramework!

• MaaTOT
  A Tears of Themis Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MaaGumballs
  MaaGumballs is an assistant tool driven by image recognition and simulated control. It can help everyone free their hands and start an adventure of brick-breaking with one click, powered by the MaaFramework.

• MMleo
  Little Assistant for EnsembleStars Music. Free your hands with image recognition and simulated control technology! Boost the producer career of hamsters! Powered by MaaFramework!

• SLIMEIM_Maa
  Assistant for the Founding Chronicles of the Demon King and Dragon.Free your hands with image recognition and simulated control technology! Powered by MaaFramework!

• Maa_bbb
  Honkai Impact 3 Mini Assistant. Uses image recognition and simulation control technology to free your hands! Supports both PC and emulator simultaneously, powered by MaaFramework!

• MAN
  Naruto Mobile Mini Assistant. Uses image recognition and simulation control technology to free your hands! Powered by MaaFramework!

• MaaGakumasu
  Assistant for Gakuen Idolmaster. Image recognition + simulation control + deep learning to free your hands! Powered by MaaFramework!

• MaaStarResonance
  Assistant for StarResonance. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• MAG
  Assistant for Aether Gazer. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• MAAAE
  An assistant for Ash Echoes. Image technology + simulation control, freeing your hands! Powered by MaaFramework.

• MBCCtools
  Assistant for Path to Nowhere. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• MaaEOV
  Assistant for Echoes Of Vision. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• MAA Star Resonance
  A helper for Star Resonance. Using Electron + text image recognition + ADB simulation control technology, freeing your hands! Powered by MaaFramework and Quasar.

• StellaSora-Auto-Helper
  Assistant for Stella Sora. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• MaaDuDuL
  Assistant for Trickcal. Image technology + simulation control, automatic pinch face, free hands! Powerfully driven by MaaFramework!

• MaaLYSK
  Assistant for Love and Deepspace. Image technology + simulation control, automatic pinch face, free hands! Powerfully driven by MaaFramework!

• MaaEnd
  An Endfield assistant powered by MaaFramework and MXU, still under active development.

• MaaGFNeuralCloud
  An assistant tool for Girls' Frontline: Project Neural Cloud using MaaFramework.

• MaaFgo
  FGO Assistant. Featuring image recognition and simulated control for a truly hands-free experience! Powered by MaaFramework.

• MALW
  Touhou LostWord Assistant. Image recognition + simulation control to free your hands! Powered by MaaFramework!

• AUTO-MAS
  A unified management and automation tool for multiple configurations—your script butler. Integrated with MaaFramework components to expand the boundaries of scripting capabilities!

• MR3A
  A Ninja Must Die 3 Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework!

• Maa_Kes
  Kes Dreamscape Assistant. Built on MaaFramework. Uses image recognition and simulated control technology to support both PC and emulator, freeing your hands! Powered by MaaFramework!

• MAK
  Maa 雪松 Assistant! Powered by MaaFramework!

• MAH
  A assistant for Tokyo Afterschool Summoners. Free your hands! Powered by MaaFramework!

• MATR
  A Touken Ranbu Assistant. Image technology + simulation control, freeing your hands! Powered by MaaFramework!

• MaaADr
  An assistant for AnotherEidos Of Dragon Vein R(AnaDos). Powered by MaaFramework!

• MFABD2
  A Brown Dust 2 assistant. Image technology + simulation control, freeing your hands! Supports PC, emulator and PlayCover. Powered by MaaFramework!

• MaaWoA
  An assistant for World of Airports. Image technology + simulation control, freeing your hands! Powered by MaaFramework!

• MAES
  Ensemble Stars!! Music rhythm-game auto-play assistant focused on song play and lane calibration. Powered by MaaFramework.

• MaaPVZ
  PVZ2 (Plants vs. Zombies 2) assistant. Image recognition + simulation control, powered by MaaFramework, bringing you a delightful gaming experience!

Eco-Building

MAA is planned to be a category of projects rather than just a single piece of software.

If your project depends on MaaFramework, we welcome you to name it as MaaXXX, MXA, MAX, and so on. Of course, this is permission, not limitation. You can freely choose other names unrelated to MAA, depending on your own ideas!

We also welcome you to submit a PR to add your project to the community projects list above!

Statement and License

Open Source License

This project is open-sourced under the LGPL-3.0 license.

Distribution Notice

This project supports GPU acceleration, which relies on an independent component provided by Microsoft: DirectML for the Windows platform. DirectML is not part of this project's open-source codebase and is not governed by the LGPL-3.0 license. For user convenience, an unmodified copy of the DirectML.dll file is included in the installation package. If GPU acceleration is not required, you may safely delete this DLL file without affecting the core functionality of the software.

The Windows, Linux and macOS prebuilt dependencies also include a WebGPU inference library based on Dawn (libwebgpu_dawn). macOS no longer ships CoreML.

Disclaimer

Intended Use

This project is intended to provide automated black-box testing tools for software development, including image recognition, UI operation simulation, and other legitimate technical scenarios. Developers must ensure that their use of the project complies with all applicable laws, regulations, and the terms of service of the target software.

Prohibited Misuse

The use of this project for the following purposes is strictly prohibited (including but not limited to):

• Disrupting, circumventing, or interfering with the normal functioning of any software, game, or service (such as anti-cheat mechanisms or authorization systems).
• Developing or distributing tools that violate third-party terms of service (such as game cheats, hacking tools, or automation scripts).
• Engaging in any illegal activity or actions that infringe upon the legitimate rights of others (such as data theft or cyberattacks).

Liability Disclaimer

This project is provided "as is". The author assumes no responsibility for any direct, indirect, or consequential damages resulting from:

• User actions that violate this statement or applicable laws and regulations.
• Damages caused by third-party tools developed using this project (e.g., account bans, legal disputes).
• Any technical or financial losses incurred from the use of this project.

User Responsibilities

By using this project, you agree to:

• Assume all risks associated with its use.
• Ensure that your use case is legal and properly authorized (e.g., with permission from the target software vendor).
• Take full responsibility for any legal issues arising from your actions and hold the project author harmless from any liability.

Development

Please note that you only need to read this chapter if you are ready to develop MaaFramework itself. If you only want to develop applications based on MaaFramework, please refer to Get Started.

• How to build
• API Design

Acknowledgments

Open Source Libraries

• opencv
  Open Source Computer Vision Library
• fastdeploy
  ⚡️An Easy-to-use and Fast Deep Learning Model Deployment Toolkit for ☁️Cloud 📱Mobile and 📹Edge.
• onnxruntime
  ONNX Runtime: cross-platform, high performance ML inferencing and training accelerator
• boost
  Boost provides free peer-reviewed portable C++ source libraries.
• libzmq
  ZeroMQ core engine in C++, implements ZMTP/3.1
• cppzmq
  Header-only C++ binding for libzmq
• meojson
  ✨ Next-gen C++ JSON/JSON5 Serialization Engine | Zero Dependency | Header-Only | Unleash JSON Potential
• minitouch
  Minimal multitouch event producer for Android.
• maatouch
  Android native implementation of minitouch input protocol
• minicap
  Stream real-time screen capture data out of Android devices.
• zlib
  A massively spiffy yet delicately unobtrusive compression library.
• gzip-hpp
  Gzip header-only C++ library
• ViGEmClient
  ViGEm Client SDK for feeder development.
• protobuf
  Protocol Buffers - Google's data interchange format
• grpc
  The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)
• thrift
  Apache Thrift

Inspiration

• MaaAssistantArknights
  《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.
  MaaFramework references the implementation ideas of the ADB controller in MAA, but does not use any of its source code.
• ok-script
  全新 Python 游戏自动化框架(支持 Windows 和模拟器)
  MaaFramework references the implementation ideas of the Win32 controller in ok-script, but does not use any of its source code.

Developers

Thanks to the following developers for their contributions to MaaFramework:

Discussion

Developers are welcome to join the official QQ group (595990173) for integration and development discussions. The group is reserved for engineering topics; product-usage support is not provided, and off-topic or spam accounts may be removed to keep the channel focused.

Sponsor