Struct Controller 

pub struct Controller { /* private fields */ }

Device controller interface.

Handles interaction with the target device, including:

• Input events (click, swipe, key press)
• Screen capture
• App management (start/stop)
• Connection management

See also: AdbControllerBuilder for advanced ADB configuration.

Implementations

impl Controller

pub fn new_adb( adb_path: &str, address: &str, config: &str, agent_path: &str, ) -> MaaResult<Self>

Create a new ADB controller for Android device control.

Arguments

• adb_path - Path to the ADB executable
• address - Device address (e.g., “127.0.0.1:5555” or “emulator-5554”)
• config - JSON configuration string for advanced options
• agent_path - Path to MaaAgent binary; pass "" to use current directory (may return Err if resolution fails).

pub fn new_win32( hwnd: *mut c_void, screencap_method: MaaWin32ScreencapMethod, mouse_method: MaaWin32InputMethod, keyboard_method: MaaWin32InputMethod, ) -> MaaResult<Self>

Create a new Win32 controller for Windows window control.

pub fn new_macos( window_id: u32, screencap_method: MaaMacOSScreencapMethod, input_method: MaaMacOSInputMethod, ) -> MaaResult<Self>

Create a new macOS controller for native macOS window control.

Arguments

• window_id - Target CGWindowID (use 0 for desktop)
• screencap_method - macOS screenshot method
• input_method - macOS input method

pub fn new_android_native<T: Serialize>(config: &T) -> MaaResult<Self>

Create a new Android native controller.

The config is serialized to JSON and passed to MaaAndroidNativeControllerCreate. You can pass either a common::AndroidNativeControllerConfig value or any other serializable type that matches the expected JSON schema.

pub fn new_playcover(address: &str, uuid: &str) -> MaaResult<Self>

Create a new PlayCover controller for iOS app control on macOS.

pub fn new_wlroots(wlr_socket_path: &str) -> MaaResult<Self>

Create a new WlRoots controller for apps running in wlroots compositor on Linux.

Arguments

• wlr_socket_path - Wayland socket path

pub fn new_wlroots_with_vk_code( wlr_socket_path: &str, use_win32_vk_code: bool, ) -> MaaResult<Self>

Create a new WlRoots controller for apps running in wlroots compositor on Linux.

Arguments

• wlr_socket_path - Wayland socket path
• use_win32_vk_code - Interpret key codes as Win32 Virtual-Key codes and translate them to Linux evdev codes internally when set to true

pub fn new_kwin( device_node: &str, screen_width: i32, screen_height: i32, ) -> MaaResult<Self>

Create a new KWin / Linux Wayland controller.

Despite its name, this controller works with any Wayland compositor that implements the XDG Screencast Portal (e.g. GNOME), provided the kernel supports uinput.

Screencap is provided by PipeWire / xdg-desktop-portal and input is simulated through /dev/uinput.

Arguments

• device_node - The uinput device node path (e.g. /dev/uinput)
• screen_width - The screen width in pixels
• screen_height - The screen height in pixels

Notes

• Requires PipeWire 1.0+ and xdg-desktop-portal.
• Requires user authorization via the screen sharing dialog (xdg-desktop-portal).
• Requires write permission to /dev/uinput (typically via the input group).

Only available on Linux: the underlying MaaKWinControllerCreate symbol is not exported by the Windows/macOS builds of MaaFramework.

pub fn new_kwin_with_vk_code( device_node: &str, screen_width: i32, screen_height: i32, use_win32_vk_code: bool, ) -> MaaResult<Self>

Create a new KWin / Linux Wayland controller.

Same as new_kwin, but lets you control how key codes are interpreted.

Arguments

• device_node - The uinput device node path (e.g. /dev/uinput)
• screen_width - The screen width in pixels
• screen_height - The screen height in pixels
• use_win32_vk_code - Interpret key codes as Win32 Virtual-Key codes and translate them to Linux evdev codes internally when set to true

pub fn new_custom<T: CustomControllerCallback + 'static>( callback: T, ) -> MaaResult<Self>

