Skip to content

README_zh.md

Latest commit

 

History

History
187 lines (145 loc) · 5.21 KB

README_zh.md

File metadata and controls

187 lines (145 loc) · 5.21 KB

LOGO

MaaFramework Rust Binding


English | 简体中文

MaaFramework 的 Rust 绑定，基于图像识别的新一代自动化框架。

✨ 特性

  • Rust 原生体验 - 符合人体工程学的安全封装，依托 Result 错误处理与强类型枚举。
  • 双模链接支持 - 按需选择 静态链接 或 动态加载，自动处理 SDK 路径与 DLL 复制。
  • 全能力覆盖 - 完整支持 Tasker 需要的任务流水线、资源加载、控制器及自定义组件扩展。
  • 零开销 FFI - 基于 bindgen 生成的直接绑定，在享受 Rust 安全性的同时保持 C++ 级性能。

📦 安装

1. 添加依赖

[dependencies]
maa-framework = "1"

2. 下载 SDK

从 MaaFramework Releases 下载：

平台 架构 下载
Windows x86_64 MAA-win-x86_64-*.zip
Windows aarch64 MAA-win-aarch64-*.zip
Linux x86_64 MAA-linux-x86_64-*.zip
Linux aarch64 MAA-linux-aarch64-*.zip
macOS x86_64 MAA-macos-x86_64-*.zip
macOS aarch64 MAA-macos-aarch64-*.zip

3. 解压到项目

my-project/
├── Cargo.toml
├── src/
│   └── main.rs
└── MAA-win-x86_64-v5.4.1/    # 解压的 SDK
    ├── bin/
    ├── lib/
    └── include/

或设置 MAA_SDK_PATH 环境变量。

4. 构建运行

cargo build
cargo run

DLL 会自动复制到 target/debug/ 或 target/release/。

🔗 链接模式

MaaFramework Rust Binding 支持两种链接模式：静态链接 (默认) 和 动态链接。

静态链接 (Static - 默认)

  • 初始化: 自动。无需额外代码。
  • 行为: 操作系统在程序启动时自动加载 DLL。
  • 要求: MaaFramework.dll (或 .so/.dylib) 必须在系统搜索路径中（通常与可执行文件同级）。
  • 用法: 
    [dependencies]
maa-framework = "1"

动态链接 (Dynamic)

  • 初始化: 手动。必须在使用任何 API 之前调用 load_library。
  • 行为: 代码在运行时从指定路径加载 DLL。
  • 要求: 指向 DLL 文件的有效路径。
  • 用法: 
    [dependencies]
maa-framework = { version = "1", features = ["dynamic"] }
    在代码中： 
    // 必须在调用任何其他 API 之前调用
maa_framework::load_library(std::path::Path::new("path/to/MaaFramework.dll"))?;

🚀 快速开始

use maa_framework::toolkit::Toolkit;
use maa_framework::controller::Controller;
use maa_framework::resource::Resource;
use maa_framework::tasker::Tasker;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // [仅动态链接模式] 加载 MaaFramework 库
    #[cfg(feature = "dynamic")]
    maa_framework::load_library(std::path::Path::new("MaaFramework.dll"))?;

    Toolkit::init_option("./", "{}")?;

    let devices = Toolkit::find_adb_devices()?;
    if devices.is_empty() {
        eprintln!("未找到 ADB 设备");
        return Ok(());
    }

    let device = &devices[0];
    let controller = Controller::new_adb(
        device.adb_path.to_str().unwrap(),
        &device.address,
        &device.config.to_string(),
        None,
    )?;
    controller.post_connection()?;

    let resource = Resource::new()?;
    resource.post_bundle("./resource")?;

    let tasker = Tasker::new()?;
    tasker.bind_controller(&controller)?;
    tasker.bind_resource(&resource)?;

    if !tasker.inited() {
        eprintln!("MAA 初始化失败");
        return Ok(());
    }

    tasker.post_task("Startup", "{}")?;
    println!("任务已启动!");

    Ok(())
}

🔧 Features

Feature 描述 默认
toolkit 设备发现工具 ✅
adb ADB 控制器支持 ✅
win32 Win32 控制器 (Windows) ✅
custom 自定义识别器/动作 ✅
image image crate 集成 ❌

📚 文档

📄 License

LGPL-3.0 - 见 LICENSE