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
• 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/v3

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/v3"
)

func main() {
    // Initialize MaaFramework
    maa.Init()
    maa.ConfigInitOption("./", "{}")

    // Create tasker
    tasker := maa.NewTasker()
    defer tasker.Destroy()

    // Find and connect to ADB device
    devices := maa.FindAdbDevices()
    if len(devices) == 0 {
        fmt.Println("No ADB device found")
        os.Exit(1)
    }
    device := devices[0]

    ctrl := maa.NewAdbController(
        device.AdbPath,
        device.Address,
        device.ScreencapMethod,
        device.InputMethod,
        device.Config,
        "path/to/MaaAgentBinary",
    )
    defer ctrl.Destroy()
    ctrl.PostConnect().Wait()
    tasker.BindController(ctrl)

    // Load resource
    res := maa.NewResource()
    defer res.Destroy()
    res.PostBundle("./resource").Wait()
    tasker.BindResource(res)

    if !tasker.Initialized() {
        fmt.Println("Failed to initialize MAA")
        os.Exit(1)
    }

    // Run task
    detail := tasker.PostTask("Startup").Wait().GetDetail()
    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