Hook a game's damage calculation to make the player invincible:
use procmod_hook::Hook;
use std::sync::atomic::{AtomicPtr, Ordering};
static TRAMPOLINE: AtomicPtr<u8> = AtomicPtr::new(std::ptr::null_mut());
extern "C" fn damage_detour(entity_id: u32, amount: f32) -> f32 {
if entity_id == 1 {
return 0.0; // player takes no damage
}
let original: extern "C" fn(u32, f32) -> f32 = unsafe {
std::mem::transmute(TRAMPOLINE.load(Ordering::SeqCst))
};
original(entity_id, amount)
}
// target_addr obtained via procmod-scan or manual inspection.
// SAFETY: the game has not started calling this function yet, and the hook
// lives until the mod shuts down after the game loop has stopped
let hook = unsafe {
Hook::install(target_addr as *const u8, damage_detour as *const u8)
}?;
TRAMPOLINE.store(hook.trampoline() as *mut u8, Ordering::SeqCst);
// damage_detour is now called instead of the original functionHook::install(target, detour)- Redirecttargettodetour. Returns a hook with a trampoline to the original.hook.trampoline()- Pointer to the original function's relocated entry point. Transmute it to the original signature to call it.hook.unhook()- Restore the original bytes and page protections, then free the trampoline. If removal fails, the hook stays installed and comes back inside theUnhookErrorso the removal can be retried.
Dropping a hook also removes it. If that removal fails, the hook stays installed and its trampoline is leaked, so a detour that calls it keeps working. To keep a hook for the rest of the process, pass it to std::mem::forget.
- Decode the whole instructions that the jump will overwrite, reading only as far as the target's memory is readable
- Allocate a read-write trampoline within 2GB of the target
- Relocate the stolen instructions into the trampoline, adjusting RIP-relative addressing, and append a jump back into the target
- Make the trampoline read-execute
- Overwrite the target's first bytes with a jump to the detour. Each affected page is made writable while keeping execute permission, then returned to its original protection
- Synchronize instruction caches
Patching is transactional. If any step fails, the original bytes are put back and the page protections restored before the error is returned. Hooks installed by this crate are serialized against each other, and a hook that would overlap an existing one is rejected.
| Platform | Architecture | Status |
|---|---|---|
| Linux | x86_64 | Supported |
| Windows | x86_64 | Supported |
| macOS | x86_64 | Supported |
arm64 support is a future goal. The crate compiles on arm64 but exports no types.
Hook::install is unsafe, and the caller's obligations cover the hook's whole life, including removal by unhook or drop:
targetmust be the first instruction of a function, and its code must stay mapped while the hook exists- The detour must have the same signature and calling convention as the target, and must stay valid while the hook exists
- No code may branch into the overwritten instructions other than to
targetitself - While the hook is being installed or removed, no thread may be executing an instruction that starts within the first 14 bytes of
target. procmod-hook does not suspend threads, so this is up to your own synchronization - The trampoline may only be called while the hook exists. When the hook is removed, no thread may be inside the trampoline or about to call it
- No code outside this crate may modify the patched bytes, or change their page protection, while the hook is being installed or removed
See CHANGELOG.md.
Part of the procmod ecosystem.