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.

Installation

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

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

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 examples and documentation provided in the repository.

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:

Platform-Specific Notes

Windows

On Windows, the default location for MaaFramework is C:\maa. Ensure that MaaFramework is installed in this directory for the binding to work out of the box.

If you need to specify a custom installation path, refer to the Custom Environment section.

Linux and macOS

On Linux and macOS, you will need to create a pkg-config file named maa.pc. This file should correctly point to the locations of the MaaFramework headers and libraries. Place this file in a directory where pkg-config can find it (e.g., /usr/lib/pkgconfig).

A sample maa.pc file might look like this:

prefix=/path/to/maafw
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: MaaFramework
Description: MaaFramework library
Version: 1.0
Libs: -L${libdir} -lMaaFramework -lMaaToolkit
Cflags: -I${includedir}

If you need to specify a custom environment, refer to the Custom Environment section.

Custom Environment

If you need to specify a custom installation path for MaaFramework, you can disable the default location using the -tags customenv build tag. Then, set the necessary environment variables CGO_CFLAGS and CGO_LDFLAGS.

go build -tags customenv

Set the environment variables as follows:

export CGO_CFLAGS="-I[path to maafw include directory]"
export CGO_LDFLAGS="-L[path to maafw lib directory] -lMaaFramework -lMaaToolkit"

Replace [path to maafw include directory] with the actual path to the MaaFramework include directory and [path to maafw lib directory] with the actual path to the MaaFramework library directory.

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