Repository navigation
Native Hooks
Part of the core documentation (overview). To use hooks in a mod, see guide 2. This page covers what happens between the game calling a method and a mod's hook running.
A hook is a detour. Every call to a game method first goes through a function of ours, which decides what to do: call the original, change the arguments, swap the return value or not let the original run.
In Terraria Mobile, the game's C# was compiled to ARM64 before it reached
the phone (IL2CPP turns C# into C++ and compiles everything, AOT). There is no
virtual machine to swap a method through reflection, and no pointer table to
redirect. A method is just a stretch of machine code inside libil2cpp.so,
and the code that calls it jumps straight to its address.
That is why the hook is inline: we rewrite the method's own first instructions with a jump to our function. Any caller, from anywhere, enters through the start of the method and lands in the detour. The rewritten instructions go into a trampoline, which runs them and continues to the rest of the method. The trampoline is the "original".
So a caller in the game jumps to Player.Update as always. The rewritten
prologue sends it to Bunny Loader's function, and when that function calls
original(), the trampoline runs the instructions that were rewritten and
continues with the rest of Player.Update.
There are three layers, each with a job:
| Layer | File | What it does |
|---|---|---|
| ShadowHook | external library (via Gradle) | Rewrites the prologue and builds the trampoline. |
HookManager |
hook/HookManager.cpp |
Allows several hooks on the same method, chained. |
| The C# trampoline | generated in BunnyLoader.dll (On_<Type>), installed through NativeApi
|
Turns the native call into typed C# values, runs the mods' hooks, and back. |
ShadowHook (ByteDance) does
the low-level work: it figures out how many instructions it needs to move,
fixes the position-dependent ones (relative jumps, adrp), builds the
trampoline and swaps the prologue safely with other threads running.
We ask for a hook in two ways:
-
by address (
shadowhook_hook_func_addr), for game methods: the address comes from theMethodInfoIL2CPP gives us (methodPointer). It is the path for every mod hook, and it also works on MuMu, which runs ARM translated to x86; -
by symbol name (
shadowhook_hook_sym_name), only foril2cpp_initduring boot (see the README).
ShadowHook runs in UNIQUE mode: an address accepts one replacement. A
second request on the same method would be refused. That is where layer 2
comes in.
The Packages tab lets you move mods up and down with the arrows before the
icon or by holding and dragging the card. At the edges, the list scrolls to
reach the other mods. Dragging saves on release; cancelling keeps the order.
These controls show up under All + Load order. The enablement filters
and the size or A–Z sorts only change the display. That order is saved and is
the same one sent to the core for loading; disabled mods keep their position
and new packages go at the end. With no order chosen, ascending uid applies.
Hooks registered during loading follow that sequence; a hook registered in a
later phase goes after the ones already installed.
Two mods want to hook Player.Update. ShadowHook accepts only one.
HookManager solves this by chaining: the second hook becomes the first one's
"original", and the second one's original is the real function.
When the game calls Player.Update, the call enters mod A's hook. Its
original() leads to mod B's hook, B's leads to C's, and C's original() runs
the real Player.Update.
- The first one installed is the outermost: it sees the call before
everyone, and whatever it passes to
original()is what the second one receives. - Adding a new link means swapping one pointer: the last link's
originalstarts pointing to the new one, and the new one points where the last one used to. Nothing is uninstalled, and no trampoline is freed while another thread might be inside it. - The swap is atomic (
__atomic_store_nwith release), and whoever calls the original reads the pointer atomically on every call. That is why the code never keeps a copy oforiginal(see the warning inHookManager.h).
Every method IL2CPP generates receives, as its last argument, its own
const MethodInfo*. A replacement function written in C++ has to declare that
extra parameter:
using DoUpdateFn = void (*)(Il2CppObject* self, Il2CppObject* gameTime, const MethodInfo*);
DoUpdateFn g_origDoUpdate = nullptr;
void hkDoUpdate(Il2CppObject* self, Il2CppObject* gt, const MethodInfo* m) {
// ... Bunny Loader's work, on the game thread ...
g_origDoUpdate(self, gt, m);
}
hook::install(doUpdateMethod, hkDoUpdate, &g_origDoUpdate);That is how the core itself hooks the game:
Main.DoUpdate (Bunny Loader's "tick", see content),
Lang.GetItemName, saving mod items and others.
For every hookable game method, ProxyGen generates an [UnmanagedCallersOnly]
C# method with the method's exact native signature: the trampoline. The
first += on On_Player.Update installs it through the native table:
On_Player.Update += hook
-> HookChain.Add: first hook on this method?
-> NativeApi.InstallHook(method, &trampoline)
-> hook::install(method, trampoline, slot) (HookManager, layer 2)
<- slot: where the "original" pointer lives
installHook gives back the address of the original pointer, not its
value. The trampoline reads it on every call, so a link added later by the
core or by another hook keeps the chain intact (the rule of layer 2).
On a call:
- The game jumps into the trampoline with its registers. The arguments
arrive already typed (a
Player, anint, arefthat is a real C# reference to the game's variable), because the trampoline's signature is the native one. - If the core is not ready yet (
HookGate: the mods are still loading on another thread), the trampoline calls the original and returns. Hooks installed during loading start running only aftermarkCoreReady. - Otherwise it calls
HookChain.Chain: the mods' hooks composed into one delegate, the last one added on the outside, whose innermostorigis the native original. - An exception in a hook is logged with the method's name; if the original had not run yet, it runs now, so the game's state stays consistent.
- The return value goes back in the right register (
x0,s0,d0, a register pair, or the memoryx8points to for large structs).
Removing every hook empties the chain but leaves the trampoline installed: calls keep passing through it and go straight to the original.
The C# loaders install their hooks the same way. For hot game methods (an
NPC's AI, a tile's per-frame calls), the native core adds stages and
filters in C++ (content/*) that only call into C# for mod types, so a
vanilla NPC does not pay for the crossing.
-
Mods, with
On_<Type>.<Method> += .... -
The C# loaders (
ItemLoader,NPCLoader...), inTerraria/ModLoader/Core/. Most game methods behind a content hook are only hooked when some registered class overrides that hook. -
The core itself, in C++, with
hook::install: the tick onMain.DoUpdate, the type limits, the saves, the native stages.
Not every game limit sits in a method that can be hooked.
if (type >= NPCID.Count) return; becomes cmp w8, #696 right in the
instruction. For those cases, hook/CodePatch.cpp
finds the method by name, looks for the exact pattern (the comparison and
the conditional branch after it) and swaps only the number. If the pattern does
not match (another game version), nothing is written and the log says why. See
content.
Bunny Loader wiki ·
Discord ·
Repository ·
BL Editor
Written for Bunny Loader 0.5.5-beta and Terraria Mobile 1.4.5.8.6.
Bunny Loader is not affiliated with Re-Logic or 505 Games.
