MaaFw 4.5.5__py3-none-manylinux2014_x86_64.whl → 5.4.0__py3-none-manylinux2014_x86_64.whl

maa/define.py

@@ -16,7 +16,9 @@ MaaCtrlId = MaaId
 MaaResId = MaaId
 MaaTaskId = MaaId
 MaaRecoId = MaaId
+MaaActId = MaaId
 MaaNodeId = MaaId
+MaaSinkId = MaaId
 MaaInvalidId = MaaId(0)
 
 MaaStringBufferHandle = ctypes.c_void_p
@@ -89,6 +91,23 @@ class MaaGlobalOptionEnum(IntEnum):
     # value: bool, eg: true; val_size: sizeof(bool)
     DebugMode = 6
 
+    # Whether to save screenshot on error
+    #
+    # value: bool, eg: true; val_size: sizeof(bool)
+    SaveOnError = 7
+
+    # Image quality for draw images
+    #
+    # value: int, eg: 85; val_size: sizeof(int)
+    # default value is 85, range: [0, 100]
+    DrawQuality = 8
+
+    # Recognition image cache limit
+    #
+    # value: size_t, eg: 4096; val_size: sizeof(size_t)
+    # default value is 4096
+    RecoImageCacheLimit = 9
+
 
 class MaaCtrlOptionEnum(IntEnum):
     Invalid = 0
@@ -165,8 +184,25 @@ MaaAdbScreencapMethod = ctypes.c_uint64
 
 class MaaAdbScreencapMethodEnum(IntEnum):
     """
-    Use bitwise OR to set the method you need
-    MaaFramework will test their speed and use the fastest one.
+    Adb screencap method flags.
+
+    Use bitwise OR to set the methods you need.
+    MaaFramework will test all provided methods and use the fastest available one.
+
+    Default: All methods except RawByNetcat, MinicapDirect, MinicapStream
+
+    Note: MinicapDirect and MinicapStream use lossy JPEG encoding, which may
+    significantly reduce template matching accuracy. Not recommended.
+
+    | Method                | Speed      | Compatibility | Encoding | Notes                             |
+    |-----------------------|------------|---------------|----------|-----------------------------------|
+    | EncodeToFileAndPull   | Slow       | High          | Lossless |                                   |
+    | Encode                | Slow       | High          | Lossless |                                   |
+    | RawWithGzip           | Medium     | High          | Lossless |                                   |
+    | RawByNetcat           | Fast       | Low           | Lossless |                                   |
+    | MinicapDirect         | Fast       | Low           | Lossy    |                                   |
+    | MinicapStream         | Very Fast  | Low           | Lossy    |                                   |
+    | EmulatorExtras        | Very Fast  | Low           | Lossless | Emulators only: MuMu 12, LDPlayer 9 |
     """
 
     Null = 0
@@ -188,9 +224,21 @@ MaaAdbInputMethod = ctypes.c_uint64
 
 class MaaAdbInputMethodEnum(IntEnum):
     """
-    Use bitwise OR to set the method you need
-    MaaFramework will select the available ones according to priority.
-    The priority is: EmulatorExtras > Maatouch > MinitouchAndAdbKey > AdbShell
+    Adb input method flags.
+
+    Use bitwise OR to set the methods you need.
+    MaaFramework will select the first available method according to priority.
+
+    Priority (high to low): EmulatorExtras > Maatouch > MinitouchAndAdbKey > AdbShell
+
+    Default: All methods except EmulatorExtras
+
+    | Method               | Speed | Compatibility | Notes                                 |
+    |----------------------|-------|---------------|---------------------------------------|
+    | AdbShell             | Slow  | High          |                                       |
+    | MinitouchAndAdbKey   | Fast  | Medium        | Key press still uses AdbShell         |
+    | Maatouch             | Fast  | Medium        |                                       |
+    | EmulatorExtras       | Fast  | Low           | Emulators only: MuMu 12               |
     """
 
     Null = 0
