Crate hudhook

hudhook

This library implements a mechanism for hooking into the render loop of applications and drawing things on screen via dear imgui.

Currently, DirectX9, DirectX 11, DirectX 12 and OpenGL 3 are supported.

For complete, fully fledged examples of usage, check out the following projects:

• darksoulsiii-practice-tool
• eldenring-practice-tool

It is a good idea to refer to these projects for any doubts about the API which aren’t clarified by this documentation, as this project is directly derived from them.

Refer to this post for in-depth information about the architecture of the library.

A tutorial book is also available, with end-to-end examples.

Fair warning

hudhook provides essential, crash-safe features for memory manipulation and UI rendering. It does, alas, contain a hefty amount of FFI and unsafe code which still has to be thoroughly tested, validated and audited for soundness. It should be OK for small projects such as videogame mods, but it may crash your application at this stage.

Examples

Hooking the render loop and drawing things with imgui

Compile your crate with both a cdylib and an executable target. The executable will be very minimal and used to inject the DLL into the target process.

Building the render loop

Implement the render loop trait for your hook target.

Example

Implement the ImguiRenderLoop trait:

// lib.rs
use hudhook::*;

pub struct MyRenderLoop;

impl ImguiRenderLoop for MyRenderLoop {
    fn render(&mut self, ui: &mut imgui::Ui) {
        ui.window("My first render loop")
            .position([0., 0.], imgui::Condition::FirstUseEver)
            .size([320., 200.], imgui::Condition::FirstUseEver)
            .build(|| {
                ui.text("Hello, hello!");
            });
    }
}

{
    // Use this if hooking into a DirectX 9 application.
    use hudhook::hooks::dx9::ImguiDx9Hooks;
    hudhook!(ImguiDx9Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a DirectX 11 application.
    use hudhook::hooks::dx11::ImguiDx11Hooks;
    hudhook!(ImguiDx11Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a DirectX 12 application.
    use hudhook::hooks::dx12::ImguiDx12Hooks;
    hudhook!(ImguiDx12Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a OpenGL 3 application.
    use hudhook::hooks::opengl3::ImguiOpenGl3Hooks;
    hudhook!(ImguiOpenGl3Hooks, MyRenderLoop);
}

Injecting the DLL

You can use the facilities in inject in your binaries to inject the DLL in your target process.

// main.rs
use hudhook::inject::Process;

fn main() {
    let mut cur_exe = std::env::current_exe().unwrap();
    cur_exe.push("..");
    cur_exe.push("libmyhook.dll");

    let cur_dll = cur_exe.canonicalize().unwrap();

    Process::by_name("MyTargetApplication.exe").unwrap().inject(cur_dll).unwrap();
}

Re-exports

pub use imgui;

pub use tracing;

Modules

hooks

Implementations of render engine hooks.

inject

Facilities for injecting compiled DLLs into target processes.

mh

Thin FFI wrapper around minhook.

util

General-purpose utilities. These are used across the crate but have proven useful in client code as well.

Macros

hudhook

Entry point generator for the library.

Structs

Hudhook

Holds all the activated hooks and manages their lifetime.

HudhookBuilder

Builder object for Hudhook.

MessageFilter

Bitflag for specifying types of window message to be filtered.

Traits

Hooks

Generic trait for platform-specific hooks.

ImguiRenderLoop

Implement your imgui rendering logic via this trait.

RenderContext

Texture Loader for ImguiRenderLoop callbacks to load and replace textures

Functions

alloc_console

Allocate a Windows console.

eject

Disable hooks and eject the DLL.

enable_console_colors

Enable console colors if the console is allocated.

free_console

Free the previously allocated Windows console.