2.2 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)
MaaImageBufferResize(image_handle, width, height)	ImageBuffer.resize(width, height)	Global.resize_image(image, width, height)

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.

MaaBuffer.h

MaaImageBufferResize

handle: Image buffer
width: Target width, pass 0 to scale by height
height: Target height, pass 0 to scale by width

Resize the image data in handle with aspect ratio preserved. width and height cannot both be 0.

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. The name must not be empty. Custom recognizers and custom actions share one case-sensitive namespace. If the name is empty or either type already uses it, the function returns false and preserves any existing registration. Unregister the existing custom before replacing it.

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. The name must not be empty. Custom recognizers and custom actions share one case-sensitive namespace. If the name is empty or either type already uses it, the function returns false and preserves any existing registration. Unregister the existing custom before replacing it.

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 the inference execution provider:
- Auto: try CUDA, then DirectML, then WebGPU, then CoreML, and fall back to CPU
- CPU
- DirectML: Windows. InferenceDevice is the Win32 EnumAdapters1 adapter id
- WebGPU: Windows, Linux and macOS. InferenceDevice is the WebGPU device id; Auto uses device 0
- CUDA: InferenceDevice is the NVIDIA GPU id. The current prebuilt packages do not include CUDA
- CoreML: deprecated. MaaDeps no longer ships CoreML; use WebGPU. The value is kept so existing callers still compile
- NCNN: Android only (setting it fails on other platforms), CPU only (InferenceDevice must be CPU or Auto, other values fail the loading), never picked by Auto. Models are loaded from <stem>.ncnn.param/.ncnn.bin/.ncnn.json next to the model path (the .onnx file is not needed). There is no fallback to onnxruntime: a missing or broken ncnn model fails the recognition, so ship ncnn models together with this provider. OCR also runs on NCNN, loading det.ncnn.param/.bin, rec.ncnn.param/.bin and keys.txt from the OCR model dir, with no fallback either. <stem>.ncnn.json carries what the ncnn files do not:
  - input_shape (required): fixed NCHW input shape, batch must be 1, e.g. [1, 3, 640, 640]
  - input / output (optional): input / output blob names, default to the first input / output of the .ncnn.param
  - metadata (optional): string-valued map, equivalent to the onnx custom metadata, e.g. "names": "{0: 'cat', 1: 'dog'}" for detector labels
  - options (optional): fp16 options of the model, see below
  OCR may ship optional det.ncnn.json / rec.ncnn.json next to the models. Only their options is read, the input size and pre / post processing follow fastdeploy PP-OCR.

Both options should be set before loading resources. A change made after loading starts (any MaaResourcePost*) is applied on the next MaaResourcePost*, and only to models that are not loaded yet; call MaaResourceClear and load again to switch every model. Switching to or from NCNN changes the inference engine and the model files, so it fails once loading starts until MaaResourceClear is called or the resource is recreated.

NCNN options: only the precision of a model is configurable, using the fp16 fields of ncnn::Option:

Key	Type	Default	Description
`use_fp16_packed`	bool	`false`	fp16 packed layout
`use_fp16_storage`	bool	`false`	Store weights and intermediate blobs in fp16
`use_fp16_arithmetic`	bool	`false`	Compute in fp16

MaaFW runs ncnn in fp32 by default so that the scores match onnxruntime. fp16 is faster on ARMv8.2+ CPUs at the cost of precision, enable it per model (usually all three together) after checking its results. Device related options are handled by MaaFW and are not configurable: the thread count is the number of big + middle cores (at most 4), the others keep the ncnn defaults. Unknown keys are ignored with a warning, a non-boolean value fails the model. For example:

json

{
    "input_shape": [1, 3, 640, 640],
    "options": { "use_fp16_packed": true, "use_fp16_storage": true, "use_fp16_arithmetic": true }
}

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.

MaaResourceGetDefaultRecognitionParam

reco_type: Recognition type string (e.g., "OCR", "TemplateMatch")
buffer [out]: Output buffer

Get default parameters for the specified recognition type from DefaultPipelineMgr, serialize as JSON and write to buffer.

MaaResourceGetDefaultActionParam

action_type: Action type string (e.g., "Click", "Swipe")
buffer [out]: Output buffer

Get default parameters for the specified action type from DefaultPipelineMgr, serialize as JSON and 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

MaaAndroidNativeControllerCreate

