Skip to content

About

Struct mapping with pointer chain traversal via derive macros

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

Repository files navigation

procmod-layout

procmod-layout

Struct mapping with pointer chain traversal via derive macros.


Map remote process memory into Rust structs. Declare byte offsets on each field, optionally follow pointer chains through multiple indirections, and read the entire struct in one call. Built on procmod-core.

Install

[dependencies]
procmod-layout = "3"

Quick start

Read a game's player state from a known base address:

use procmod_layout::{GameStruct, Process};

#[derive(GameStruct)]
struct Player {
    #[offset(0x100)]
    health: f32,
    #[offset(0x104)]
    max_health: f32,
    #[offset(0x108)]
    position: [f32; 3],
}

fn main() -> procmod_layout::Result<()> {
    let game = Process::attach(pid)?;
    let player = Player::read(&game, player_base)?;
    println!("hp: {}/{}", player.health, player.max_health);
    println!("pos: {:?}", player.position);
    Ok(())
}

Usage

Basic struct mapping

Every field needs an #[offset(N)] attribute specifying its byte offset from the base address. The derive macro generates a read(process, base) -> Result<Self> method.

use procmod_layout::{GameStruct, Process};

#[derive(GameStruct)]
struct GameSettings {
    #[offset(0x00)]
    difficulty: u32,
    #[offset(0x04)]
    volume: f32,
    #[offset(0x08)]
    fov: f32,
    #[offset(0x10)]
    mouse_sensitivity: f64,
}

Pointer chains

When a value is behind one or more pointer indirections, use #[pointer_chain(...)] to follow the chain automatically. The offsets list the intermediate dereference offsets before reading the final value.

For example, reading a damage multiplier stored behind two pointer hops:

use procmod_layout::{GameStruct, Process};

#[derive(GameStruct)]
struct CombatState {
    #[offset(0x50)]
    is_attacking: u8,
    #[offset(0x54)]
    combo_count: u32,
    #[offset(0x60)]
    #[pointer_chain(0x10, 0x08)]
    damage_mult: f32,
}

// The pointer chain for damage_mult reads:
//   1. read pointer at (base + 0x60)
//   2. read pointer at (ptr + 0x10)
//   3. read f32 at (ptr + 0x08)

Composing with procmod-scan

Use procmod-scan to find a structure's base address after a game update, then read it with a layout:

use procmod_layout::{Address, Capability, GameStruct, Process};
use procmod_scan::Pattern;

#[derive(GameStruct)]
struct Inventory {
    #[offset(0x00)]
    slot_count: u32,
    #[offset(0x04)]
    gold: u32,
    #[offset(0x10)]
    weight: f32,
}

fn find_inventory<C: Capability>(process: &Process<C>, module: &[u8], module_base: Address) -> procmod_layout::Result<Inventory> {
    let sig = Pattern::from_ida("48 8D 0D ? ? ? ? E8 ? ? ? ? 48 8B D8").unwrap();
    let offset = sig.scan_first(module).expect("inventory signature not found");
    let base = module_base.checked_add(offset as u64)?;
    Inventory::read(process, base)
}

Supported types

Every field type must implement AnyBitPattern, meaning any bytes in the target's memory form a valid value. The derive checks this at compile time. bool, char, enums, and references are rejected; read them through their underlying integer type (e.g., u8 for booleans) and convert.

  • Numeric primitives: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
  • Fixed-size arrays: [f32; 3], [u8; 16], etc.
  • Target pointers: Pointer32, Pointer64
  • Your own #[repr(C)] structs that derive AnyBitPattern with bytemuck (bytemuck = { version = "1", features = ["derive"] }), and math types such as glam's that implement it behind a bytemuck feature
use procmod_layout::GameStruct;

#[derive(Clone, Copy, bytemuck::AnyBitPattern)]
#[repr(C)]
struct Vec3 {
    x: f32,
    y: f32,
    z: f32,
}

#[derive(GameStruct)]
struct Enemy {
    #[offset(0x30)]
    position: Vec3,
    #[offset(0x3C)]
    is_aggro: u8,
}

Upgrading from 2.x

See CHANGELOG.md.

License

MIT

About

Struct mapping with pointer chain traversal via derive macros

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages