Game Memory Utils

A Rust library for reading and writing process memory on Linux, designed for easy trainer creation!

Features

• Process Memory Access: Read and write to any process memory using /proc/pid/mem
• Pattern Scanning: Advanced byte pattern matching with wildcard support
• Module Management: Find and work with loaded modules/libraries
• Safe Memory Operations: Type-safe memory operations with error handling
• Ptrace Integration: Automatic process attachment and detachment
• Debug Support: Optional debug output for troubleshooting

Installation

Add to your Cargo.toml:

[dependencies]
game_mem_utils = "0.2.0"

Or use cargo add:

cargo add game_mem_utils

Quick Start

use game_mem_utils::{GameMemUtils, hex};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Attach to a process by name
    let mut mem = GameMemUtils::new("my_game", false)?;

    // Read a u32 value at absolute address
    let gold: u32 = mem.read_at(hex!("8320b84"))?;
    println!("Current gold: {gold}");

    // Write a new value
    mem.write_at(hex!("8320b84"), 999999u32)?;

    // Pattern scanning
    if let Some(addr) = mem.pattern_scan_all_process_memory("48 89 ?? ?? ?? C3")? {
        println!("Pattern found at: 0x{:x}", addr);
    }

    Ok(())
}

Usage Examples

Process Attachment

// Attach by process name
let mut mem = GameMemUtils::new("game_process", false)?;

// Attach by PID
let mut mem = GameMemUtils::from_pid(1234, false)?;

// Enable debug output
let mut mem = GameMemUtils::new("game_process", true)?;

Reading Memory

// Read at absolute address
let value: u32 = mem.read_at(0x12345678)?;

// Read at offset from base address
let value: u32 = mem.read(0x1000)?;

// Read using hex string offset
let value: u32 = mem.read_hex("1000")?;

// Read raw bytes
let bytes = mem.read_bytes(0x12345678, 16)?;

// Read null-terminated string
let text = mem.read_string(0x12345678, 64)?;

// Read specific integer types
let val_u32 = mem.read_u32_le(0x12345678)?;
let val_u64 = mem.read_u64_le(0x12345678)?;

Writing Memory

// Write at absolute address
mem.write_at(0x12345678, 42u32)?;

// Write at offset from base address
mem.write(0x1000, 100i32)?;

// Write using hex string offset
mem.write_hex("1000", 200u32)?;

// Write raw bytes
mem.write_bytes(0x12345678, &[0x41, 0x42, 0x43])?;

// Write specific integer types
mem.write_u32_le(0x12345678, 12345)?;
mem.write_u64_le(0x12345678, 9876543210)?;

Pattern Scanning

// Scan all readable+executable memory regions
if let Some(addr) = mem.pattern_scan_all_process_memory("48 89 ?? ?? ?? C3")? {
    println!("Pattern found at: 0x{:x}", addr);
}

// Scan specific module
if let Some(addr) = mem.pattern_scan_module("game.exe", "89 46 08 ?? C0")? {
    println!("Pattern found in module at: 0x{:x}", addr);
}

// Pattern syntax: hex bytes with ?? for wildcards
// Examples:
// "48 89 E5"           - exact bytes
// "48 ?? E5"           - wildcard in middle
// "?? 89 ?? ?? ?? C3"  - multiple wildcards

Module Management

// Get process and base address info
let pid = mem.pid();
let base_addr = mem.base_address();

// Find module base address
let module_base = mem.find_module_base("libgame.so")?;

// List all loaded modules
let modules = mem.find_loaded_modules()?;
for (name, base, end, permissions) in modules {
    println!("{}: 0x{:x}-0x{:x} ({})", name, base, end, permissions);
}

// Filter modules by regex
let filtered = mem.filter_modules_by_regex(&modules, r".*\.so$")?;

Using the hex! Macro

use game_mem_utils::hex;

// Convert hex strings to u64 at compile time
let address = hex!("8320b84");  // 0x8320b84
let value: u32 = mem.read_at(address)?;

Error Handling

The library uses a comprehensive error system:

use game_mem_utils::MemoryError;

match mem.read_at::<u32>(0x12345678) {
    Ok(value) => println!("Read value: {}", value),
    Err(MemoryError::ProcessNotFound(name)) => {
        eprintln!("Process '{}' not found", name);
    }
    Err(MemoryError::InsufficientPermissions) => {
        eprintln!("Need sudo or appropriate permissions");
    }
    Err(MemoryError::InvalidAddress) => {
        eprintln!("Invalid memory address");
    }
    Err(e) => eprintln!("Other error: {}", e),
}

Debug Mode

Enable debug output to troubleshoot memory operations:

let mut mem = GameMemUtils::new("my_game", true)?; // Enable debug

// Debug output will show:
// - Memory region scanning details
// - Pattern matching progress
// - Ptrace operation results
// - Module loading information

Requirements

• Linux: This library is Linux-specific and uses /proc/pid/mem and ptrace
• Permissions: May require sudo or appropriate capabilities to attach to processes
• Target Process: The target process should be running and accessible

Supported Platforms

• Linux (x86_64, ARM64, and other architectures supported by Rust)
• Wine/Proton games

Safety Notes

• This library directly manipulates process memory, which can cause crashes if used incorrectly
• Always validate addresses and data before writing
• The target process will be temporarily stopped during attachment
• Automatic cleanup ensures processes are properly detached

License

Licensed under the MIT license. See LICENSE for details.

Changelog

0.2.0

• Added comprehensive pattern scanning with wildcard support
• Added debug mode for troubleshooting
• Enhanced error handling and reporting
• Added support for regex-based module filtering
• Process attachment via ptrace

0.1.2

• Initial release with basic memory read/write operations
• Module base address detection