config_json: Android native controller config JSON, required fields:
- library_path: Android native control unit library path
- screen_resolution.width: raw screenshot width, also used as the touch coordinate width
- screen_resolution.height: raw screenshot height, also used as the touch coordinate height
- optional fields: display_id (defaults to 0), force_stop (defaults to false)

Create an Android native controller backed by MaaAndroidNativeControlUnit for native screenshot and input on Android.

screen_resolution must match both the control unit's raw screenshot resolution and touch coordinate space, otherwise screencap fails immediately.
Multi-touch is supported: contact is the finger id (0 for the first finger, valid range 0–15). The external library's TouchArgs must carry contact.

MaaCustomControllerCreate

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

Create custom controller

MaaDbgControllerCreate

read_path: Path to a directory of images (or a single image file). Images are loaded on connect and cycled on each screencap. All input operations are no-ops that return success.

Create debug controller

MaaReplayControllerCreate

recording_path: Path to the recording JSONL file written by MaaRecordControllerCreate. Screenshot paths are resolved relative to this file's parent directory.

Create replay controller

MaaRecordControllerCreate

inner: Inner controller to forward all operations to. The record controller does not take ownership of inner.
recording_path: Path to the recording JSONL file to write. Screenshots are saved to a {stem}-Screenshot folder in the same directory. Replay with MaaReplayControllerCreate using the recorded file.

Create record controller that wraps an existing controller and records all operations

MaaPlayCoverControllerCreate

address: PlayTools service listening address, format: host:port, e.g., 127.0.0.1:1717
uuid: Target application's Bundle Identifier, e.g., com.hypergryph.arknights

Create PlayCover controller for controlling iOS applications running via fork PlayCover on macOS. See Control Methods.

MaaLinuxControllerCreate

config_json: Linux controller config JSON.
- Required fields:
  - screencap_method: screencap method to use, see Control Methods.
  - input_method: input method to use, see Control Methods.
- Wlroots Required fields:
  - wlr_socket_path: wayland socket path (e.g., "/run/user/1000/wayland-0").
- PipeWire monitor capture (via xdg-desktop-portal) Required fields:
  - pw_socket_fd: The PipeWire socket FD (from the ScreenCast portal).
  - pw_node_id: The PipeWire Node ID.
- PipeWire session-daemon node capture (gamescope etc.) Required fields:
  - pw_node_id: attach to a session-daemon node directly; discover the node with MaaToolkitGamescopeInstanceFindAll.
- UInput Optional fields:
  - uinput_path: The uinput device node path, default is "/dev/uinput".
  - uinput_screen_width: The screen width in pixels for the uinput absolute axis range.
  - uinput_screen_height: The screen height in pixels for the uinput absolute axis range.
- Libei (EIS) Required fields:
  - eis_socket_path: The EIS socket path (e.g., "/run/user/1000/gamescope-0-ei").
- Optional fields:
  - use_win32_vk_code: Whether to use Win32 Virtual-Key codes (VK_*). If true, keys use Win32 VK codes. The default value is false, which uses Linux evdev scan codes.

Create Linux controller for controlling applications on Linux. See Control Methods.

MaaGamepadControllerCreate

hWnd: Window handle for screencap. Pass nullptr/None/null if screencap is not needed
gamepad_type: Gamepad type, see Control Methods
screencap_method: Win32 screencap method, see Control Methods

Create Gamepad controller for emulating Xbox 360 or DualShock 4 gamepad input on Windows. See Control Methods.

notice

ViGEm Bus Driver must be installed

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
ScreenshotTargetExpand
Scale screenshots to a reference resolution (width, height) using Unity Canvas Scaler Expand semantics: scale = max(width / raw_width, height / raw_height). The scale is applied uniformly to both axes so the source aspect ratio is preserved and both output dimensions are >= the reference. No cropping, no non-uniform stretching. Mutually exclusive with ScreenshotTargetLongSide / ScreenshotTargetShortSide; setting any of them resets the others. Value is an int32_t array of length 2: { width, height }.
ScreenshotUseRawSize
No scaling for screenshots
ScreenshotResizeMethod
Set screenshot resize interpolation method (0=INTER_NEAREST, 1=INTER_LINEAR, 2=INTER_CUBIC, 3=INTER_AREA, 4=INTER_LANCZOS4), default is INTER_AREA(3)
BackgroundManagedKeys
Declare Win32 background managed key domain. After setting, matching MaaControllerPostClickKey, MaaControllerPostKeyDown, MaaControllerPostKeyUp and pipeline ClickKey, LongPressKey, KeyDown, KeyUp operations automatically route through the background guardian path. Only supported by Win32 controllers; other controllers will fail.

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.

