设备连接
设备连接是使用 MaaFramework 功能（截图、OCR、调试等）的前提。MPE 通过 LocalBridge 支持多种设备类型，覆盖 Windows、macOS 和 Linux 三大平台。
支持的设备类型
不同平台支持的控制器类型如下：
| 平台 | 支持的控制器 |
|---|---|
| Windows | ADB、Win32、Gamepad |
| macOS | ADB、macOS、PlayCover |
| Linux | ADB、WlRoots |
提示
连接面板会根据当前操作系统自动显示可用的设备类型，无需手动筛选。
打开连接面板
点击编辑区右上角的连接按钮，展开连接面板。连接面板中可以选择设备类型、配置参数并建立连接。
ADB（Android 设备）
ADB 是最常用的连接方式，适用于 Android 模拟器和真机。
自动扫描
连接面板默认会自动扫描本地 ADB 设备列表，显示已连接的设备供选择。
手动连接
若自动扫描未找到设备，可手动输入连接信息：
- ADB 路径：ADB 可执行文件路径（留空则使用系统 PATH 中的 adb）
- 设备地址：设备的 serial 地址（如
127.0.0.1:5555、emulator-5554）
截图方式
| 方式 | 说明 |
|---|---|
| EncodeToFileAndPull | 编码为文件后拉取（兼容性最好） |
| Encode | 直接编码传输 |
| RawWithGzip | 原始数据 + Gzip 压缩 |
| RawByNetcat | 通过 Netcat 传输原始数据 |
| MinicapDirect | Minicap 直连 |
| MinicapStream | Minicap 流式传输 |
| EmulatorExtras | 模拟器专用加速 |
输入方式
| 方式 | 说明 |
|---|---|
| AdbShell | ADB Shell 输入（兼容性最好） |
| MinitouchAndAdbKey | Minitouch 触控 + ADB 按键 |
| Maatouch | MaaTouch 输入（推荐） |
| EmulatorExtras | 模拟器专用加速 |
提示
大多数情况下使用默认配置即可。若遇到截图黑屏或输入无响应，可尝试切换截图/输入方式。
Win32（Windows 窗口）
Win32 控制器用于连接 Windows 桌面应用程序窗口。
窗口选择
连接面板会列出当前系统中所有可见窗口，选择目标窗口即可连接。列表显示窗口标题和进程名称。
配置参数
- 截图方式：默认 FramePool（帧池截图）
- 输入方式：默认 SendMessageWithCursorPos（发送消息 + 光标定位）
Gamepad（游戏手柄）
Gamepad 控制器支持通过游戏手柄进行输入操作，仅在 Windows 平台可用。
支持的手柄类型
- Xbox360：Xbox 360 兼容手柄
- DualShock4：PlayStation DualShock 4 手柄
配置参数
- hwnd：目标窗口句柄
- 截图方式：与 Win32 相同
- 输入方式：手柄输入映射
PlayCover（macOS iOS 模拟）
PlayCover 控制器用于连接 macOS 上通过 PlayCover 运行的 iOS 应用，仅在 macOS 平台可用。
配置参数
- 地址（Address）：PlayCover 连接地址
- UUID：应用的唯一标识符
- 名称（Name）：应用显示名称
macOS（原生应用）
macOS 控制器用于连接 macOS 原生应用程序，仅在 macOS 平台可用。
配置参数
- PID：目标应用的进程 ID
- 截图方式：默认 ScreenCaptureKit
- 输入方式：GlobalEvent（全局事件）或 PostToPid（发送到进程）
WlRoots（Linux Wayland）
WlRoots 控制器用于连接基于 WlRoots 的 Wayland 合成器，仅在 Linux 平台可用。
配置参数
- Socket 路径：Wayland socket 文件路径
- Win32 VkCode：可选，虚拟键码映射
连接状态
连接成功后，编辑区右上角的连接按钮会变为蓝色，并显示已连接的设备信息。
连接面板中可以：
- 查看当前连接状态
- 断开当前设备
- 切换到其他设备
警告
同一时间只能连接一个设备。切换设备前需要先断开当前连接。
常见问题
ADB 设备列表为空
- 确认模拟器或设备已启动
- 确认 ADB 服务正在运行（终端执行
adb devices检查） - 若使用自定义 ADB 路径，确认路径正确
Win32 窗口列表中找不到目标窗口
- 确认目标应用已启动且窗口可见
- 部分全屏应用可能不在列表中，尝试切换为窗口模式
- 刷新窗口列表
连接后截图黑屏
- 尝试切换截图方式（如从 Encode 切换到 EncodeToFileAndPull）
- 确认设备画面正常显示
- 部分模拟器需要使用 EmulatorExtras 方式