@@ -207,29 +255,176 @@ class MaaAdbInputMethodEnum(IntEnum):
 MaaWin32ScreencapMethod = ctypes.c_uint64
 
 
-# No bitwise OR, just set it
 class MaaWin32ScreencapMethodEnum(IntEnum):
+    """
+    Win32 screencap method.
+
+    No bitwise OR, select ONE method only.
+
+    No default value. Client should choose one as default.
+
+    Different applications use different rendering methods, there is no universal solution.
+
+    | Method                  | Speed     | Compatibility | Require Admin | Background Support | Notes                            |
+    |-------------------------|-----------|---------------|---------------|--------------------|----------------------------------|
+    | GDI                     | Fast      | Medium        | No            | No                 |                                  |
+    | FramePool               | Very Fast | Medium        | No            | Yes                | Requires Windows 10 1903+        |
+    | DXGI_DesktopDup         | Very Fast | Low           | No            | No                 | Desktop duplication (full screen)|
+    | DXGI_DesktopDup_Window  | Very Fast | Low           | No            | No                 | Desktop duplication then crop    |
+    | PrintWindow             | Medium    | Medium        | No            | Yes                |                                  |
+    | ScreenDC                | Fast      | High          | No            | No                 |                                  |
+
+    Note: When a window is minimized on Windows, all screencap methods will fail.
+    Avoid minimizing the target window.
+    """
+
     Null = 0
 
     GDI = 1
     FramePool = 1 << 1
     DXGI_DesktopDup = 1 << 2
+    DXGI_DesktopDup_Window = 1 << 3
+    PrintWindow = 1 << 4
+    ScreenDC = 1 << 5
 
 
 MaaWin32InputMethod = ctypes.c_uint64
 
 
-# No bitwise OR, just set it
 class MaaWin32InputMethodEnum(IntEnum):
+    """
+    Win32 input method.
+
+    No bitwise OR, select ONE method only.
+
+    No default value. Client should choose one as default.
+
+    Different applications process input differently, there is no universal solution.
+
+    | Method                       | Compatibility | Require Admin | Seize Mouse | Background Support | Notes                                                       |
+    |------------------------------|---------------|---------------|--------------|--------------------|-------------------------------------------------------------|
+    | Seize                        | High          | No            | Yes          | No                 |                                                             |
+    | SendMessage                  | Medium        | Maybe         | No           | Yes                |                                                             |
+    | PostMessage                  | Medium        | Maybe         | No           | Yes                |                                                             |
+    | LegacyEvent                  | Low           | No            | Yes          | No                 |                                                             |
+    | PostThreadMessage            | Low           | Maybe         | No           | Yes                |                                                             |
+    | SendMessageWithCursorPos     | Medium        | Maybe         | Briefly      | Yes                | Designed for apps that check real cursor position           |
+    | PostMessageWithCursorPos     | Medium        | Maybe         | Briefly      | Yes                | Designed for apps that check real cursor position           |
+
+    Note:
+    - Admin rights mainly depend on the target application's privilege level.
+      If the target runs as admin, MaaFramework should also run as admin for compatibility.
+    - "WithCursorPos" methods briefly move the cursor to target position, send message,
+      then restore cursor position. This "briefly" seizes the mouse but won't block user operations.
+    """
+
     Null = 0
 
     Seize = 1
     SendMessage = 1 << 1
+    PostMessage = 1 << 2
+    LegacyEvent = 1 << 3
+    PostThreadMessage = 1 << 4
+    SendMessageWithCursorPos = 1 << 5
+    PostMessageWithCursorPos = 1 << 6
 
 
 # No bitwise OR, just set it
 MaaDbgControllerType = ctypes.c_uint64
 
