feat: android native support (#1222)

Co-authored-by: MistEO <mistereo@hotmail.com>

Author: Aliothmoon

.github/workflows/build.yml

@@ -389,6 +389,9 @@ jobs:
               with:
                   ndk-version: r27d
 
+            - name: Export ANDROID_NDK_ROOT
+              run: echo "ANDROID_NDK_ROOT=${{ steps.setup-ndk.outputs.ndk-path }}" >> "$GITHUB_ENV"
+
             - name: Setup ccache
               uses: Chocobo1/setup-ccache-action@v1
               with:
@@ -401,20 +404,29 @@ jobs:
                   python3 tools/maadeps-download.py ${{ matrix.arch == 'x86_64' && 'x64' || 'arm64' }}-android
 
             - name: Build MAA
+              shell: bash
               run: |
-                  cmake --preset 'NinjaMulti' \
-                    -DCMAKE_TOOLCHAIN_FILE=${{ steps.setup-ndk.outputs.ndk-path}}/build/cmake/android.toolchain.cmake \
-                    -DANDROID_ABI=${{ matrix.arch == 'x86_64' && 'x86_64' || 'arm64-v8a' }} \
-                    -DANDROID_PLATFORM=android-23 \
-                    -DMAADEPS_TRIPLET='maa-${{ matrix.arch == 'x86_64' && 'x64' || 'arm64' }}-android' \
+                  if [[ "${{ matrix.arch }}" == "x86_64" ]]; then
+                      preset='NinjaMulti Android x64'
+                  else
+                      preset='NinjaMulti Android arm64'
+                  fi
+
+                  cmake --preset "$preset" \
                     -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}'
 
-                  cmake --build build --preset 'NinjaMulti - ${{ needs.meta.outputs.build-config }}' -j 16
+                  cmake --build --preset "$preset - ${{ needs.meta.outputs.build-config }}" -j 16
 
             - name: Install
               shell: bash
               run: |
-                  cmake --install build --prefix install --config ${{ needs.meta.outputs.build-config }}
+                  if [[ "${{ matrix.arch }}" == "x86_64" ]]; then
+                      build_dir='build/android/x86_64'
+                  else
+                      build_dir='build/android/arm64-v8a'
+                  fi
+
+                  cmake --install "$build_dir" --prefix install --config ${{ needs.meta.outputs.build-config }}
 
                   cp -r docs install
                   cp README*.md install

CMakeLists.txt

@@ -9,6 +9,7 @@ include(source/MaaUtils/MaaUtils.cmake)
 option(WITH_ADB_CONTROLLER "build with adb controller" ON)
 option(WITH_WIN32_CONTROLLER "build with win32 controller" ON)
 option(WITH_MACOS_CONTROLLER "build with macOS controller" ON)
+option(WITH_ANDROID_NATIVE_CONTROLLER "build with Android native controller" ON)
 option(WITH_CUSTOM_CONTROLLER "build with custom controller" ON)
 option(WITH_PLAYCOVER_CONTROLLER "build with PlayCover controller for macOS" ON)
 option(WITH_GAMEPAD_CONTROLLER "build with virtual gamepad controller for Windows" ON)
@@ -52,6 +53,11 @@ if(WITH_MACOS_CONTROLLER AND NOT APPLE)
     set(WITH_MACOS_CONTROLLER OFF)
 endif()
 
+if(WITH_ANDROID_NATIVE_CONTROLLER AND NOT ANDROID)
+    message(STATUS "Not on Android, disable WITH_ANDROID_NATIVE_CONTROLLER")
+    set(WITH_ANDROID_NATIVE_CONTROLLER OFF)
+endif()
+
 if(WITH_GAMEPAD_CONTROLLER AND NOT WIN32)
     message(STATUS "Not on Windows, disable WITH_GAMEPAD_CONTROLLER")
     set(WITH_GAMEPAD_CONTROLLER OFF)

CMakePresets.json

@@ -51,6 +51,37 @@
                 "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/source/MaaUtils/MaaDeps/cmake/maa-arm64-linux-toolchain.cmake"
             }
         },
