Integrated Interface Overview

About Binding

Different language bindings may have different naming conventions and are wrapped according to the Standardized Interface Design. Please search for the actual names yourself. Some interfaces may be used automatically internally and not provided directly (such as StringBuffer-related interfaces). Below are reference names for some interfaces across different bindings.

C API	Python Standard Interface	NodeJS Standard Interface
MaaVersion()	Library.version()	Global.version
MaaTaskerCreate()	Tasker()	new Tasker()
MaaTaskerDestroy(tasker_handle)	Called automatically on destruct	tasker.destroy()
MaaResourcePostBundle(res_handle, path)	resource.post_bundle(path)	res.post_bundle(path)
MaaControllerPostClick(ctrl_handle, x, y)	controller.post_click(x, y)	ctrl.post_click(x, y)
MaaTaskerInited(tasker_handle)	tasker.inited	tasker.inited
MaaTaskerPostTask(tasker_handle, entry, override)	tasker.post_task(entry, override)	tasker.post_task(entry, override)

MaaUtility.h

MaaVersion

Returns the version of MaaFramework.

MaaGlobalSetOption

Set global options. Will be split into specific options in bindings.

• LogDir

  Set the log path.

• SaveDraw

  Set whether to save recognition results to log path/vision. When enabled, RecoDetail can retrieve draws.

• StdoutLevel

  Set the log output level to stdout.

• DebugMode

  Set whether to enable debug mode. In debug mode, RecoDetail can retrieve raw/draws; all tasks are treated as focus and produce callbacks.

• SaveOnError

  Set whether to save screenshot on error to log path/on_error.

• DrawQuality

  Set the JPEG quality for recognition visualization images (0-100). Default value is 85.

• RecoImageCacheLimit

  Set the recognition image cache limit. Default value is 4096.

MaaGlobalLoadPlugin

• library_path: Plugin library path or name

Load plugin. Can use full path or name only. When using name only, will search in system directory and current directory. Can also recursively search for plugins in a directory.

MaaResource.h

MaaResourceCreate

Create resource.

MaaResourceDestroy

Destroy resource.

MaaResourceAddSink

• res: Resource
• sink: Event callback
• trans_arg: Argument passed to callback

Add resource event listener, returns listener id

MaaResourceRemoveSink

• res: Resource
• sink_id: Listener id

Remove resource event listener

MaaResourceClearSinks

• res: Resource

Clear all resource event listeners

MaaResourceRegisterCustomRecognition

• name: Name
• recognition: Custom recognizer
• trans_arg: Argument passed to callback

Register a custom recognizer named name.

MaaResourceUnregisterCustomRecognition

• name: Name

Remove the custom recognizer named name.

MaaResourceClearCustomRecognition

Remove all custom recognizers.

MaaResourceRegisterCustomAction

• name: Name
• action: Custom action
• trans_arg: Argument passed to callback

Register a custom action named name.

MaaResourceUnregisterCustomAction

• name: Name

Remove the custom action named name.

MaaResourceClearCustomAction

Remove all custom actions.

MaaResourcePostBundle

• path: Resource path

Asynchronously load resources from the path path. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaResourceStatus and MaaResourceWait.

MaaResourceOverridePipeline

• pipeline_override: JSON for overriding

Override pipeline_override.

MaaResourceOverrideNext

• node_name: Task name
• next_list: Next list

Override the next list of node_name with next_list. Note: This method directly sets the next list, creating the node if it doesn't exist.

MaaResourceOverrideImage

• image_name: Image name
• image: Image data

Override the image corresponding to image_name with image. This method always succeeds.

MaaResourceGetNodeData

• node_name: Task name
• buffer [out]: Output buffer

Get the current definition of task node_name, write to buffer.

MaaResourceClear

Clear loaded content. This method will fail and return false if resources are currently loading.

MaaResourceStatus

• id: Operation id

Query the status of operation with id.

MaaResourceWait

• id: Operation id

Wait for the operation with id to complete.

MaaResourceLoaded