+# No bitwise OR, just set it
+MaaGamepadType = ctypes.c_uint64
+
+
+class MaaGamepadTypeEnum(IntEnum):
+    """
+    Virtual gamepad type for GamepadController (Windows only).
+
+    No bitwise OR, select ONE type only.
+
+    Requires ViGEm Bus Driver to be installed.
+
+    | Type        | Description                           |
+    |-------------|---------------------------------------|
+    | Xbox360     | Microsoft Xbox 360 Controller (wired) |
+    | DualShock4  | Sony DualShock 4 Controller (wired)   |
+    """
+
+    Xbox360 = 0
+    DualShock4 = 1
+
+
+class MaaGamepadButtonEnum(IntEnum):
+    """
+    Gamepad button flags (XUSB protocol values).
+
+    Use bitwise OR to combine multiple buttons.
+    DS4 face buttons are aliases to Xbox face buttons.
+    """
+
+    # D-pad
+    DPAD_UP = 0x0001
+    DPAD_DOWN = 0x0002
+    DPAD_LEFT = 0x0004
+    DPAD_RIGHT = 0x0008
+
+    # Control buttons
+    START = 0x0010
+    BACK = 0x0020
+    LEFT_THUMB = 0x0040  # L3
+    RIGHT_THUMB = 0x0080  # R3
+
+    # Shoulder buttons
+    LB = 0x0100  # Left Bumper / L1
+    RB = 0x0200  # Right Bumper / R1
+
+    # Guide button
+    GUIDE = 0x0400
+
+    # Face buttons (Xbox layout)
+    A = 0x1000
+    B = 0x2000
+    X = 0x4000
+    Y = 0x8000
+
+    # DS4 face buttons (aliases to Xbox buttons)
+    CROSS = A
+    CIRCLE = B
+    SQUARE = X
+    TRIANGLE = Y
+    L1 = LB
+    R1 = RB
+    L3 = LEFT_THUMB
+    R3 = RIGHT_THUMB
+    OPTIONS = START
+    SHARE = BACK
+
+    # DS4 special buttons (unique values)
+    PS = 0x10000
+    TOUCHPAD = 0x20000
+
+
+class MaaGamepadContactEnum(IntEnum):
+    """
+    Gamepad contact (analog stick or trigger) mapping for touch_down/touch_move/touch_up.
+    """
+
+    LEFT_STICK = 0  # x: -32768~32767, y: -32768~32767
+    RIGHT_STICK = 1  # x: -32768~32767, y: -32768~32767
+    LEFT_TRIGGER = 2  # pressure: 0~255
+    RIGHT_TRIGGER = 3  # pressure: 0~255
+
+
+MaaControllerFeature = ctypes.c_uint64
+
+
+# Use bitwise OR to set the features you need
+class MaaControllerFeatureEnum(IntEnum):
+    Null = 0
+
+    UseMouseDownAndUpInsteadOfClick = 1
+    UseKeyboardDownAndUpInsteadOfClick = 1 << 1
+
 
 class MaaDbgControllerTypeEnum(IntEnum):
     Null = 0
@@ -240,8 +435,8 @@ class MaaDbgControllerTypeEnum(IntEnum):
 
 FUNCTYPE = ctypes.WINFUNCTYPE if (platform.system() == "Windows") else ctypes.CFUNCTYPE
 
