# 2.2 Integrated Interface Overview

## About Binding

Different language bindings may have different naming conventions and are wrapped according to the [Standardized Interface Design](./4.2-StandardizedInterfaceDesign.md). 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`.

### 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`.

### 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](2.4-ControlMethods.md#adb-screencap)
- `input_methods`: all available input methods, see [Control Methods](2.4-ControlMethods.md#adb-input)
- `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](2.4-ControlMethods.md#win32-screencap)
- `mouse_method`: mouse input method used, see [Control Methods](2.4-ControlMethods.md#win32-input)
- `keyboard_method`: keyboard input method used, see [Control Methods](2.4-ControlMethods.md#win32-input)

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.

### 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](https://github.com/hguandl/PlayCover/releases) on macOS. See [Control Methods](2.4-ControlMethods.md#playcover-macos).

### MaaWlRootsControllerCreate

- `wlr_socket_path`: Wayland Socket path, e.g., `/run/user/1000/wayland-0`
- `use_win32_vk_code`: Whether to interpret key codes as Win32 Virtual-Key codes (VK_*). When `true`, key codes passed to `click_key` / `key_down` / `key_up` are interpreted as Win32 VK codes and translated to Linux evdev codes internally; when `false`, they are passed through as raw evdev codes. Default is `false`

Create WlRoots controller for controlling applications running in wlroots compositor on Linux. See [Control Methods](2.4-ControlMethods.md#wlroots-linux).

### MaaGamepadControllerCreate

- `hWnd`: Window handle for screencap. Pass nullptr/None/null if screencap is not needed
- `gamepad_type`: Gamepad type, see [Control Methods](2.4-ControlMethods.md#gamepad-types)
- `screencap_method`: Win32 screencap method, see [Control Methods](2.4-ControlMethods.md#win32-screencap)

Create Gamepad controller for emulating Xbox 360 or DualShock 4 gamepad input on Windows. See [Control Methods](2.4-ControlMethods.md#gamepad-windows).

notice

- [ViGEm Bus Driver](https://github.com/ViGEm/ViGEmBus/releases) 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

- 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.)
  - 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.)
  - 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
  - [Adb Controller](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 Controller](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS Controller](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

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](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 Controller](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS Controller](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

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](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 Controller](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS Controller](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

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)
  - 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
  - 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
  - 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`
- `wlroots`: `type`, `wlr_socket_path`
- `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.

## 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.

### 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`).

### 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`).

## 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

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
