English | 简体中文

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

🚀 No Cgo Required! Pure Go implementation using purego.

• Cross-platform Controllers - ADB, Win32, WlRoots, macOS, PlayCover, and Android native control backends
• Recording and Replay - Capture controller operations to JSONL and replay them for debugging and regression testing
• Virtual Gamepad Controller - Gamepad automation via ViGEm (Windows only)
• Toolkit Utilities - Discover ADB devices and desktop windows, and manage macOS automation permissions
• Image Recognition - Template matching, OCR, feature detection, and more
• Custom Extensions - Implement custom recognitions, actions, and controllers in pure Go
• Agent Support - Mount custom recognition and action logic from external processes
• Async Jobs and Events - Poll job status, inspect task details, and subscribe to resource, controller, and tasker events
• Pipeline and Runtime APIs - Declarative JSON task flows with runtime task, recognition, and action orchestration

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

Download the MaaFramework Release for your platform and extract it.

Programs built with maa-framework-go require MaaFramework dynamic libraries at runtime. You have several options:

1. Via Init() Option - Specify library path programmatically:

   maa.Init(maa.WithLibDir("path/to/MaaFramework/bin"))

2. Working Directory - Place MaaFramework libraries in your program's working directory

3. Environment Variables - Add library path to PATH (Windows) or LD_LIBRARY_PATH (Linux/macOS)

4. System Library Path - Install libraries to system library directories

package main

import (
	"fmt"
	"os"

	"github.com/MaaXYZ/maa-framework-go/v4"
)

func main() {
	maa.Init()
	if err := maa.ConfigInitOption("./", "{}"); err != nil {
		fmt.Println("Failed to init config:", err)
		os.Exit(1)
	}
	tasker, err := maa.NewTasker()
	if err != nil {
		fmt.Println("Failed to create tasker")
		os.Exit(1)
	}
	defer tasker.Destroy()

	devices, err := maa.FindAdbDevices()
	if err != nil {
		fmt.Println("Failed to find adb devices:", err)
		os.Exit(1)
	}
	device := devices[0]
	ctrl, err := maa.NewAdbController(
		device.AdbPath,
		device.Address,
		device.ScreencapMethod,
		device.InputMethod,
		device.Config,
		"path/to/MaaAgentBinary",
	)
	if err != nil {
		fmt.Println("Failed to create ADB controller")
		os.Exit(1)
	}
	defer ctrl.Destroy()
	ctrl.PostConnect().Wait()
	tasker.BindController(ctrl)

	res, err := maa.NewResource()
	if err != nil {
		fmt.Println("Failed to create resource")
		os.Exit(1)
	}
	defer res.Destroy()
	res.PostBundle("./resource").Wait()
	tasker.BindResource(res)
	if !tasker.Initialized() {
		fmt.Println("Failed to init MAA.")
		os.Exit(1)
	}

	detail, err := tasker.PostTask("Startup").Wait().GetDetail()
	if err != nil {
		fmt.Println("Failed to get task detail:", err)
		os.Exit(1)
	}
	fmt.Println(detail)
}

For more examples, see the examples directory:

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

• MaaFramework Quick Start
• Pipeline Protocol
• Integration Guide
• Go Package Documentation

Contributions are welcome! Feel free to:

• Report bugs by opening issues
• Suggest features or improvements
• Submit pull requests

This project is licensed under the LGPL-3.0 License.

• QQ Group: 595990173
• GitHub Discussions: MaaFramework Discussions