-MaaNotificationCallback = FUNCTYPE(
-    None, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_void_p
+MaaEventCallback = FUNCTYPE(
+    None, ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_void_p
 )
 
 MaaCustomRecognitionCallback = FUNCTYPE(
@@ -284,11 +479,19 @@ class MaaCustomControllerCallbacks(ctypes.Structure):
         MaaBool,
         ctypes.c_void_p,
     )
+    ConnectedFunc = FUNCTYPE(
+        MaaBool,
+        ctypes.c_void_p,
+    )
     RequestUuidFunc = FUNCTYPE(
         MaaBool,
         ctypes.c_void_p,
         MaaStringBufferHandle,
     )
+    GetFeaturesFunc = FUNCTYPE(
+        MaaControllerFeature,
+        ctypes.c_void_p,
+    )
     StartAppFunc = FUNCTYPE(
         MaaBool,
         ctypes.c_char_p,
@@ -360,9 +563,17 @@ class MaaCustomControllerCallbacks(ctypes.Structure):
         ctypes.c_int32,
         ctypes.c_void_p,
     )
+    ScrollFunc = FUNCTYPE(
+        MaaBool,
+        ctypes.c_int32,
+        ctypes.c_int32,
+        ctypes.c_void_p,
+    )
     _fields_ = [
         ("connect", ConnectFunc),
+        ("connected", ConnectedFunc),
         ("request_uuid", RequestUuidFunc),
+        ("get_features", GetFeaturesFunc),
         ("start_app", StartAppFunc),
         ("stop_app", StopAppFunc),
         ("screencap", ScreencapFunc),
@@ -375,6 +586,7 @@ class MaaCustomControllerCallbacks(ctypes.Structure):
         ("input_text", InputTextFunc),
         ("key_down", KeyDownFunc),
         ("key_up", KeyUpFunc),
+        ("scroll", ScrollFunc),
     ]
 
 
@@ -410,6 +622,41 @@ class Status:
         return self._status == MaaStatusEnum.running
 
 
+@dataclass
+class Point:
+    x: int = 0
+    y: int = 0
+
+    def __add__(
+        self,
+        other: Union[
+            "Point",
+            Tuple[int, int],
+            List[int],
+        ],
+    ):
+        if (
+            isinstance(other, Point)
+            or isinstance(other, tuple)
+            or (isinstance(other, list) and len(other) == 2)
+        ):
+            x1, y1 = self
+            x2, y2 = other
+            return Point(
+                x1 + x2,
+                y1 + y2,
+            )
+
+        raise TypeError(f"Cannot add {type(other).__name__} to Point")
+
+    def __iter__(self):
+        yield self.x
+        yield self.y
+
+    def __getitem__(self, key):
+        return list(self)[key]
+
+
 @dataclass
 class Rect:
     x: int = 0
@@ -448,12 +695,15 @@ class Rect:
         yield self.h
 
     def __getitem__(self, key):
-        return self.roi[key]
+        return list(self)[key]
 
-    @property
-    def roi(self):
-        return list(self)
 
+PointType = Union[
+    Point,
+    List[int],
+    numpy.ndarray,
+    Tuple[int, int],
+]
 
 RectType = Union[
     Rect,
@@ -471,6 +721,31 @@ class AlgorithmEnum(StrEnum):
     OCR = "OCR"
     NeuralNetworkClassify = "NeuralNetworkClassify"
     NeuralNetworkDetect = "NeuralNetworkDetect"
+    And = "And"
+    Or = "Or"
+    Custom = "Custom"
+
+
+class ActionEnum(StrEnum):
+    DoNothing = "DoNothing"
+    Click = "Click"
+    LongPress = "LongPress"
+    Swipe = "Swipe"
+    MultiSwipe = "MultiSwipe"
+    ClickKey = "ClickKey"
+    LongPressKey = "LongPressKey"
+    InputText = "InputText"
+    StartApp = "StartApp"
+    StopApp = "StopApp"
+    Scroll = "Scroll"
+    TouchDown = "TouchDown"
+    TouchMove = "TouchMove"
+    TouchUp = "TouchUp"
+    KeyDown = "KeyDown"
+    KeyUp = "KeyUp"
+    StopTask = "StopTask"
+    Command = "Command"
+    Shell = "Shell"
     Custom = "Custom"
 
 
@@ -516,6 +791,20 @@ class CustomRecognitionResult:
     detail: Union[str, Dict]
 
 
+@dataclass
+class AndRecognitionResult:
+    """And 算法识别结果，包含所有子识别的完整详情"""
+
+    sub_results: List["RecognitionDetail"]
+
+
+@dataclass
+class OrRecognitionResult:
+    """Or 算法识别结果，包含已执行子识别的完整详情"""
+
+    sub_results: List["RecognitionDetail"]
+
+
 RecognitionResult = Union[
     TemplateMatchResult,
     FeatureMatchResult,
@@ -523,6 +812,8 @@ RecognitionResult = Union[
     OCRResult,
     NeuralNetworkClassifyResult,
     NeuralNetworkDetectResult,
+    AndRecognitionResult,
+    OrRecognitionResult,
     CustomRecognitionResult,
 ]
 
@@ -534,6 +825,8 @@ AlgorithmResultDict = {
     AlgorithmEnum.OCR: OCRResult,
     AlgorithmEnum.NeuralNetworkClassify: NeuralNetworkClassifyResult,
     AlgorithmEnum.NeuralNetworkDetect: NeuralNetworkDetectResult,
+    AlgorithmEnum.And: AndRecognitionResult,
+    AlgorithmEnum.Or: OrRecognitionResult,
     AlgorithmEnum.Custom: CustomRecognitionResult,
 }
 
@@ -542,11 +835,12 @@ AlgorithmResultDict = {
 class RecognitionDetail:
     reco_id: int
     name: str
-    algorithm: AlgorithmEnum
+    algorithm: Union[AlgorithmEnum, str]
+    hit: bool
     box: Optional[Rect]
 
     all_results: List[RecognitionResult]
-    filterd_results: List[RecognitionResult]
+    filtered_results: List[RecognitionResult]
     best_result: Optional[RecognitionResult]
 
     raw_detail: Dict
@@ -554,11 +848,133 @@ class RecognitionDetail:
     draw_images: List[numpy.ndarray]  # only valid in debug mode
 
 
+@dataclass
+class ClickActionResult:
+    point: Point
+    contact: int
+
+
+@dataclass
+class LongPressActionResult:
+    point: Point
+    duration: int
+    contact: int
+
+
+@dataclass
+class SwipeActionResult:
+    begin: Point
+    end: List[Point]
+    end_hold: List[int]
+    duration: List[int]
+    only_hover: bool
+    starting: int
+    contact: int
+
+
+@dataclass
+class MultiSwipeActionResult:
+    swipes: List[SwipeActionResult]
+
+
+@dataclass
+class ClickKeyActionResult:
+    keycode: List[int]
+
+
+@dataclass
+class LongPressKeyActionResult:
+    keycode: List[int]
+    duration: int
+
+
+@dataclass
+class InputTextActionResult:
+    text: str
+
+
+@dataclass
+class AppActionResult:
+    package: str
+
+
+@dataclass
+class ScrollActionResult:
+    dx: int
+    dy: int
+
+
+@dataclass
+class TouchActionResult:
+    contact: int
+    point: Point
+    pressure: int
+
+
+@dataclass
+class ShellActionResult:
+    cmd: str
+    timeout: int
+    success: bool
+    output: str
+
+
+ActionResult = Union[
+    ClickActionResult,
+    LongPressActionResult,
+    SwipeActionResult,
+    MultiSwipeActionResult,
+    ClickKeyActionResult,
+    LongPressKeyActionResult,
+    InputTextActionResult,
+    AppActionResult,
+    ScrollActionResult,
+    TouchActionResult,
+    ShellActionResult,
+    None,
+]
+
+ActionResultDict = {
+    ActionEnum.DoNothing: None,
+    ActionEnum.Click: ClickActionResult,
+    ActionEnum.LongPress: LongPressActionResult,
+    ActionEnum.Swipe: SwipeActionResult,
+    ActionEnum.MultiSwipe: MultiSwipeActionResult,
+    ActionEnum.ClickKey: ClickKeyActionResult,
+    ActionEnum.LongPressKey: LongPressKeyActionResult,
+    ActionEnum.InputText: InputTextActionResult,
+    ActionEnum.StartApp: AppActionResult,
+    ActionEnum.StopApp: AppActionResult,
+    ActionEnum.Scroll: ScrollActionResult,
+    ActionEnum.TouchDown: TouchActionResult,
+    ActionEnum.TouchMove: TouchActionResult,
+    ActionEnum.TouchUp: TouchActionResult,
+    ActionEnum.KeyDown: ClickKeyActionResult,
+    ActionEnum.KeyUp: ClickKeyActionResult,
+    ActionEnum.StopTask: None,
+    ActionEnum.Command: None,
+    ActionEnum.Shell: ShellActionResult,
+    ActionEnum.Custom: None,
+}
+
+
+@dataclass
+class ActionDetail:
+    action_id: int
+    name: str
+    action: Union[ActionEnum, str]
+    box: Rect
+    success: bool
+    result: Optional[ActionResult]
+    raw_detail: Dict
+
+
 @dataclass
 class NodeDetail:
     node_id: int
     name: str
-    recognition: RecognitionDetail
+    recognition: Optional[RecognitionDetail]
+    action: Optional[ActionDetail]
     completed: bool
 
 

maa/event_sink.py

@@ -0,0 +1,103 @@
+import ctypes
+import json
+from abc import ABC
+from typing import Tuple
+from enum import IntEnum
+
+from .define import MaaEventCallback
+
+
+# class NotificationEvent(IntEnum):
+#     ResourceLoading = 1
+#     ControllerAction = 2
+#     TaskerTask = 3
+#     TaskNextList = 4
+#     TaskRecognition = 5
+#     TaskAction = 6
+
+
+class NotificationType(IntEnum):
+    """通知类型枚举 / Notification type enumeration
+
+    用于标识事件回调的状态类型。
+    Used to identify the status type of event callbacks.
+
+    Attributes:
+        Unknown: 未知类型 / Unknown type
+        Starting: 开始 / Starting
+        Succeeded: 成功 / Succeeded
+        Failed: 失败 / Failed
+    """
+
+    Unknown = 0
+    Starting = 1
+    Succeeded = 2
+    Failed = 3
+
+
+class EventSink(ABC):
+    """事件监听器基类 / Event sink base class
+
+    用于接收 MaaFramework 各种事件回调的抽象基类。
+    派生类包括 ResourceEventSink、ControllerEventSink、TaskerEventSink、ContextEventSink。
+    Abstract base class for receiving various event callbacks from MaaFramework.
+    Derived classes include ResourceEventSink, ControllerEventSink, TaskerEventSink, ContextEventSink.
+    """
+
+    def on_unknown_notification(self, instance, msg: str, details: dict):
+        """处理未知类型的通知 / Handle unknown notification
+
+        当收到无法识别的通知时调用。
+        Called when an unrecognized notification is received.
+
+        Args:
+            instance: 相关实例对象 / Related instance object
+            msg: 消息类型 / Message type
+            details: 消息详情 / Message details
+        """
+        pass
+
+    def _on_raw_notification(self, handle: ctypes.c_void_p, msg: str, details: dict):
+        pass
+
+    @property
+    def c_callback(self) -> MaaEventCallback:
+        return self._c_sink_agent
+
+    @property
+    def c_callback_arg(self) -> ctypes.c_void_p:
+        return ctypes.c_void_p.from_buffer(ctypes.py_object(self))
+
+    @staticmethod
+    def _gen_c_param(
+        sink: "EventSink",
+    ) -> Tuple[MaaEventCallback, ctypes.c_void_p]:
+        return sink.c_callback, sink.c_callback_arg
+
+    @staticmethod
+    def _notification_type(message: str) -> NotificationType:
+        if message.endswith(".Starting"):
+            return NotificationType.Starting
+        elif message.endswith(".Succeeded"):
+            return NotificationType.Succeeded
+        elif message.endswith(".Failed"):
+            return NotificationType.Failed
+        else:
+            return NotificationType.Unknown
+
+    @staticmethod
+    @MaaEventCallback
+    def _c_sink_agent(
+        handle: ctypes.c_void_p,
+        msg: ctypes.c_char_p,
+        details_json: ctypes.c_char_p,
+        callback_arg: ctypes.c_void_p,
+    ):
+        if not callback_arg:
+            return
+
+        self: EventSink = ctypes.cast(callback_arg, ctypes.py_object).value
+
+        self._on_raw_notification(
+            handle, msg.decode(), json.loads(details_json.decode())
+        )