MaaControllerPostClickV2

x, y: Click coordinates
contact: Contact number
- Adb Controller: finger number (0 for first finger, 1 for second finger, etc.)
- Android Native Controller: finger id (0 for first finger, valid range 0–15)
- Win32 Controller: mouse button (0: left, 1: right, 2: middle)
- MacOS Controller: mouse button (0: left, 1: right, 2: middle)
pressure: Contact pressure

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.

MaaControllerPostSwipeV2

x1, y1: Start coordinates
x2, y2: End coordinates
duration: Swipe duration in ms
contact: Contact number
- Adb Controller: finger number (0 for first finger, 1 for second finger, etc.)
- Android Native Controller: finger id (0 for first finger, valid range 0–15)
- Win32 Controller: mouse button (0: left, 1: right, 2: middle)
- MacOS Controller: mouse button (0: left, 1: right, 2: middle)
pressure: Contact pressure

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

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

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

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: path or command of the executable

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: process name (optional), default to the associated window process

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
- Android Native Controller: finger id (0–15)
- Win32 Controller: mouse button (0: left, 1: right, 2: middle)
- MacOS 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
- Android Native Controller: finger id (0–15)
- Win32 Controller: mouse button (0: left, 1: right, 2: middle)
- MacOS 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
- Android Native Controller: finger id (0–15)
- Win32 Controller: mouse button (0: left, 1: right, 2: middle)
- MacOS 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.

MaaControllerPostRelativeMove

dx: Horizontal move distance
dy: Vertical move distance

Asynchronously execute a relative movement. Currently supported by Win32 controller. Operations posted to unsupported controllers will fail. 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 up, negative values scroll down

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

NOTE

Win32, macOS, and custom controllers that implement scroll support scroll operations.
Posting scroll to a controller that does not implement scroll will cause the action to fail.
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.

MaaControllerPostInactive

Asynchronously set the controller to inactive state. For Win32 controllers, this restores the window's topmost status, unblocks input, restores cursor/window positions, and reverts other invasive operations. Other controllers perform no operation. This is an asynchronous operation that immediately returns an operation id. You can query the status via MaaControllerStatus and MaaControllerWait.

NOTE

The Tasker automatically calls this after all tasks finish, so manual invocation is usually unnecessary.

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.

NOTE

The screenshot is scaled according to the screenshot target size settings (long side / short side). The resulting image dimensions may differ from the raw device resolution.
Use MaaControllerGetResolution to get the raw (unscaled) device resolution.

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.

NOTE

The returned image is scaled according to the screenshot target size settings (long side / short side). The image dimensions may differ from the raw device resolution.
Use MaaControllerGetResolution to get the raw (unscaled) device resolution.

MaaControllerGetResolution

width [out]: Output raw width
height [out]: Output raw height

Get the raw (unscaled) device resolution.

NOTE

This returns the actual device screen resolution before any scaling.
The screenshot obtained via MaaControllerCachedImage is scaled according to the screenshot target size settings, so its dimensions may differ from this raw resolution.
Valid values are only available after the first screenshot is taken.

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.

MaaControllerGetInfo

buffer [out]: Output buffer

Get controller information (JSON string), write to buffer.
The returned JSON always contains a type field indicating the controller type. Depending on the type, it also includes the respective constructor parameters.
Connection status, UUID, and resolution can be obtained via dedicated interfaces (MaaControllerConnected, MaaControllerGetUuid, MaaControllerGetResolution) and are not duplicated here.

Fields returned by each type:

adb: type, adb_path, adb_serial, screencap_methods, input_methods, agent_path, config
win32: type, hwnd, screencap_method, mouse_method, keyboard_method
playcover: type, address
gamepad: type, hwnd, gamepad_type, screencap_method
linux: type, screencap_method, input_method, wlr_socket_path, pw_socket_fd, pw_node_id, uinput_screen_width, uinput_screen_height, uinput_path, eis_socket_path, use_win32_vk_code
custom: type (if the custom controller implements the get_info callback, additional fields from it will also be included)
dbg: type, path, image_count, image_index
replay: type, record_count, record_index

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

MaaTaskerOverridePipeline

task_id: Task ID
pipeline_override: JSON for overriding