+        {
+            "name": "NinjaMulti Android",
+            "hidden": true,
+            "inherits": "NinjaMulti",
+            "cacheVariables": {
+                "CMAKE_TOOLCHAIN_FILE": "$env{ANDROID_NDK_ROOT}/build/cmake/android.toolchain.cmake",
+                "ANDROID_PLATFORM": "android-23"
+            }
+        },
+        {
+            "name": "NinjaMulti Android x64",
+            "displayName": "Ninja MultiConfig Android x64",
+            "description": "Ninja MultiConfig Android x64, requires ANDROID_NDK_ROOT",
+            "inherits": "NinjaMulti Android",
+            "binaryDir": "${sourceDir}/build/android/x86_64",
+            "cacheVariables": {
+                "ANDROID_ABI": "x86_64",
+                "MAADEPS_TRIPLET": "maa-x64-android"
+            }
+        },
+        {
+            "name": "NinjaMulti Android arm64",
+            "displayName": "Ninja MultiConfig Android arm64",
+            "description": "Ninja MultiConfig Android arm64, requires ANDROID_NDK_ROOT",
+            "inherits": "NinjaMulti Android",
+            "binaryDir": "${sourceDir}/build/android/arm64-v8a",
+            "cacheVariables": {
+                "ANDROID_ABI": "arm64-v8a",
+                "MAADEPS_TRIPLET": "maa-arm64-android"
+            }
+        },
         {
             "name": "MSVC 2022",
             "displayName": "MSVC 2022",
@@ -153,6 +184,54 @@
             "configuration": "Release",
             "jobs": 16
         },
