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:
- Type-Safe: Mismatches are caught at compile time, not runtime.
- Zero-Cost: Hooks use const-hashing and direct FFI calls with no runtime overhead.
- 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 *;
use hookable;
// This function is now interceptable by any loaded mod
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 *;
// Define the data contract manually (or use use_game_hooks! for auto-gen)
declare_args!
// Intercept the function BEFORE it runs
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