Override the pipeline of a specified task, dynamically modify pipeline configuration during task execution.

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

MaaTaskerGetWaitFreezesDetail

wf_id: Wait Freezes ID
node_name [out]: Node name buffer
phase [out]: Phase string buffer ("pre" / "post" / "repeat" / "context")
success [out]: Whether succeeded
elapsed_ms [out]: Total elapsed time in milliseconds
reco_id_list [out]: Recognition ID array for each frame-to-frame comparison
reco_id_list_size [in, out]: Size of the recognition ID array (input: buffer size, output: actual size)
roi [out]: Actual ROI region used for comparison

Get wait freezes details. Obtained via wf_id from the callback. Each reco_id can be queried via MaaTaskerGetRecognitionDetail to get the drawn images.

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.

MaaContextRunRecognitionDirect

reco_type: Recognition type (e.g., "OCR", "TemplateMatch")
reco_param: Recognition parameters JSON
image: Previous screenshot

Execute recognition directly with type and parameters, without requiring a pipeline 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.

MaaContextRunActionDirect

action_type: Action type (e.g., "Click", "Swipe")
action_param: Action parameters JSON
box: Previous recognition position
reco_detail: Previous recognition details

Execute action directly with type and parameters, without requiring a pipeline 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

MaaContextWaitFreezes

time: Wait time in milliseconds (simple mode)
box: Recognition hit box, used when target is Self to calculate ROI
wait_freezes_param: Optional advanced parameters JSON object containing:
- time: Wait time in milliseconds
- target: Target region, supports Self (default), PreTask, Region types
- threshold: Similarity threshold (default 0.95)
- method: Comparison method (default template matching method)
- rate_limit: Screenshot interval in milliseconds (default 1000)
- timeout: Timeout in milliseconds (default 20000)

Wait for screen to stabilize. time and wait_freezes_param.time are mutually exclusive: both cannot be non-zero, and both cannot be zero.

MaaAgentClientAPI.h

MaaAgentClientCreateV2

identifier: Connection identifier buffer (can be empty, auto-generate if empty)

Create Agent client

If empty, an IPC identifier is generated automatically
If a numeric string (1-65535) is passed, it is treated as a TCP port and listens on 127.0.0.1
On older Windows versions that don't support AF_UNIX (before Build 17063), it automatically falls back to TCP mode

MaaAgentClientCreateTcp

port: TCP port number (0-65535)

Create Agent client (TCP mode)

The Agent client will listen on 127.0.0.1 at the specified TCP port. If 0 is passed, the system will automatically select an available port. The AgentServer can use the port number obtained from MaaAgentClientIdentifier as the identifier to connect via TCP.

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

MaaAgentClientRegisterControllerSink

ctrl: Controller

MaaAgentClientRegisterTaskerSink

tasker: Instance

MaaAgentClientConnect

Connect. If startup, protocol validation, or custom registration fails, the client rolls back registrations made by the current attempt and tries to shut down the remote session before returning false.

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

MaaAgentServerRegisterCustomAction

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

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

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

NOTE

On Win32, the returned value is a native HWND.
On macOS, the returned value represents the window windowID (CGWindowID / SCWindow.windowID). It is force-cast to void* at the API layer, so it is not a Cocoa NSWindow* pointer.
On Linux, the returned value represents the display number n in the Wayland socket name wayland-<n>. It is force-cast to void* at the API layer, so it is not a native window handle.

MaaToolkitDesktopWindowGetClassName

window: Window

Get window class name

NOTE

On Win32, the returned value is the window class name.
On macOS, the returned value is the Bundle ID (SCWindow.owningApplication.bundleIdentifier).
On Linux, the returned value is the full path of the Wayland socket (e.g. /run/user/1000/wayland-0).

MaaToolkitDesktopWindowGetWindowName

window: Window

Get window name

NOTE

On Win32, the returned value is the window name.
On macOS, the returned value is the window title (SCWindow.title).
On Linux, the returned value is the file name of the Wayland socket (e.g. wayland-0).

MaaToolkitGamescope.h

Linux (non-Android) only.

MaaToolkitGamescopeInstanceListCreate

Create a gamescope instance list

MaaToolkitGamescopeInstanceListDestroy

handle: Instance list handle

Destroy a gamescope instance list

MaaToolkitGamescopeInstanceFindAll

buffer [out]: Output buffer

