ghook-sdk 0.1.0

Core SDK for the ghook modding framework -- hook manager, mod loader, dependency resolver, and host API
Documentation

game hook

A high-performance, type-safe, native Rust modding framework.

ghook is not just a library; it is a FFI code-generation engine for Aspect-Oriented Programming (AOP) and Dependency Injection (DI) in native Rust applications. It allows game developers to expose stable, typed interfaces for modders while maintaining full control over the host application's lifecycle.

Unlike traditional modding APIs that rely on scripting languages (Lua, Python) or fragile memory scanning, ghook leverages the Rust type system and compile-time metaprogramming to create a bridge between the game and mods that is:

  1. Type-Safe: Mismatches are caught at compile time, not runtime.
  2. Zero-Cost: Hooks use const-hashing and direct FFI calls with no runtime overhead.
  3. Engine-Agnostic: Works with any Rust game (Bevy, Godot-Rust, custom engines) because it relies on language features, not engine specifics.

Key Features

Native Rust AOP & IoC

ghook implements true Inversion of Control. The game defines what can be modified (via #[hookable]), and mods define how it is modified (via #[prefix], #[postfix], #[replace]). This decouples game logic from mod logic completely.

Compile-Time Safety via use_game_hooks!

Mods can read the game's binary metadata at compile time. If the game changes a function signature, the mod fails to build with a clear error message. No more silent crashes due to API drift.

Dependency Resolution & Lifecycle Management

Built-in ModLoader handles:

  • Topological sorting of mod load orders.
  • Detection of circular dependencies and conflicts.
  • Hot-reloading of shared libraries without restarting the game.
  • Panic isolation: A crashing mod is disabled, not the whole game.

Extensible Host API

Games can expose custom APIs (World, UI, Audio) to mods via a type-safe extension registry. Mods request these extensions by name, ensuring loose coupling.

Quick Start

1. Game Side (Host)

Add ghook-sdk and ghook-macros to your Cargo.toml. Mark functions you want to be moddable:

use ghook_sdk::*;
use ghook_macros::hookable;

// This function is now interceptable by any loaded mod
#[hookable]
fn apply_damage(entity_id: u64, amount: f32) -> f32 {
    println!("Applying {} damage to entity {}", amount, entity_id);
    amount
}

fn main() {
    // Initialize the host API and load mods
    let host_api = create_host_api();
    let mut loader = ModLoader::new();
    
    // Loads all .so/.dll files from ./mods, resolves deps, and initializes them
    loader.load_all_mods("./mods", &host_api).expect("Failed to load mods");

    // Call the function as usual. Mods will intercept it automatically.
    let final_damage = apply_damage(101, 50.0);
}

2. Mod Side (Plugin)

Create a cdylib crate. Use declare_args! to match the game's types, or use_game_hooks! for auto-generation.

use ghook_sdk::*;

// Define the data contract manually (or use use_game_hooks! for auto-gen)
declare_args! {
    ApplyDamageArgs { entity_id: u64, amount: f32 }
}

#[mod_info(id = "double_damage_mod", version = "1.0.0")]
#[mod_init]
fn init(api: &HostApi) -> i32 {
    register_double_damage(api);
    api.log_info("Double Damage Mod Loaded!");
    0
}

// Intercept the function BEFORE it runs
#[prefix(target = "apply_damage")]
fn double_damage(args: &mut ApplyDamageArgs) -> HookControl {
    args.amount *= 2.0; // Modify arguments in place
    HookControl::Continue // Let the original function run
}

Documentation

  • SDK Docs: Core API, ModLoader, HostApi.
  • Macros Docs: #[hookable], #[prefix], use_game_hooks!.

🛠️ Why ghook?

Feature Traditional Scripting (Lua/JS) Memory Scanning (Cheat Engine) ghook (Native Rust)
Performance Slow (VM overhead) Fast Native Speed
Safety Runtime Errors Crashes Compile-Time Checks
Stability Breaks on updates Breaks on patches ABI Stable
DX Separate Language Reverse Engineering Pure Rust
Integration Manual Binding Fragile Offsets Declarative Macros

License

Licensed under the Mozilla Public License 2.0.

Author

Semyon Tsarev
GitHub