MaaFramework Go Binding

English | 简体中文

Go binding for MaaFramework, a cross-platform automation testing framework based on image recognition.

No Cgo Required! Pure Go implementation using purego. Android builds are the exception; see the Android build guide.

Features

• Cross-platform Controllers - ADB, Win32, Linux, macOS, PlayCover, and Android Native
• Recording and Replay - Capture controller operations to JSONL, then replay them for debugging and regression testing
• Virtual Gamepad Controller (Windows only) - Gamepad automation via ViGEm
• Toolkit Utilities - Find ADB devices and desktop windows; manage macOS automation permissions
• Image Recognition - Template matching, OCR, and feature detection
• Custom Extensions - Custom recognitions, actions, and controllers in pure Go
• Agent Support - Run custom recognition and action logic from an external process
• Async Jobs and Events - Poll job status and task details, or subscribe to resource, controller, and tasker events
• Pipeline v2 model APIs - Typed builders emit nested v2 JSON

Requirements

• Go 1.25 or later
• MaaFramework - Tracks the latest MaaFramework release, including prereleases; compatibility with older releases is not guaranteed. The header badge records the MaaFramework release that passed unit tests before this binding's latest release; it is a tested baseline, not a version requirement.

Installation

1. Install Go Package

go get github.com/MaaXYZ/maa-framework-go/v4

2. Download MaaFramework

Download the MaaFramework Release for your platform and extract it.

Platform	Architecture	Download
Windows	amd64	MAA-win-x86_64-*.zip
Windows	arm64	MAA-win-aarch64-*.zip
Linux	amd64	MAA-linux-x86_64-*.zip
Linux	arm64	MAA-linux-aarch64-*.zip
macOS	amd64	MAA-macos-x86_64-*.zip
macOS	arm64	MAA-macos-aarch64-*.zip
Android	amd64	MAA-android-x86_64-*.zip
Android	arm64	MAA-android-aarch64-*.zip

3. Load Runtime Libraries

Programs built with maa-framework-go require MaaFramework dynamic libraries at runtime. Two common loading methods are shown below; see the runtime library loading guide for additional methods using environment variables or system library directories, and for the library file list.

1. Library Directory - Point WithLibDir at the directory containing the libraries:

   if err := maa.Init(maa.WithLibDir("path/to/MaaFramework/bin")); err != nil {
       return err
   }

2. Working Directory - Place the libraries and their dependencies in the program's working directory and select it explicitly:

   if err := maa.Init(maa.WithLibDir(".")); err != nil {
       return err
   }

Quick Start

The core steps are shown below. See the complete quick-start example for runtime initialization, device discovery, object creation, and cleanup. Set the agent binary directory in NewAdbController and run from examples/quick-start so ./resource resolves to the included bundle.

// Initialize MAA, find an ADB device, and create ctrl (see the full example).
connectJob, err := ctrl.PostConnect()
if err != nil {
	return fmt.Errorf("post connect: %w", err)
}
if !connectJob.Wait().Success() {
	return errors.New("ADB controller connection failed")
}

// Create res before loading the resource bundle.
bundleJob, err := res.PostBundle("./resource")
if err != nil {
	return fmt.Errorf("post resource bundle: %w", err)
}
if !bundleJob.Wait().Success() {
	return errors.New("resource bundle loading failed")
}

// Create tasker after the controller is connected and the resource is loaded.
if err := tasker.BindController(ctrl); err != nil {
	return fmt.Errorf("bind controller: %w", err)
}
if err := tasker.BindResource(res); err != nil {
	return fmt.Errorf("bind resource: %w", err)
}
if !tasker.Initialized() {
	return errors.New("tasker initialization check failed")
}

taskJob, err := tasker.PostTask("Startup")
if err != nil {
	return fmt.Errorf("post task: %w", err)
}
if !taskJob.Wait().Success() {
	return errors.New("Startup task failed")
}
detail, err := taskJob.GetDetail()
if err != nil {
	return fmt.Errorf("get task detail: %w", err)
}
fmt.Println(detail)

Examples

For more examples, see the examples directory:

• quick-start - Basic usage
• custom-action - Custom action
• custom-recognition - Custom recognition
• agent-client - Agent client
• agent-server - Agent server

Documentation

• Runtime library loading
• Android build guide
• Frequently asked questions
• Migration guides: v3 to v4, beta.18 to beta.19, beta.19 to v4.
• Changelog
• MaaFramework Quick Start
• Pipeline Protocol
• Integration Guide
• Go Package Documentation

Contributing

Bug reports, feature suggestions, and pull requests are welcome. See the contribution guide for development setup, checks, and pull request guidelines.

License

This project is licensed under the LGPL-3.0 License.

Community

• QQ Group: 595990173
• GitHub Discussions: MaaFramework Discussions