Enumerate gamescope instances into buffer (the list is empty when gamescope is not running).
Each instance is keyed by a gamescope-<n> Wayland socket under $XDG_RUNTIME_DIR (falling back to /run/user/<uid> when unset); its PipeWire node ID is fetched via the gamescope_pipewire protocol, and its EIS socket path is derived as the same-named gamescope-<n>-ei.
Sorted by display number in ascending order; stale sockets that cannot be connected to are dropped

MaaToolkitGamescopeInstanceListSize

list: Instance list

Get instance list size

MaaToolkitGamescopeInstanceListAt

list: Instance list
index: Index

Get instance at the specified index in the instance list

MaaToolkitGamescopeInstanceGetDisplayNo

instance: Instance

Get display number (the n in gamescope-<n>)

MaaToolkitGamescopeInstanceGetPipeWireNodeId

instance: Instance

Get PipeWire node ID (0 means no capture node available); a non-zero value is usable as the pw_node_id config of the Linux controller (session-daemon node capture)

MaaToolkitGamescopeInstanceGetEisSocketPath

instance: Instance

Get EIS socket path (empty string means no EIS socket), usable as the eis_socket_path config of the Linux controller (Libei input)

MaaToolkitPortal.h

Linux (non-Android) only; calls on other platforms fail and return empty values (nullptr / -1 / 0 / false).

MaaToolkitPortalHelperCreate

Create a Portal helper object, used to complete the authorization flow through the xdg-desktop-portal ScreenCast interface and obtain PipeWire screencap stream parameters.

MaaToolkitPortalHelperDestroy

helper: Portal helper object

Destroy the Portal helper object and close the D-Bus session it holds

MaaToolkitPortalHelperOpenStream

helper: Portal helper object

Run a complete ScreenCast authorization flow (CreateSession → SelectSources → Start → OpenPipeWireRemote), selecting a single monitor. A system authorization dialog pops up during the process and waits for user confirmation; it fails if not confirmed within 30 seconds.

Authorization options must be set before calling via MaaToolkitPortalHelperSetPersist / MaaToolkitPortalHelperSetRestoreToken.
On failure, the session created internally during this call is cleaned up.

MaaToolkitPortalHelperGetPersist

helper: Portal helper object

Get whether persistent authorization (persist) is currently requested, default false

MaaToolkitPortalHelperSetPersist

helper: Portal helper object
enable: whether to request persistent authorization

Set whether to request persistent authorization; must be called before MaaToolkitPortalHelperOpenStream

MaaToolkitPortalHelperGetPipeWireFD

helper: Portal helper object

Get the PipeWire socket FD obtained from authorization (-1 means not yet obtained), usable as the pw_socket_fd config of the Linux controller

MaaToolkitPortalHelperGetPipeWireNodeID

helper: Portal helper object

Get the PipeWire node ID obtained from authorization (0 means not yet obtained), usable as the pw_node_id config of the Linux controller

MaaToolkitPortalHelperGetRestoreToken

helper: Portal helper object

Get the restore token (empty string means not obtained). When persistent authorization is requested, the portal issues it after successful authorization; persist it and pass it next time via MaaToolkitPortalHelperSetRestoreToken to avoid repeated authorization

MaaToolkitPortalHelperSetRestoreToken

helper: Portal helper object
token: restore token

Set the restore token; must be called before MaaToolkitPortalHelperOpenStream; passing a null pointer fails

2.2 Integrated Interface Overview ​

About Binding ​

MaaUtility.h ​

MaaVersion ​

MaaGlobalSetOption ​

MaaGlobalLoadPlugin ​

MaaBuffer.h ​

MaaImageBufferResize ​

MaaResource.h ​

MaaResourceCreate ​

MaaResourceDestroy ​

MaaResourceAddSink ​

MaaResourceRemoveSink ​

MaaResourceClearSinks ​

MaaResourceRegisterCustomRecognition ​

MaaResourceUnregisterCustomRecognition ​

MaaResourceClearCustomRecognition ​

MaaResourceRegisterCustomAction ​

MaaResourceUnregisterCustomAction ​

MaaResourceClearCustomAction ​

MaaResourcePostBundle ​

MaaResourceOverridePipeline ​

MaaResourceOverrideNext ​

MaaResourceOverrideImage ​

MaaResourceGetNodeData ​

MaaResourceClear ​

MaaResourceStatus ​

MaaResourceWait ​

MaaResourceLoaded ​

MaaResourceSetOption ​

