MaaFramework Golang Binding

English | 简体中文

This is the Go binding for MaaFramework, providing Go developers with a simple and effective way to use MaaFramework's features within their Go applications.

No Cgo required!

Installation

To install the MaaFramework Go binding, run the following command in your terminal:

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

In addition, please download the Release package for MaaFramework to get the necessary dynamic library files.

Usage

To use MaaFramework in your Go project, import the package as you would with any other Go package:

import "github.com/MaaXYZ/maa-framework-go"

Then, you can use the functionalities provided by MaaFramework. For detailed usage, refer to the documentation and examples provided in the repository.

Note: Programs built with maa-framework-go rely on the dynamic libraries of MaaFramework. Please ensure one of the following conditions is met:

1. The program's working directory contains the MaaFramework dynamic libraries.
2. Environment variables (such as LD_LIBRARY_PATH or PATH) are set to include the path to the dynamic libraries.

Otherwise, the program may not run correctly.

Documentation

Currently, there is not much detailed documentation available. Please refer to the source code and compare it with the interfaces in the original MaaFramework project to understand how to use the bindings. We are actively working on adding more comments and documentation to the source code.

Here are some documents from the maa framework that might help you:

• QuickStarted
• PipelineProtocol

Examples

• Quirk Start
• Custom Recognition
• Custom Action
• PI CLI

Quirk start

See quirk-start for details.

Here is a basic example to get you started:

package main

import (
    "fmt"
    "github.com/MaaXYZ/maa-framework-go"
    "os"
)

func main() {
    toolkit := maa.NewToolkit()
    toolkit.ConfigInitOption("./", "{}")
    tasker := maa.NewTasker(nil)
    defer tasker.Destroy()

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

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

    detail := tasker.PostPipeline("Startup").Wait().GetDetail()
    fmt.Println(detail)
}

Custom Recognition

See custom-recognition for details.

Here is a basic example to implement your custom recognition:

package main

import (
    "fmt"
    "github.com/MaaXYZ/maa-framework-go"
    "os"
)

func main() {
    toolkit := maa.NewToolkit()
    toolkit.ConfigInitOption("./", "{}")
    tasker := maa.NewTasker(nil)
    defer tasker.Destroy()

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

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

    res.RegisterCustomRecognition("MyRec", &MyRec{})

    detail := tasker.PostPipeline("Startup").Wait().GetDetail()
    fmt.Println(detail)
}

type MyRec struct{}

func (r *MyRec) Run(ctx *maa.Context, arg *maa.CustomRecognitionArg) (maa.CustomRecognitionResult, bool) {
    ctx.RunRecognition("MyCustomOCR", arg.Img, maa.J{
        "MyCustomOCR": maa.J{
            "roi": []int{100, 100, 200, 300},
        },
    })

    ctx.OverridePipeline(maa.J{
        "MyCustomOCR": maa.J{
            "roi": []int{1, 1, 114, 514},
        },
    })

    newContext := ctx.Clone()
    newContext.OverridePipeline(maa.J{
        "MyCustomOCR": maa.J{
            "roi": []int{100, 200, 300, 400},
        },
    })
    newContext.RunPipeline("MyCustomOCR", arg.Img)

    clickJob := ctx.GetTasker().GetController().PostClick(10, 20)
    clickJob.Wait()

    ctx.OverrideNext(arg.CurrentTaskName, []string{"TaskA", "TaskB"})

    return maa.CustomRecognitionResult{
        Box:    maa.Rect{0, 0, 100, 100},
        Detail: "Hello World!",
    }, true
}

Custom Action

See custom-action for details.

Here is a basic example to implement your custom action:

package main

import (
    "fmt"
    "github.com/MaaXYZ/maa-framework-go"
    "os"
)

func main() {
    toolkit := maa.NewToolkit()
    toolkit.ConfigInitOption("./", "{}")
    tasker := maa.NewTasker(nil)
    defer tasker.Destroy()

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

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

    res.RegisterCustomAction("MyAct", &MyAct{})

    detail := tasker.PostPipeline("Startup").Wait().GetDetail()
    fmt.Println(detail)
}

type MyAct struct{}

func (a *MyAct) Run(_ *maa.Context, _ *maa.CustomActionArg) bool {
    return true
}

PI CLI

See pi-cli for details.

Here is a basic example of using PI CLI:

package main

import (
    "github.com/MaaXYZ/maa-framework-go"
)

func main() {
    toolkit := maa.NewToolkit()
    toolkit.RegisterPICustomAction(0, "MyAct", &MyAct{})
    toolkit.RunCli(0, "./resource", "./", false, nil)
}

type MyAct struct{}

func (m MyAct) Run(ctx *maa.Context, arg *maa.CustomActionArg) bool {
    ctx.OverrideNext(arg.CurrentTaskName, []string{"TaskA", "TaskB"})

    img := ctx.GetTasker().GetController().CacheImage()
    ctx.GetTasker().GetController().PostClick(100, 100).Wait()

    ctx.RunRecognition("Cat", img, maa.J{
        "recognition": "OCR",
        "expected":    "cat",
    })
    return true
}

Contributing

We welcome contributions to the MaaFramework Go binding. If you find a bug or have a feature request, please open an issue on the GitHub repository. If you want to contribute code, feel free to fork the repository and submit a pull request.

License

This project is licensed under the LGPL-3.0 License. See the LICENSE file for details.

Discussion

QQ Group: 595990173