2.4 控制方式说明
本文档详细说明 MaaFramework 中 Screencap（截图）和 Input（控制）的各种方式及其配置。
TIP
- 对于 API ，screencap/input 使用
int类型（按位或组合）；对于 ProjectInterface V2，使用string类型（直接使用名称）。 - ProjectInterface V2 仅支持配置 Win32 控制器的 screencap/mouse/keyboard 方式。Adb 控制器的 screencap/input 使用
MaaToolkitAdbDeviceFind自动检测和选择最优方式，无需手动配置。
Adb
Adb Input
参考 MaaDef.h
将下面选择的方式 按位或 合并为一个值提供。MaaFramework 将会按照固定优先级顺序尝试所有提供的方式，选择首个可用方式。
默认尝试除 EmulatorExtras 外所有方式。
优先级: EmulatorExtras > Maatouch > MinitouchAndAdbKey > AdbShell
| 名称 | API 值 | 速度 | 兼容性 | 说明 |
|---|---|---|---|---|
| AdbShell | 1 | 慢 | 高 | |
| MinitouchAndAdbKey | 2 | 快 | 中 | 按键仍使用 AdbShell |
| Maatouch | 4 | 快 | 中 | |
| EmulatorExtras | 8 | 快 | 低 | 仅支持模拟器：MuMu 12 |
Adb Screencap
参考 MaaDef.h
将下面选择的方式 按位或 合并为一个值提供。MaaFramework 将会尝试所有提供的方式，选择最快的可用方式。
默认尝试除 RawByNetcat，MinicapDirect，MinicapStream 外所有方式。
MinicapDirect 和 MinicapStream 由于会编码为 jpg，为有损编码，将显著降低模板匹配的效果，不建议使用。
| 名称 | API 值 | 速度 | 兼容性 | 编码 | 说明 |
|---|---|---|---|---|---|
| EncodeToFileAndPull | 1 | 慢 | 高 | 无损 | |
| Encode | 2 | 慢 | 高 | 无损 | |
| RawWithGzip | 4 | 中 | 高 | 无损 | |
| RawByNetcat | 8 | 快 | 低 | 无损 | |
| MinicapDirect | 16 | 快 | 低 | 有损 | |
| MinicapStream | 32 | 极快 | 低 | 有损 | |
| EmulatorExtras | 64 | 极快 | 低 | 无损 | 仅支持模拟器：MuMu 12、雷电 9、AVD |
Win32
Win32 Input
参考 MaaDef.h
选择下面的值提供。
无默认值。Client 可以选择一个作为默认值。
Win32 下不同程序处理输入的方法不同，不存在一个通用方式。
| 名称 | API 值 | 兼容性 | 需管理员权限 | 抢占鼠标 | 支持后台 | 说明 |
|---|---|---|---|---|---|---|
| Seize | 1 | 高 | 否 | 是 | 否 | |
| SendMessage | 2 | 中 | 可能 | 否 | 是 | |
| PostMessage | 4 | 中 | 可能 | 否 | 是 | |
| LegacyEvent | 8 | 低 | 否 | 是 | 否 | |
| PostThreadMessage | 16 | 低 | 可能 | 否 | 是 | 已废弃 |
| SendMessageWithCursorPos | 32 | 中 | 可能 | 短暂 | 是 | 短暂移动光标到目标位置后恢复，专为检测实际鼠标位置的程序设计 |
| PostMessageWithCursorPos | 64 | 中 | 可能 | 短暂 | 是 | 短暂移动光标到目标位置后恢复，专为检测实际鼠标位置的程序设计 |
| SendMessageWithWindowPos | 128 | 中 | 可能 | 否 | 是 | 短暂移动窗口使目标位置与光标重合后恢复，不抢占鼠标 |
| PostMessageWithWindowPos | 256 | 中 | 可能 | 否 | 是 | 短暂移动窗口使目标位置与光标重合后恢复，不抢占鼠标 |
NOTE
- 管理员权限主要取决于目标程序的权限级别，若目标程序为管理员权限，则需以管理员权限运行以保证兼容性。
WithCursorPos系列方式会短暂移动光标到目标位置，发送完消息后会将光标移回原位置，因此会“短暂”抢占鼠标，但不会阻止用户操作。WithWindowPos系列方式会短暂移动窗口，使目标位置与当前光标位置重合，发送完消息后会将窗口移回原位置。不会移动光标，因此不抢占鼠标，但窗口会短暂闪烁。
Win32 Screencap
参考 MaaDef.h
将下面选择的方式 按位或 合并为一个值提供。MaaFramework 将会尝试所有提供的方式，选择最快的可用方式。
无默认值。Client 可以选择一个组合作为默认值。
Win32 下不同程序处理绘制的方法不同，不存在一个通用方式。
| 名称 | API 值 | 速度 | 兼容性 | 需管理员权限 | 支持后台 | 说明 |
|---|---|---|---|---|---|---|
| GDI | 1 | 快 | 中 | 否 | 否 | |
| FramePool | 2 | 极快 | 中 | 否 | 是 | Windows 10 1903+ 可用 |
| DXGI_DesktopDup | 4 | 极快 | 低 | 否 | 否 | 桌面复制（全屏输出复制） |
| DXGI_DesktopDup_Window | 8 | 极快 | 低 | 否 | 否 | 桌面复制后裁剪 |
| PrintWindow | 16 | 中 | 中 | 否 | 是 | |
| ScreenDC | 32 | 快 | 高 | 否 | 否 |
NOTE
提供了三个组合宏便于直接使用：
MaaWin32ScreencapMethod_All：所有截图方式MaaWin32ScreencapMethod_Foreground：DXGI_DesktopDup_Window | ScreenDCMaaWin32ScreencapMethod_Background：FramePool | PrintWindow
FramePool 和 PrintWindow 内置了伪最小化支持：当目标窗口被最小化时，会将窗口设为透明并开启点击穿透，以不激活的方式恢复窗口，从而在不打扰用户的情况下继续截图。
其他截图方式在窗口最小化后无法获取有效内容，请避免窗口最小化。
PlayCover (macOS)
PlayCover 控制器用于在 macOS 上控制通过 fork版PlayCover 运行的 iOS 应用程序。
PlayCover 前置要求
- 在 macOS 上安装 fork版PlayCover
- 目标 iOS 应用需要在 PlayCover 中启用 MaaTools 功能
Gamepad (Windows)
Gamepad 控制器用于在 Windows 上模拟 Xbox 360 或 DualShock 4 手柄输入，适用于需要手柄控制的游戏。
Gamepad 前置要求
需要安装 ViGEm Bus Driver。
手柄类型
| 类型 | API 值 | 说明 |
|---|---|---|
| Xbox360 | 0 | Microsoft Xbox 360 Controller (有线) |
| DualShock4 | 1 | Sony DualShock 4 Controller (有线) |
操作映射
Gamepad 控制器使用以下映射方式：
数字按键 (click_key/key_down/key_up)
使用 MaaGamepadButton_* 常量作为按键值。Xbox 按键值用于 Xbox360 手柄，DS4 面板按键自动映射到 Xbox 等效按键：
| 按键 | API 值 | Xbox 360 | DualShock 4 等效 |
|---|---|---|---|
| DPAD_UP | 1 | 十字键 上 | 十字键 上 |
| DPAD_DOWN | 2 | 十字键 下 | 十字键 下 |
| DPAD_LEFT | 4 | 十字键 左 | 十字键 左 |
| DPAD_RIGHT | 8 | 十字键 右 | 十字键 右 |
| START / OPTIONS | 16 | Start | Options |
| BACK / SHARE | 32 | Back | Share |
| LEFT_THUMB / L3 | 64 | 左摇杆按下 | L3 |
| RIGHT_THUMB / R3 | 128 | 右摇杆按下 | R3 |
| LB / L1 | 256 | LB | L1 |
| RB / R1 | 512 | RB | R1 |
| GUIDE | 1024 | Xbox Guide | - |
| A / CROSS | 4096 | A | ✗ (Cross) |
| B / CIRCLE | 8192 | B | ○ (Circle) |
| X / SQUARE | 16384 | X | □ (Square) |
| Y / TRIANGLE | 32768 | Y | △ (Triangle) |
| PS | 65536 | - | PS (仅 DS4) |
| TOUCHPAD | 131072 | - | 触摸板按下 (仅 DS4) |
模拟输入 (touch_down/touch_move/touch_up)
使用 contact 参数选择控制目标：
| Contact | 说明 | x/y 范围 | pressure 范围 |
|---|---|---|---|
| 0 | 左摇杆 | -32768 ~ 32767 | 忽略 |
| 1 | 右摇杆 | -32768 ~ 32767 | 忽略 |
| 2 | 左扳机 (LT/L2) | 忽略 | 0 ~ 255 |
| 3 | 右扳机 (RT/R2) | 忽略 | 0 ~ 255 |
NOTE
- 需要安装 ViGEm Bus Driver 才能使用此控制器。
WlRoots (Linux)
WlRoots 控制器用于在 Linux 上控制在专用 wlroots 合成器中运行的应用程序。
合成器前置要求
待控制的 wlroots 合成器必须支持以下协议：
- Wayland 核心协议
virtual-keyboard-unstable-v1wlr-screencopy-unstable-v1wlr-virtual-pointer-unstable-v1
NOTE
建议启动一个嵌套合成器会话以使用该控制器。不建议控制当前桌面所使用的合成器，这可能会在任务执行过程中产生意外行为。