Check if resources loaded normally.

MaaResourceSetOption

Set resource options. Will be split into specific options in bindings.

• InferenceDevice

  Set inference device.

• InferenceExecutionProvider

  Set inference provider.

MaaResourceGetHash

• buffer [out]: Output buffer

Get resource hash, write to buffer.

MaaResourceGetNodeList

• buffer [out]: Output buffer

Get task list, write to buffer.

MaaResourceGetCustomRecognitionList

• buffer [out]: Output buffer

Get registered custom recognizer name list, write to buffer.

MaaResourceGetCustomActionList

• buffer [out]: Output buffer

Get registered custom action name list, write to buffer.

MaaController.h

MaaAdbControllerCreate

• adb_path: adb path
• address: connection address
• screencap_methods: all available screenshot methods, see Control Methods
• input_methods: all available input methods, see Control Methods
• config: extra config
• agent_path: MaaAgentBinary path

Create Adb controller

Screenshot and input methods will be speed tested at startup, selecting the fastest option.

MaaWin32ControllerCreate

• hWnd: window handle
• screencap_method: screenshot method used, see Control Methods
• mouse_method: mouse input method used, see Control Methods
• keyboard_method: keyboard input method used, see Control Methods

Create Win32 controller

MaaCustomControllerCreate

• controller: Custom control callback structure
• controller_arg: Argument passed to callbacks

Create custom controller

MaaDbgControllerCreate

• read_path: Input path, includes operations recorded via Recording option
• write_path: Output path, includes execution results
• type: Controller mode
• config: Extra config

Create debug controller

MaaControllerDestroy

Destroy controller

MaaControllerAddSink

• ctrl: Controller
• sink: Event callback
• trans_arg: Argument passed to callback

Add controller event listener, returns listener id

MaaControllerRemoveSink

• ctrl: Controller
• sink_id: Listener id

Remove controller event listener

MaaControllerClearSinks

• ctrl: Controller

Clear all controller event listeners

MaaControllerSetOption

Set controller options. Will be split into specific options in bindings.

• ScreenshotTargetLongSide

  Set screenshot scaling long side to specified length

• ScreenshotTargetShortSide

  Set screenshot scaling short side to specified length

• ScreenshotUseRawSize

  No scaling for screenshots

MaaControllerPostConnection

Asynchronously connect device. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostClick

• x, y: Click coordinates

Asynchronously click. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostSwipe

• x1, y1: Start coordinates
• x2, y2: End coordinates
• duration: Swipe duration in ms

Asynchronously swipe. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostClickKey

• key: Virtual key code
  • Adb Controller
  • Win32 Controller

Asynchronously click key. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostKeyDown

• key: Virtual key code
  • Adb Controller
  • Win32 Controller

Asynchronously key down. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostKeyUp

• key: Virtual key code
  • Adb Controller
  • Win32 Controller

Asynchronously key up. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostInputText

• text: Text to input

Asynchronously input text. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostStartApp

• intent: Target app
  • Adb Controller: package name or activity
  • Win32 Controller: not supported yet

Asynchronously start app. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostStopApp

• intent: Target app
  • Adb Controller: package name
  • Win32 Controller: not supported yet

Asynchronously stop app. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostTouchDown

• contact: Contact number
  • Adb Controller: finger number
  • Win32 Controller: mouse button (0: left, 1: right, 2: middle)
• x, y: Contact position
• pressure: Contact pressure

Asynchronously touch down. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostTouchMove

• contact: Contact number
  • Adb Controller: finger number
  • Win32 Controller: mouse button (0: left, 1: right, 2: middle)
• x, y: Contact position
• pressure: Contact pressure

Asynchronously move. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostTouchUp

• contact: Contact number
  • Adb Controller: finger number
  • Win32 Controller: mouse button (0: left, 1: right, 2: middle)

Asynchronously touch up. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

MaaControllerPostScroll

• dx: Horizontal scroll distance, positive values scroll right, negative values scroll left
• dy: Vertical scroll distance, positive values scroll down, negative values scroll up

