Win Auto Utils

中文文档 | English Documentation

A universal Windows automation utility library providing atomic modules for memory operations, window management, input simulation, and color processing. Built with Rust for performance and safety.

🚀 Features

Core Capabilities

• Process Management: Process enumeration, handle aggregation, module snapshot (ToolHelp32)
• Window Operations: Window handle queries, enumeration, manipulation, DC management
• Input Simulation: Keyboard input (Key Down/Up/Press), mouse click & movement
• Screen Capture: High-performance DXGI-based capture, GDI color picking
• Color Processing: Pure Rust pixel color finding algorithms (zero dependencies)
• Memory Operations: Read/write process memory, address resolution, AOB scanning
• Hooking System: Inline hooks, trampoline hooks, register extraction
• Script Engine: Pure Rust interpreter with control flow, timing, keyboard/mouse instructions
• DLL Injection: Cross-architecture injection (x64→x86/x64, WOW64 compatible)
• Template Matching: Image-based UI element detection with parallel processing

Key Advantages

✅ Atomic Design: Enable only what you need via feature flags
✅ Minimal Dependencies: Core features depend only on windows crate
✅ Performance: Release mode with LTO, size optimization, symbol stripping
✅ Safety: Rust's ownership system prevents common memory errors
✅ Cross-platform Script Engine: Pure Rust, no external dependencies

📦 Installation

Add to your Cargo.toml:

[dependencies]

win-auto-utils = { version = "0.2.0", features = ["standard"] }

For full functionality including template matching:

[dependencies]

win-auto-utils = { version = "0.2.0", features = ["full"] }

🎯 Quick Start

Process Management

Only three types needed for full functionality!

use win_auto_utils::process::{Process, ProcessConfig, ProcessManager};

// Method 1: One-step initialization by name (most convenient)
let mut process = Process::init_by_name("notepad.exe")?;
println!("PID: {}", process.pid_or_default());

// Method 2: One-step initialization by PID (when you know the PID)
let process = Process::init_by_pid(12345)?;
println!("HWND: {:?}", process.hwnd_or_default());

// Method 3: Using Builder with intuitive methods (no enums needed!)
let config = ProcessConfig::builder("target.exe")
    .set_window_client_mode()  // Easy to remember - no DCMode enum!
    .exclude_invisible()
    .include_by_title("Game Window")
    .build();
let mut game = Process::new(config);
game.init()?;

// Method 4: Instance method init_with_pid (for existing Process objects)
// Useful for distinguishing multiple instances of the same process
let mut app = Process::by_name("target.exe");
app.init()?;  // Initialize first instance
// Later, switch to specific PID for second instance
app.init_with_pid(20908)?;

// Manager API (simple and straightforward):
let mut manager = ProcessManager::new();
manager.register("notepad.exe")?;  // process name becomes the key
manager.register_alias("game", "target.exe")?;  // custom alias
manager.init("notepad.exe")?;
manager.init_with_pid("game", 12345)?;  // initialize with specific PID

// Query processes (read-only, no mut needed)
if let Some(proc) = manager.get("notepad.exe") {
    println!("PID: {:?}", proc.pid());
}

// DC Mode Options (intuitive method names):
// - .set_window_mode()        -> Standard window DC (GetWindowDC)
// - .set_window_client_mode() -> Client area DC (GetDC) - best for games
// - .set_desktop_mode()       -> Desktop DC for full-screen capture

Memory Operations

use win_auto_utils::memory::{read_memory_t, write_memory_t};

// Read a 32-bit integer
let value: i32 = read_memory_t(handle, address)?;

// Write a float value
write_memory_t::<f32>(handle, address, 999.0)?;

Input Simulation

use win_auto_utils::keyboard::key_press;
use win_auto_utils::mouse::{move_to, left_click};

// Press 'A' key
key_press(handle, 0x41)?;

// Move mouse and click
move_to(handle, 100, 200)?;
left_click(handle)?;

Screen Capture (DXGI)

use win_auto_utils::dxgi::DxgiCapture;

let mut capture = DxgiCapture::new()?;
let image = capture.capture_window(hwnd)?;

Memory Hooking

use win_auto_utils::memory_hook::TrampolineHook;

let shellcode = vec![0x01, 0xD2]; // add edx, edx
let mut hook = TrampolineHook::x86(handle, target_addr, shellcode);
hook.install()?;
// ... trigger hook ...
hook.uninstall()?; // Auto-frees memory

Script Engine

use win_auto_utils::script_engine::ScriptEngine;

let script = r#"
    loop 10
        key VK_SPACE
        sleep 100
    end
"#;

let mut engine = ScriptEngine::new();
engine.execute(script)?;

📚 Documentation

Comprehensive documentation is available in both English and Chinese:

Quick Links

• Documentation Index (EN) - Complete navigation guide
• 文档索引 (中文) - 完整导航指南

Module Documentation

English

• Modules Overview - High-level view of all modules
• Memory Operations
• Memory Hooking
• Address Resolution
• AOB Scanning
• Script Engine
• Input Control
• Process & Window
• Screen Capture
• Template Matching
• DLL Injection

Chinese (中文)

• 模块概览 - 所有模块的高层视图
• 内存操作
• 内存钩子
• 地址解析
• 字节扫描
• 脚本引擎
• 输入控制
• 进程与窗口
• 屏幕捕获
• 模板匹配
• DLL注入

🏗️ Architecture

The library follows a modular architecture with feature-gated components:

win-auto-utils/
├── Process & Window Layer
│   ├── process      - Process management
│   ├── hwnd         - Handle queries
│   ├── window       - Window manipulation
│   └── snapshot     - ToolHelp32 enumeration
│
├── Input Layer
│   ├── keyboard     - Keyboard simulation
│   └── mouse        - Mouse control
│
├── Graphics Layer
│   ├── dxgi         - Screen capture
│   ├── color_picker - GDI color picking
│   └── color_finder - Pixel color search
│
├── Memory Layer
│   ├── memory       - Basic read/write
│   ├── memory_resolver - Symbolic addresses
│   ├── memory_aobscan  - Pattern scanning
│   └── memory_hook     - Inline/trampoline hooks
│
├── Advanced Features
│   ├── dll_injector    - DLL injection
│   └── template_matcher - Image matching
│
└── Script Engine
    ├── script_engine      - Core interpreter
    └── scripts_builtin    - Built-in instructions

🔧 Feature Flags

Choose only what you need:

Minimal Setup (~15s compilation)

cargo build --no-default-features --features "keyboard,mouse"

Core Features (default)

cargo build  # Includes all stable features except template_matcher

Full Features (~45-60s compilation)

cargo build --no-default-features --features "full"

Available Features

See Cargo.toml for complete feature list.

📖 Examples

Explore the examples/ directory for usage demonstrations:

# Run script engine example

cargo run --example script_engine --features "script_engine"


# Run DXGI capture example

cargo run --example dxgi_capture --features "dxgi"


# Run memory hook example

cargo run --example memory_hook_reset --features "memory_hook"


# Run AOB scan benchmark

cargo run --example aobscan_benchmark --features "memory_aobscan"

🧪 Testing

Run tests for specific modules:

# Test script engine

cargo test --features "script_engine"


# Test built-in instructions

cargo test --features "scripts_builtin"


# Test memory operations

cargo test --features "memory"