+        {
+            "name": "NinjaMulti Android x64 - Debug",
+            "displayName": "Ninja MultiConfig Android x64 Debug",
+            "description": "Ninja MultiConfig Android x64 Debug",
+            "configurePreset": "NinjaMulti Android x64",
+            "configuration": "Debug",
+            "jobs": 16
+        },
+        {
+            "name": "NinjaMulti Android x64 - RelWithDebInfo",
+            "displayName": "Ninja MultiConfig Android x64 RelWithDebInfo",
+            "description": "Ninja MultiConfig Android x64 RelWithDebInfo",
+            "configurePreset": "NinjaMulti Android x64",
+            "configuration": "RelWithDebInfo",
+            "jobs": 16
+        },
+        {
+            "name": "NinjaMulti Android x64 - Release",
+            "displayName": "Ninja MultiConfig Android x64 Release",
+            "description": "Ninja MultiConfig Android x64 Release",
+            "configurePreset": "NinjaMulti Android x64",
+            "configuration": "Release",
+            "jobs": 16
+        },
+        {
+            "name": "NinjaMulti Android arm64 - Debug",
+            "displayName": "Ninja MultiConfig Android arm64 Debug",
+            "description": "Ninja MultiConfig Android arm64 Debug",
+            "configurePreset": "NinjaMulti Android arm64",
+            "configuration": "Debug",
+            "jobs": 16
+        },
+        {
+            "name": "NinjaMulti Android arm64 - RelWithDebInfo",
+            "displayName": "Ninja MultiConfig Android arm64 RelWithDebInfo",
+            "description": "Ninja MultiConfig Android arm64 RelWithDebInfo",
+            "configurePreset": "NinjaMulti Android arm64",
+            "configuration": "RelWithDebInfo",
+            "jobs": 16
+        },
+        {
+            "name": "NinjaMulti Android arm64 - Release",
+            "displayName": "Ninja MultiConfig Android arm64 Release",
+            "description": "Ninja MultiConfig Android arm64 Release",
+            "configurePreset": "NinjaMulti Android arm64",
+            "configuration": "Release",
+            "jobs": 16
+        },
         {
             "name": "MSVC 2022 - Debug",
             "displayName": "MSVC 2022 Debug",

docs/en_us/2.2-IntegratedInterfaceOverview.md

@@ -254,6 +254,18 @@ Create Adb controller
 
 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

docs/en_us/2.4-ControlMethods.md

@@ -46,6 +46,29 @@ By default, all methods except `RawByNetcat`, `MinicapDirect`, and `MinicapStrea
 | MinicapStream | `32` | Very Fast | Low | Lossy | |
 | EmulatorExtras | `64` | Very Fast | Low | Lossless | Only supports emulators: MuMu 12, LDPlayer 9, and AVD |
 
+## Android Native
+
+The Android native controller uses `MaaAndroidNativeControlUnit` for direct screenshot and input on Android.
+
+### Android Native Prerequisites
+
+1. Android platform only
+
+### Android Native Configuration
+
+Pass a JSON config to `MaaAndroidNativeControllerCreate(config_json)`:
+
+- `library_path`: Android native control unit library path
+- `screen_resolution.width` / `screen_resolution.height`: raw screenshot resolution, also used as the touch coordinate space
+- `display_id`: target display id, optional, defaults to `0`
+- `force_stop`: whether to force stop before `start_app`, optional, defaults to `false`
+
+> [!NOTE]
+>
+> MaaFramework converts scaled recognition coordinates back to raw screenshot coordinates in `ControllerAgent`.
+> The Android native controller no longer performs any frame-to-touch remapping internally, and only clamps to `screen_resolution`.
+> If the control unit reports a raw frame resolution different from `screen_resolution`, screencap fails immediately.
+
 ## Win32
 
 ### Win32 Input

docs/zh_cn/2.2-集成接口一览.md

@@ -254,6 +254,18 @@
 
 创建 Win32 控制器
 
+### MaaAndroidNativeControllerCreate
+
+- `config_json`: Android Native 控制器配置 JSON，必填字段：
+  - `library_path`: Android Native 控制单元库路径
+  - `screen_resolution.width`: 原始截图宽度，同时也是 touch 坐标宽度
+  - `screen_resolution.height`: 原始截图高度，同时也是 touch 坐标高度
+  - 可选字段：`display_id`（默认 `0`）、`force_stop`（默认 `false`）
+
+创建 Android Native 控制器，用于在 Android 环境下通过 `MaaAndroidNativeControlUnit` 完成原生输入与截图。
+
+> `screen_resolution` 必须与控制单元返回的原始截图分辨率和 touch 坐标系保持一致，否则截图会直接失败。
+
 ### MaaCustomControllerCreate
 
 - `controller`: 自定义控制回调结构体

docs/zh_cn/2.4-控制方式说明.md

@@ -46,6 +46,29 @@
 | MinicapStream | `32` | 极快 | 低 | 有损 | |
 | EmulatorExtras | `64` | 极快 | 低 | 无损 | 仅支持模拟器：MuMu 12、雷电 9、AVD |
 
+## Android Native
+
+Android Native 控制器用于在 Android 环境下通过 `MaaAndroidNativeControlUnit` 直接完成截图和输入。
+
+### Android Native 前置要求
+
+1. 仅支持 Android 平台
+
+### Android Native 配置
+
+通过 `MaaAndroidNativeControllerCreate(config_json)` 传入 JSON 配置：
+
+- `library_path`：Android Native 控制单元库路径
+- `screen_resolution.width` / `screen_resolution.height`：原始截图分辨率，同时也是 touch 坐标系
+- `display_id`：目标显示 ID，可选，默认 `0`
+- `force_stop`：`start_app` 前是否强制停止应用，可选，默认 `false`
+
+> [!NOTE]
+>
+> MaaFramework 会在 `ControllerAgent` 中统一把缩放后的识别坐标换算回原始截图坐标。
+> Android Native 控制器不会再额外做 frame-to-touch 映射，只会按 `screen_resolution` 做边界裁剪。
+> 如果控制单元返回的原始截图分辨率与 `screen_resolution` 不一致，截图会直接失败。
+
 ## Win32
 
 ### Win32 Input

include/MaaControlUnit/AndroidNativeControlUnitAPI.h

@@ -0,0 +1,19 @@
+#pragma once
+
+#include "MaaControlUnit/ControlUnitAPI.h"
+#include "MaaFramework/MaaDef.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    MAA_CONTROL_UNIT_API const char* MaaAndroidNativeControlUnitGetVersion();
+
+    MAA_CONTROL_UNIT_API MaaAndroidNativeControlUnitHandle MaaAndroidNativeControlUnitCreate(const char* config_json);
+
+    MAA_CONTROL_UNIT_API void MaaAndroidNativeControlUnitDestroy(MaaAndroidNativeControlUnitHandle handle);
+
+#ifdef __cplusplus
+}
+#endif

include/MaaControlUnit/ControlUnitAPI.h

@@ -86,6 +86,15 @@ class AdbControlUnitAPI
     virtual bool find_device(/*out*/ std::vector<std::string>& devices) = 0;
 };
 
+class AndroidNativeControlUnitAPI : public ControlUnitAPI
+{
+public:
+    ~AndroidNativeControlUnitAPI() override = default;
+
+    virtual void* attach_thread() const = 0;
+    virtual int detach_thread(void* env) const = 0;
+};
+
 class Win32ControlUnitAPI
     : public ControlUnitAPI
     , public ScrollableUnit
@@ -141,3 +150,4 @@ using MaaCustomControlUnitHandle = MAA_CTRL_UNIT_NS::CustomControlUnitAPI*;
 using MaaReplayControlUnitHandle = MAA_CTRL_UNIT_NS::FullControlUnitAPI*;
 using MaaRecordControlUnitHandle = MAA_CTRL_UNIT_NS::FullControlUnitAPI*;
 using MaaDbgControlUnitHandle = MAA_CTRL_UNIT_NS::ControlUnitAPI*;
+using MaaAndroidNativeControlUnitHandle = MAA_CTRL_UNIT_NS::AndroidNativeControlUnitAPI*;

include/MaaControlUnit/MaaControlUnitAPI.h

@@ -6,6 +6,7 @@
 #include "RecordTypes.h"
 
 #include "AdbControlUnitAPI.h"
+#include "AndroidNativeControlUnitAPI.h"
 #include "CustomControlUnitAPI.h"
 #include "DbgControlUnitAPI.h"
 #include "GamepadControlUnitAPI.h"