Asynchronously scroll. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

NOTE

• Only Win32 Controller supports scroll operations. Adb Controller does not support scrolling.
• The dx/dy values are sent directly as scroll increments. The Windows standard wheel increment is 120 (WHEEL_DELTA) per notch. Using multiples of 120 is recommended for best compatibility.

MaaControllerPostScreencap

Asynchronously screenshot. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait, and get the screenshot via MaaControllerCachedImage.

MaaControllerPostShell

• cmd: Shell command to execute

Asynchronously execute a shell command on an ADB device. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait, and get the output via MaaControllerGetShellOutput.

Note: This is only valid for ADB controllers. Other controller types will fail with an error.

MaaControllerStatus

• id: Operation id

Query status of operation with id.

MaaControllerWait

• id: Operation id

Wait for operation with id to complete.

MaaControllerConnected

Check if connected.

MaaControllerCachedImage

• buffer [out]: Output buffer

Get the latest screenshot, write to buffer.

MaaControllerGetShellOutput

• buffer [out]: Output buffer

Get the output from the most recent shell command execution, write to buffer.

MaaControllerGetUuid

• buffer [out]: Output buffer

Get device uuid, write to buffer.

MaaTasker.h

MaaTaskerCreate

Create instance

MaaTaskerDestroy

Destroy instance

MaaTaskerAddSink

• tasker: Instance
• sink: Event callback
• trans_arg: Argument passed to callback

Add instance event listener, returns listener id

MaaTaskerRemoveSink

• tasker: Instance
• sink_id: Listener id

Remove instance event listener

MaaTaskerClearSinks

• tasker: Instance

Clear all instance event listeners

MaaTaskerAddContextSink

• tasker: Instance
• sink: Event callback
• trans_arg: Argument passed to callback

Add context event listener, returns listener id

MaaTaskerRemoveContextSink

• tasker: Instance
• sink_id: Listener id

Remove context event listener

MaaTaskerClearContextSinks

• tasker: Instance

Clear all context event listeners

MaaTaskerSetOption

Set instance options. Will be split into specific options in bindings.

No configurable options currently.

MaaTaskerBindResource

• res: Resource

Bind resource

MaaTaskerBindController

• ctrl: Controller

Bind controller

MaaTaskerInited

Check if initialized correctly

MaaTaskerPostTask

• entry: Task entry
• pipeline_override: JSON for overriding

Asynchronously execute task. This is an asynchronous operation that immediately returns a task id. You can query the status via MaaTaskerStatus and MaaTaskerWait, and get task details via MaaTaskerGetTaskDetail.

MaaTaskerPostRecognition

• reco_type: Recognition type string
• reco_param: Recognition parameters JSON
• image: Previous screenshot

Asynchronously execute recognition. This is an asynchronous operation that immediately returns a task id. You can query the status via MaaTaskerStatus and MaaTaskerWait, and get task details via MaaTaskerGetTaskDetail.

MaaTaskerPostAction

• action_type: Action type string
• action_param: Action parameters JSON
• box: Previous recognition position
• reco_detail: Previous recognition details

Asynchronously execute action. This is an asynchronous operation that immediately returns a task id. You can query the status via MaaTaskerStatus and MaaTaskerWait, and get task details via MaaTaskerGetTaskDetail.

MaaTaskerStatus

• id: Operation id

Query status of operation with id.

MaaTaskerWait

• id: Operation id

Wait for operation with id to complete.

MaaTaskerRunning

Check if instance is still running

MaaTaskerPostStop

Asynchronously stop instance. This is an asynchronous operation that immediately returns a task id. The stop operation will interrupt the currently running task and stop resource loading and controller operations. You can query the status via MaaTaskerStatus and MaaTaskerWait.

MaaTaskerStopping

Check if instance is stopping (not yet stopped)

MaaTaskerGetResource

Get bound resource

MaaTaskerGetController

Get bound controller

MaaTaskerClearCache