MaaResourceGetHash ​

MaaResourceGetNodeList ​

MaaResourceGetCustomRecognitionList ​

MaaResourceGetCustomActionList ​

MaaResourceGetDefaultRecognitionParam ​

MaaResourceGetDefaultActionParam ​

MaaController.h ​

MaaAdbControllerCreate ​

MaaWin32ControllerCreate ​

MaaAndroidNativeControllerCreate ​

MaaCustomControllerCreate ​

MaaDbgControllerCreate ​

MaaReplayControllerCreate ​

MaaRecordControllerCreate ​

MaaPlayCoverControllerCreate ​

MaaLinuxControllerCreate ​

MaaGamepadControllerCreate ​

MaaControllerDestroy ​

MaaControllerAddSink ​

MaaControllerRemoveSink ​

MaaControllerClearSinks ​

MaaControllerSetOption ​

MaaControllerPostConnection ​

MaaControllerPostClick ​

MaaControllerPostClickV2 ​

MaaControllerPostSwipe ​

MaaControllerPostSwipeV2 ​

MaaControllerPostClickKey ​

MaaControllerPostKeyDown ​

MaaControllerPostKeyUp ​

MaaControllerPostInputText ​

MaaControllerPostStartApp ​

MaaControllerPostStopApp ​

MaaControllerPostTouchDown ​

MaaControllerPostTouchMove ​

MaaControllerPostTouchUp ​

MaaControllerPostRelativeMove ​

MaaControllerPostScroll ​

MaaControllerPostInactive ​

MaaControllerPostScreencap ​

MaaControllerPostShell ​

MaaControllerStatus ​

MaaControllerWait ​

MaaControllerConnected ​

MaaControllerCachedImage ​

MaaControllerGetResolution ​

MaaControllerGetShellOutput ​

MaaControllerGetUuid ​

MaaControllerGetInfo ​

MaaTasker.h ​

2.2 Integrated Interface Overview

About Binding

MaaUtility.h

MaaVersion

MaaGlobalSetOption

MaaGlobalLoadPlugin

MaaBuffer.h

MaaImageBufferResize

MaaResource.h

MaaResourceCreate

MaaResourceDestroy

MaaResourceAddSink

MaaResourceRemoveSink

MaaResourceClearSinks

MaaResourceRegisterCustomRecognition

MaaResourceUnregisterCustomRecognition

MaaResourceClearCustomRecognition

MaaResourceRegisterCustomAction

MaaResourceUnregisterCustomAction

MaaResourceClearCustomAction

MaaResourcePostBundle

MaaResourceOverridePipeline

MaaResourceOverrideNext

MaaResourceOverrideImage

MaaResourceGetNodeData

MaaResourceClear

MaaResourceStatus

MaaResourceWait

MaaResourceLoaded

MaaResourceSetOption

MaaResourceGetHash

MaaResourceGetNodeList

MaaResourceGetCustomRecognitionList

MaaResourceGetCustomActionList

MaaResourceGetDefaultRecognitionParam

MaaResourceGetDefaultActionParam

MaaController.h

MaaAdbControllerCreate

MaaWin32ControllerCreate

MaaAndroidNativeControllerCreate

MaaCustomControllerCreate

MaaDbgControllerCreate

MaaReplayControllerCreate

MaaRecordControllerCreate

MaaPlayCoverControllerCreate

MaaLinuxControllerCreate

MaaGamepadControllerCreate

MaaControllerDestroy

MaaControllerAddSink

MaaControllerRemoveSink

MaaControllerClearSinks

MaaControllerSetOption

MaaControllerPostConnection

MaaControllerPostClick

MaaControllerPostClickV2

MaaControllerPostSwipe

MaaControllerPostSwipeV2

MaaControllerPostClickKey

MaaControllerPostKeyDown

MaaControllerPostKeyUp

MaaControllerPostInputText

MaaControllerPostStartApp

MaaControllerPostStopApp

MaaControllerPostTouchDown

MaaControllerPostTouchMove

MaaControllerPostTouchUp

MaaControllerPostRelativeMove

MaaControllerPostScroll

MaaControllerPostInactive

MaaControllerPostScreencap

MaaControllerPostShell

MaaControllerStatus

MaaControllerWait

MaaControllerConnected

MaaControllerCachedImage

MaaControllerGetResolution

MaaControllerGetShellOutput

MaaControllerGetUuid

MaaControllerGetInfo

MaaTasker.h