Create a custom controller with user-defined callbacks.

pub fn post_click(&self, x: i32, y: i32) -> MaaResult<MaaId>

Post a click action at the specified coordinates.

pub fn post_screencap(&self) -> MaaResult<MaaId>

Post a screenshot capture request.

pub fn post_click_v2( &self, x: i32, y: i32, contact: i32, pressure: i32, ) -> MaaResult<MaaId>

Post a click action with contact and pressure parameters.

Arguments

• x, y - Click coordinates
• contact - Contact/finger index (for multi-touch)
• pressure - Touch pressure (1 = normal)

pub fn post_swipe( &self, x1: i32, y1: i32, x2: i32, y2: i32, duration: i32, ) -> MaaResult<MaaId>

Post a swipe action from one point to another.

Arguments

• x1, y1 - Start coordinates
• x2, y2 - End coordinates
• duration - Swipe duration in milliseconds

pub fn post_click_key(&self, keycode: i32) -> MaaResult<MaaId>

Post a key click action.

Arguments

• keycode - Virtual key code (ADB keycode for Android, VK for Win32)

pub fn post_press(&self, keycode: i32) -> MaaResult<MaaId>

👎Deprecated:

Use post_click_key instead

Alias for post_click_key.

pub fn post_input_text(&self, text: &str) -> MaaResult<MaaId>

Post a text input action.

Arguments

• text - Text to input

pub fn post_shell(&self, cmd: &str, timeout: i64) -> MaaResult<MaaId>

Post a shell command execution on controllers that support shell access.

Arguments

• cmd - Shell command to execute
• timeout - Timeout in milliseconds

pub fn post_touch_down( &self, contact: i32, x: i32, y: i32, pressure: i32, ) -> MaaResult<MaaId>

Post a touch down event.

Arguments

• contact - Contact/finger index
• x, y - Touch coordinates
• pressure - Touch pressure

pub fn post_touch_move( &self, contact: i32, x: i32, y: i32, pressure: i32, ) -> MaaResult<MaaId>

Post a touch move event.

Arguments

• contact - Contact/finger index
• x, y - New touch coordinates
• pressure - Touch pressure

pub fn post_touch_up(&self, contact: i32) -> MaaResult<MaaId>

Post a touch up event.

Arguments

• contact - Contact/finger index to release

pub fn post_relative_move(&self, dx: i32, dy: i32) -> MaaResult<MaaId>

Post a relative movement action on controllers that support it.

Arguments

• dx - Relative horizontal movement offset
• dy - Relative vertical movement offset

pub fn raw(&self) -> *mut MaaController

Returns the underlying raw controller handle.

pub fn post_connection(&self) -> MaaResult<MaaId>

Post a connection request to the device.

Returns a job ID that can be used with wait to block until connected.

pub fn connected(&self) -> bool

Returns true if the controller is connected to the device.

pub fn uuid(&self) -> MaaResult<String>

Gets the unique identifier (UUID) of the connected device.

pub fn info(&self) -> MaaResult<Value>

Gets the controller information as a JSON value.

Returns controller-specific information including type, constructor parameters and current state. The returned JSON always contains a “type” field.

pub fn resolution(&self) -> MaaResult<(i32, i32)>

Gets the device screen resolution as (width, height).

pub fn post_swipe_v2( &self, x1: i32, y1: i32, x2: i32, y2: i32, duration: i32, contact: i32, pressure: i32, ) -> MaaResult<MaaId>

Post a swipe action with contact and pressure parameters.

Arguments

• x1, y1 - Start coordinates
• x2, y2 - End coordinates
• duration - Swipe duration in milliseconds
• contact - Contact/finger index
• pressure - Touch pressure

pub fn post_key_down(&self, keycode: i32) -> MaaResult<MaaId>

Post a key down event.

pub fn post_key_up(&self, keycode: i32) -> MaaResult<MaaId>

Post a key up event.

pub fn post_start_app(&self, intent: &str) -> MaaResult<MaaId>