Clear all queryable information

MaaTaskerGetRecognitionDetail

• reco_id: Recognition id
• node_name [out]: Node name buffer
• algorithm [out]: Recognition algorithm buffer
• hit [out]: Hit or not
• box [out]: Hit position
• detail_json [out]: Recognition details buffer
• raw [out]: Screenshot buffer (valid only in debug mode)
• draws [out]: Screenshot with recognition results buffer (valid only in debug mode)

Get recognition info

MaaTaskerGetActionDetail

• action_id: Action id
• node_name [out]: Node name
• action [out]: Action type name (e.g., "Click", "Swipe", etc.)
• box [out]: Action region (recognition box)
• success [out]: Action return value (return value from controller call)
• detail_json [out]: Actual parameter passed to controller (JSON format)

Get action information

MaaTaskerGetNodeDetail

• node_id: Node id
• node_name [out]: Node name buffer
• reco_id [out]: Corresponding recognition id
• action_id [out]: Corresponding action id
• completed [out]: Operation result

Get node info

MaaTaskerGetTaskDetail

• task_id: Task id
• entry [out]: Task entry buffer
• node_id_list [out]: Node id array
• node_id_list_size [in, out]: Node id array size (input: buffer size, output: actual size)
• status [out]: Task status

Get task info

MaaTaskerGetLatestNode

• node_name: Task name
• latest_id [out]: Latest node id

Get latest node id for task node_name

MaaContext.h

MaaContextRunTask

• entry: Task entry
• pipeline_override: JSON for overriding

Synchronously execute task. Returns MaaInvalidId on failure, or task id on success. You can get task details via MaaTaskerGetTaskDetail.

MaaContextRunRecognition

• entry: Task name
• pipeline_override: JSON for overriding
• image: Previous screenshot

Synchronously execute recognition logic for entry, returns recognition id. Returns MaaInvalidId on failure, or recognition id on success. You can get recognition details via MaaTaskerGetRecognitionDetail.

Will not execute subsequent operations or next steps.

MaaContextRunAction

• entry: Task name
• pipeline_override: JSON for overriding
• box: Previous recognition position
• reco_detail: Previous recognition details

Synchronously execute action logic for entry, returns action id. Returns MaaInvalidId on failure, or action id on success. You can get action details via MaaTaskerGetActionDetail.

Will not execute subsequent next steps.

MaaContextOverridePipeline

• pipeline_override: JSON for overriding

Override pipeline_override

MaaContextOverrideNext

• node_name: Task name
• next_list: Next list

Override next list of node_name with next_list. This method will fail and return false if the node does not exist.

MaaContextOverrideImage

• image_name: Image name
• image: Image data

Override the image corresponding to image_name with image. This method always succeeds.

MaaContextGetNodeData

• node_name: Task name
• buffer [out]: Output buffer

Get current definition of task node_name, write to buffer.

MaaContextGetTaskId

Get corresponding task id

MaaContextGetTasker

Get instance

MaaContextClone

Clone context

MaaContextSetAnchor

• anchor_name: Anchor name
• node_name: Node name

Set the node corresponding to anchor anchor_name to node_name

MaaContextGetAnchor

• anchor_name: Anchor name
• buffer [out]: Output buffer

Get the node name corresponding to anchor anchor_name, write to buffer

MaaContextGetHitCount

• node_name: Node name
• count [out]: Hit count

Get hit count for node node_name, write to count

MaaContextClearHitCount

• node_name: Node name

Clear hit count for node node_name

MaaToolkitConfig.h

MaaToolkitConfigInitOption

• user_path: Config storage path
• default_json: Default config

Load global config from user_path

MaaToolkitAdbDevice.h

MaaToolkitAdbDeviceListCreate

Create device list

MaaToolkitAdbDeviceListDestroy

• handle: Device list handle

Destroy device list

MaaToolkitAdbDeviceFind

• buffer [out]: Output buffer

Search all known Android emulators, write to buffer

MaaToolkitAdbDeviceFindSpecified

