maa_framework/
lib.rs

1//! # MaaFramework Rust Bindings
2//!
3//! High-performance, safe Rust bindings for [MaaFramework](https://github.com/MaaXYZ/MaaFramework),
4//! a game automation framework based on image recognition.
5//!
6//! ## Quick Start
7//!
8//! ```no_run
9//! use maa_framework::toolkit::Toolkit;
10//! use maa_framework::controller::Controller;
11//! use maa_framework::resource::Resource;
12//! use maa_framework::tasker::Tasker;
13//!
14//! fn main() -> Result<(), Box<dyn std::error::Error>> {
15//!     // 1. Find devices
16//!     let devices = Toolkit::find_adb_devices()?;
17//!     let device = devices.first().expect("No device found");
18//!
19//!     // 2. Create controller
20//!     let controller = Controller::new_adb(
21//!         device.adb_path.to_str().unwrap(),
22//!         &device.address,
23//!         "{}",
24//!         None,
25//!     )?;
26//!
27//!     // 3. Create resource and tasker
28//!     let resource = Resource::new()?;
29//!     let tasker = Tasker::new()?;
30//!
31//!     // 4. Bind and run
32//!     tasker.bind(&resource, &controller)?;
33//!     let job = tasker.post_task("StartTask", "{}")?;
34//!     job.wait();
35//!
36//!     Ok(())
37//! }
38//! ```
39//!
40//! ## Core Modules
41//!
42//! | Module | Description |
43//! |--------|-------------|
44//! | [`tasker`] | Task execution and pipeline management |
45//! | [`resource`] | Resource loading (images, models, pipelines) |
46//! | [`controller`] | Device control (ADB, Win32, PlayCover) |
47//! | [`context`] | Task execution context for custom components |
48//! | [`toolkit`] | Device discovery utilities |
49//! | [`pipeline`] | Pipeline configuration types |
50//! | [`job`] | Asynchronous job management |
51//! | [`event_sink`] | Event sink system for typed callbacks |
52//! | [`buffer`] | Safe data buffers for FFI |
53//! | [`custom`] | Custom recognizer and action traits |
54//! | [`custom_controller`] | Custom controller implementation |
55//! | [`notification`] | Structured event notification parsing |
56//! | [`common`] | Common types and data structures |
57//! | [`error`] | Error types and handling |
58//! | [`util`] | Miscellaneous utility functions |
59//! | [`agent_client`] | Remote custom component client |
60//! | [`agent_server`] | Remote custom component server |
61//!
62//! ## Feature Flags
63//!
64//! - `adb` - ADB controller support (default)
65//! - `win32` - Win32 controller support (Windows only)
66//! - `custom` - Custom recognizer/action/controller support
67//! - `toolkit` - Device discovery utilities
68//! - `image` - Integration with the `image` crate
69
70#![allow(non_upper_case_globals)]
71#![allow(non_camel_case_types)]
72#![allow(non_snake_case)]
73
74pub mod agent_client;
75pub mod agent_server;
76pub mod buffer;
77pub mod callback;
78pub mod common;
79pub mod context;
80pub mod controller;
81pub mod custom;
82pub mod custom_controller;
83pub mod error;
84pub mod event_sink;
85pub mod job;
86pub mod notification;
87pub mod pipeline;
88pub mod resource;
89pub mod sys;
90pub mod tasker;
91pub mod toolkit;
92pub mod util;
93
94pub use common::ControllerFeature;
95pub use common::MaaStatus;
96pub use error::{MaaError, MaaResult};
97
98use std::ffi::CString;
99
100/// Get the MaaFramework version string.
101///
102/// # Example
103/// ```no_run
104/// println!("MaaFramework version: {}", maa_framework::maa_version());
105/// ```
106pub fn maa_version() -> &'static str {
107    unsafe {
108        std::ffi::CStr::from_ptr(sys::MaaVersion())
109            .to_str()
110            .unwrap_or("unknown")
111    }
112}
113
114/// Set a global framework option.
115///
116/// Low-level function for setting global options. Consider using the
117/// convenience wrappers like [`configure_logging`], [`set_debug_mode`], etc.
118pub fn set_global_option(
119    key: sys::MaaGlobalOption,
120    value: *mut std::ffi::c_void,
121    size: u64,
122) -> MaaResult<()> {
123    let ret = unsafe { sys::MaaGlobalSetOption(key, value, size) };
124    common::check_bool(ret)
125}
126
127/// Configure the log output directory.
128///
129/// # Arguments
130/// * `log_dir` - Path to the directory where logs should be stored
131pub fn configure_logging(log_dir: &str) -> MaaResult<()> {
132    let c_dir = CString::new(log_dir)?;
133    set_global_option(
134        sys::MaaGlobalOptionEnum_MaaGlobalOption_LogDir as i32,
135        c_dir.as_ptr() as *mut _,
136        c_dir.as_bytes().len() as u64,
137    )
138}
139
140/// Enable or disable debug mode.
141///
142/// In debug mode:
143/// - Recognition details include raw images and draws
144/// - All tasks are treated as focus tasks and produce callbacks
145///
146/// # Arguments
147/// * `enable` - `true` to enable debug mode
148pub fn set_debug_mode(enable: bool) -> MaaResult<()> {
149    let mut val_bool = if enable { 1u8 } else { 0u8 };
150    set_global_option(
151        sys::MaaGlobalOptionEnum_MaaGlobalOption_DebugMode as i32,
152        &mut val_bool as *mut _ as *mut _,
153        std::mem::size_of::<u8>() as u64,
154    )
155}
156
157/// Set the log level for stdout output.
158///
159/// # Arguments
160/// * `level` - Logging level (use `sys::MaaLoggingLevel*` constants)
161pub fn set_stdout_level(level: sys::MaaLoggingLevel) -> MaaResult<()> {
162    let mut val = level;
163    set_global_option(
164        sys::MaaGlobalOptionEnum_MaaGlobalOption_StdoutLevel as i32,
165        &mut val as *mut _ as *mut _,
166        std::mem::size_of::<sys::MaaLoggingLevel>() as u64,
167    )
168}
169
170/// Enable/disable saving recognition visualizations to log directory.
171pub fn set_save_draw(enable: bool) -> MaaResult<()> {
172    let mut val: u8 = if enable { 1 } else { 0 };
173    set_global_option(
174        sys::MaaGlobalOptionEnum_MaaGlobalOption_SaveDraw as i32,
175        &mut val as *mut _ as *mut _,
176        std::mem::size_of::<u8>() as u64,
177    )
178}
179
180/// Enable/disable saving screenshots on error.
181pub fn set_save_on_error(enable: bool) -> MaaResult<()> {
182    let mut val: u8 = if enable { 1 } else { 0 };
183    set_global_option(
184        sys::MaaGlobalOptionEnum_MaaGlobalOption_SaveOnError as i32,
185        &mut val as *mut _ as *mut _,
186        std::mem::size_of::<u8>() as u64,
187    )
188}
189
190/// Set JPEG quality for saved draw images (0-100, default 85).
191pub fn set_draw_quality(quality: i32) -> MaaResult<()> {
192    let mut val = quality;
193    set_global_option(
194        sys::MaaGlobalOptionEnum_MaaGlobalOption_DrawQuality as i32,
195        &mut val as *mut _ as *mut _,
196        std::mem::size_of::<i32>() as u64,
197    )
198}
199
200/// Set the recognition image cache limit (default 4096).
201pub fn set_reco_image_cache_limit(limit: u64) -> MaaResult<()> {
202    let mut val = limit;
203    set_global_option(
204        sys::MaaGlobalOptionEnum_MaaGlobalOption_RecoImageCacheLimit as i32,
205        &mut val as *mut _ as *mut _,
206        std::mem::size_of::<u64>() as u64,
207    )
208}
209
210/// Load a plugin from the specified path.
211pub fn load_plugin(path: &str) -> MaaResult<()> {
212    let c_path = CString::new(path)?;
213    let ret = unsafe { sys::MaaGlobalLoadPlugin(c_path.as_ptr()) };
214    common::check_bool(ret)
215}
maa_framework/lib.rs

maa_framework/
lib.rs
