feat: android native support

Author: Lemon-miaow

maa-framework/src/common.rs

@@ -308,6 +308,30 @@ bitflags::bitflags! {
 // ADB Controller Methods
 // ============================================================================
 
+/// Raw screen resolution used by Android native control units.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AndroidScreenResolution {
+    /// Raw screenshot width reported by the control unit.
+    pub width: i32,
+    /// Raw screenshot height reported by the control unit.
+    pub height: i32,
+}
+
+/// Configuration for [`crate::controller::Controller::new_android_native`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AndroidNativeControllerConfig {
+    /// Path to the Android native control unit shared library.
+    pub library_path: String,
+    /// Raw screenshot/touch coordinate resolution exposed by the control unit.
+    pub screen_resolution: AndroidScreenResolution,
+    /// Target Android display id. Defaults to `0` when omitted by MaaFramework.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display_id: Option<u32>,
+    /// Whether to force-stop before `start_app`. Defaults to `false` when omitted.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub force_stop: Option<bool>,
+}
+
 bitflags::bitflags! {
     /// ADB screencap method flags.
     ///
@@ -903,3 +927,37 @@ pub struct CustomRecognitionResult {
     pub box_rect: (i32, i32, i32, i32),
     pub detail: serde_json::Value,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{AndroidNativeControllerConfig, AndroidScreenResolution};
+    use serde_json::json;
+
+    #[test]
+    fn android_native_controller_config_serializes_expected_shape() {
+        let config = AndroidNativeControllerConfig {
+            library_path: "/data/local/tmp/libmaa_unit.so".to_string(),
+            screen_resolution: AndroidScreenResolution {
+                width: 1920,
+                height: 1080,
+            },
+            display_id: Some(1),
+            force_stop: Some(true),
+        };
+
+        let value = serde_json::to_value(config).unwrap();
+
+        assert_eq!(
+            value,
+            json!({
+                "library_path": "/data/local/tmp/libmaa_unit.so",
+                "screen_resolution": {
+                    "width": 1920,
+                    "height": 1080
+                },
+                "display_id": 1,
+                "force_stop": true
+            })
+        );
+    }
+}

maa-framework/src/controller.rs

@@ -1,9 +1,12 @@
 //! Device controller for input, screen capture, and app management.
 
 use crate::{MaaError, MaaResult, common, sys};
+use serde::Serialize;
 use std::collections::HashMap;
 use std::ffi::CString;
 use std::os::raw::c_void;
+#[cfg(feature = "dynamic")]
+use std::panic::AssertUnwindSafe;
 use std::ptr::NonNull;
 use std::sync::{Arc, Mutex};
 
@@ -151,6 +154,37 @@ impl Controller {
         Self::from_handle(handle)
     }
 
+    /// 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_android_native<T: Serialize>(config: &T) -> MaaResult<Self> {
+        let config_json = serde_json::to_string(config).map_err(|e| {
+            MaaError::InvalidConfig(format!(
+                "Failed to serialize Android native controller config: {}",
+                e
+            ))
+        })?;
+        let c_config = CString::new(config_json)?;
+
+        #[cfg(feature = "dynamic")]
+        let handle = std::panic::catch_unwind(AssertUnwindSafe(|| unsafe {
+            sys::MaaAndroidNativeControllerCreate(c_config.as_ptr())
+        }))
+        .map_err(|_| {
+            MaaError::InvalidArgument(
+                "Android native controller is not available in this MaaFramework build".to_string(),
+            )
+        })?;
+
+        #[cfg(not(feature = "dynamic"))]
+        let handle = unsafe { sys::MaaAndroidNativeControllerCreate(c_config.as_ptr()) };
+
+        Self::from_handle(handle)
+    }
+
     /// Create a new PlayCover controller for iOS app control on macOS.
 
     pub fn new_playcover(address: &str, uuid: &str) -> MaaResult<Self> {

maa-framework/src/lib.rs

@@ -45,7 +45,7 @@
 //! |--------|-------------|
 //! | [`tasker`] | Task execution and pipeline management |
 //! | [`resource`] | Resource loading (images, models, pipelines) |
-//! | [`controller`] | Device control (ADB, Win32, macOS, PlayCover, WlRoots) |
+//! | [`controller`] | Device control (ADB, Win32, macOS, Android Native, PlayCover, WlRoots) |
 //! | [`context`] | Task execution context for custom components |
 //! | [`toolkit`] | Device discovery utilities |
 //! | [`pipeline`] | Pipeline configuration types |
@@ -92,6 +92,8 @@ pub mod tasker;
 pub mod toolkit;
 pub mod util;
 
+pub use common::AndroidNativeControllerConfig;
+pub use common::AndroidScreenResolution;
 pub use common::ControllerFeature;
 pub use common::MaaStatus;
 pub use error::{MaaError, MaaResult};