• adb_path: adb path
• buffer [out]: Output buffer

Search emulators using specified adb_path, write to buffer

MaaToolkitAdbDeviceListSize

• list: Device list

Get device list size

MaaToolkitAdbDeviceListAt

• list: Device list
• index: Index

Get device at specified index in device list

MaaToolkitAdbDeviceGetName

• device: Device

Get device name

MaaToolkitAdbDeviceGetAdbPath

• device: Device

Get device adb path

MaaToolkitAdbDeviceGetAddress

• device: Device

Get device connection address

MaaToolkitAdbDeviceGetScreencapMethods

• device: Device

Get device supported screenshot methods

MaaToolkitAdbDeviceGetInputMethods

• device: Device

Get device supported input methods

MaaToolkitAdbDeviceGetConfig

• device: Device

Get device config

MaaToolkitDesktopWindow.h

MaaToolkitDesktopWindowListCreate

Create window list

MaaToolkitDesktopWindowListDestroy

• handle: Window list handle

Destroy window list

MaaToolkitDesktopWindowFindAll

• buffer [out]: Output buffer

Query all window info, write to buffer

MaaToolkitDesktopWindowListSize

• list: Window list

Get window list size

MaaToolkitDesktopWindowListAt

• list: Window list
• index: Index

Get window at specified index in window list

MaaToolkitDesktopWindowGetHandle

• window: Window

Get window handle

MaaToolkitDesktopWindowGetClassName

• window: Window

Get window class name

MaaToolkitDesktopWindowGetWindowName

• window: Window

Get window name

MaaAgentClientAPI.h

MaaAgentClientCreateV2

• identifier: Listening address buffer (can be empty, auto-generate if empty)

Create Agent client

If empty, auto-generate

MaaAgentClientDestroy

Destroy Agent client

MaaAgentClientIdentifier

• identifier [out]: Output buffer

Get actual listening address, write to identifier

MaaAgentClientBindResource

• res: Resource

Bind Agent client to resource res

MaaAgentClientRegisterResourceSink

• res: Resource

Register resource event listener

MaaAgentClientRegisterControllerSink

• ctrl: Controller

Register controller event listener

MaaAgentClientRegisterTaskerSink

• tasker: Instance

Register instance event listener

MaaAgentClientConnect

Connect

MaaAgentClientDisconnect

Disconnect

MaaAgentClientConnected

Check if connected

MaaAgentClientAlive

Check if Agent server is still responsive

MaaAgentClientSetTimeout

• milliseconds: Timeout in ms

Set Agent server timeout

MaaAgentClientGetCustomRecognitionList

• buffer [out]: Output buffer

Get custom recognizer name list registered after Agent connection, write to buffer.

MaaAgentClientGetCustomActionList

• buffer [out]: Output buffer

Get custom action name list registered after Agent connection, write to buffer.

MaaAgentServerAPI.h

MaaAgentServerRegisterCustomRecognition

• name: Name
• recognition: Custom recognizer
• trans_arg: Argument passed to callback

Register a custom recognizer named name

MaaAgentServerRegisterCustomAction

• name: Name
• action: Custom action
• trans_arg: Argument passed to callback

Register a custom action named name

MaaAgentServerAddResourceSink

• sink: Event callback
• trans_arg: Argument passed to callback

Add resource event listener, returns listener id

MaaAgentServerAddControllerSink

• sink: Event callback
• trans_arg: Argument passed to callback

Add controller event listener, returns listener id

MaaAgentServerAddTaskerSink

• sink: Event callback
• trans_arg: Argument passed to callback

Add instance event listener, returns listener id

MaaAgentServerAddContextSink

• sink: Event callback
• trans_arg: Argument passed to callback

Add context event listener, returns listener id

MaaAgentServerStartUp

• identifier: Connection address

Start server and connect to identifier

MaaAgentServerShutDown

Stop server

MaaAgentServerJoin

Synchronously wait for server thread to end

MaaAgentServerDetach

Detach server thread