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.

✨ Features

• ADB Controller - Android device automation via ADB
• Win32 Controller - Windows desktop application automation
• PlayCover Controller - Control iOS apps via PlayCover on macOS
• Virtual Gamepad Controller - Gamepad automation via ViGEm (Windows only)
• Image Recognition - Template matching, OCR, feature detection and more
• Custom Recognition - Implement custom image recognition algorithms
• Custom Actions - Define your own automation logic
• Agent Support - Mount custom recognition and actions from external processes
• Pipeline-based - Declarative task flow with JSON configuration

📦 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

⚙️ Runtime Requirements

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

🚀 Quick Start

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

📖 Examples

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

📚 Documentation

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

🤝 Contributing

Contributions are welcome! Feel free to:

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

📄 License

This project is licensed under the LGPL-3.0 License.

💬 Community

• QQ Group: 595990173
• GitHub Discussions: MaaFramework Discussions