Start an application.

Arguments

• intent - Package name or activity (ADB), app identifier (Win32)

pub fn post_stop_app(&self, intent: &str) -> MaaResult<MaaId>

Stop an application.

Arguments

• intent - Package name (ADB)

pub fn post_scroll(&self, dx: i32, dy: i32) -> MaaResult<MaaId>

Post a scroll action on controllers that support it.

Arguments

• dx - Horizontal scroll delta (positive = right)
• dy - Vertical scroll delta (positive = down)

pub fn post_inactive(&self) -> MaaResult<MaaId>

Post an inactive request to the controller.

For Win32 controllers, this restores window position (removes topmost) and unblocks user input. For other controllers, this is a no-op that always succeeds.

pub fn cached_image(&self) -> MaaResult<MaaImageBuffer>

Gets the most recently captured screenshot.

pub fn shell_output(&self) -> MaaResult<String>

Gets the output from the most recent shell command.

pub fn status(&self, ctrl_id: MaaId) -> MaaStatus

Gets the status of a controller operation.

pub fn wait(&self, ctrl_id: MaaId) -> MaaStatus

Blocks until a controller operation completes.

pub fn set_screenshot_target_long_side(&self, long_side: i32) -> MaaResult<()>

Sets the target long side for screenshot scaling.

pub fn set_screenshot_target_short_side(&self, short_side: i32) -> MaaResult<()>

Sets the target short side for screenshot scaling.

pub fn set_screenshot_use_raw_size(&self, enable: bool) -> MaaResult<()>

Sets whether to use raw (unscaled) screenshot resolution.

pub fn set_screenshot_resize_method(&self, method: i32) -> MaaResult<()>

Sets the interpolation method used when resizing screenshots.

Values correspond to OpenCV interpolation flags: 0 = INTER_NEAREST 1 = INTER_LINEAR 2 = INTER_CUBIC 3 = INTER_AREA 4 = INTER_LANCZOS4

pub fn set_mouse_lock_follow(&self, enable: bool) -> MaaResult<()>

Sets whether to enable mouse-lock-follow mode.

For Win32 controllers, useful for TPS/FPS games that lock the mouse to their window while running in the background.

pub fn set_background_managed_keys(&self, keys: &[i32]) -> MaaResult<()>

Configure background managed key domain for Win32 controllers.

Must be set before connection. After setting, matching ClickKey / LongPressKey / KeyDown / KeyUp operations automatically route through the background guardian path. Only supported by Win32 controllers; other controllers will fail.

Pass an empty slice to clear managed keys.

pub fn new_dbg(read_path: &str) -> MaaResult<Self>

pub fn new_replay(recording_path: &str) -> MaaResult<Self>

Create a replay controller for replaying recorded controller operations.

pub fn new_record(inner: &Controller, recording_path: &str) -> MaaResult<Self>

Create a record controller that wraps another controller and records all operations.

pub fn new_gamepad( hwnd: *mut c_void, gamepad_type: GamepadType, screencap_method: Win32ScreencapMethod, ) -> MaaResult<Self>

Create a virtual gamepad controller (Windows only).

pub fn add_sink<F>(&self, callback: F) -> MaaResult<MaaSinkId>

where F: Fn(&str, &str) + Send + Sync + 'static,

Returns sink_id for later removal. Callback lifetime managed by caller.

pub fn add_event_sink(&self, sink: Box<dyn EventSink>) -> MaaResult<MaaSinkId>

Register a strongly-typed event sink.

This method registers an implementation of the EventSink trait to receive structured notifications from this controller.

Arguments

• sink - The event sink implementation (must be boxed).

Returns

A MaaSinkId which can be used to manually remove the sink later via remove_sink. The sink will be automatically unregistered and dropped when the Controller is dropped.

pub fn remove_sink(&self, sink_id: MaaSinkId)

pub fn clear_sinks(&self)

Trait Implementations

impl Clone for Controller

fn clone(&self) -> Controller

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Controller

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for Controller

impl Sync for Controller