Repository navigation
Hooks
A hook is how a C# mod changes Terraria. This page teaches hooks from zero, one idea at a time, with an example for each.
Terraria is made of methods. Item.SetDefaults fills in a new item,
Player.Update runs the player every frame, Lang.GetItemNameValue gives an
item's name. A hook puts you between the game and one of those methods.
Say the game calls Item.SetDefaults(item, 98) to fill in a Minishark. With a
hook installed, the call reaches your code first. You can look at the arguments
and change them, and when you are ready you call orig(item, 98): orig is
the real method, which fills in the item and comes back to you. Now you can
change the result, and when your hook returns, the game carries on with an item
that went through your hands.
Think of it as a receptionist: every call to the method passes through your desk first. You can let it through untouched, change what it carries, answer it yourself, or not let it in at all.
The hook catches every call: from the game, from another mod, from your own code.
On_Item.SetDefaults += (orig, self, type, variant) =>
{
orig(self, type, variant);
self.useTime = 4;
};| Piece | What it is |
|---|---|
On_Item |
The hooks of the Item class. Every game type in BunnyLoader.dll has its On_<Type>: On_Player, On_NPC, On_Main, On_WorldGen, On_Vector2... |
.SetDefaults |
One event per method. Your editor's autocomplete lists them all. |
+= |
Adds your hook. -= removes it. |
orig |
"Do what you would have done": the rest of the chain and, at the end, the game's method. |
self |
The object the method runs on (here, the item). Only exists for instance methods. |
type, variant |
The method's own parameters, in the same order as in the game. |
The parameter names are yours to choose: (orig, item, id, v) works the
same. The order is what counts.
The most common pattern. The game does its work, then you adjust:
// Every weapon hits twice as hard.
On_Item.SetDefaults += (orig, self, type, variant) =>
{
orig(self, type, variant);
if (self.damage > 0) self.damage *= 2;
};// The player never loses life (every frame, refill it).
On_Player.Update += (orig, self, i) =>
{
orig(self, i);
self.statLife = self.statLifeMax2;
};// Every chat message gets a prefix.
On_Main.NewText_string_byte_byte_byte_bool += (orig, text, r, g, b, onlyLocal) =>
orig("[BL] " + text, r, g, b, onlyLocal);When the method returns something, your hook returns it too. You decide what:
// The Minishark gets a new name; every other item keeps its own.
On_Lang.GetItemNameValue += (orig, id) =>
id == ItemID.Minishark ? "Turbo Shark" : orig(id);If you never call orig, the game's method does not run:
// It never starts raining.
On_Main.StartRain += (orig, instant, strength, coinRain) => { };Use this one carefully: whatever the method did (and whatever other mods' hooks after yours did) does not happen.
Main.StartRain, Lang.GetItemNameValue and WorldGen.InWorld are
static: they do not belong to an object. Their hooks go straight from orig
to the parameters, as you saw above.
How do you know? Autocomplete shows the delegate. On_Lang.hook_GetItemNameValue
is (orig, int id) → string?, with no self.
Some methods exist in several versions (overloads). WorldGen.InWorld, for
example:
bool InWorld(int x, int y, int fluff = 0)
bool InWorld(Point p, int fluff = 0)
bool InWorld(Rectangle rect, int fluff = 0)
Each one is a different method, so each one has its own hook. Their names get the parameter types appended:
| Method in the game | Hook |
|---|---|
InWorld(int x, int y, int fluff) |
On_WorldGen.InWorld_int_int_int |
InWorld(Point p, int fluff) |
On_WorldGen.InWorld_Point_int |
Dot(ref Vector2 a, ref Vector2 b, out float r) |
On_Vector2.Dot_refVector2_refVector2_outfloat |
NewText(string, byte, byte, byte, bool) |
On_Main.NewText_string_byte_byte_byte_bool |
SetDefaults(int, ItemVariant) (the only SetDefaults) |
On_Item.SetDefaults |
The rule:
- a method with one version: just its name;
- with several: name +
_+ each parameter's type, withref,outorinin front when it has one. Primitive types use the C# keyword (int,float,bool), other types their short name (Point,Vector2), arrays end inArray.
You rarely need to build the name yourself: type On_WorldGen.InWorld and
the editor shows the options.
tModLoader names some overloads slightly differently (
refInt32instead ofoutint). See the comparison.
A C# property is two methods underneath, and each one can be hooked:
// Player.HandPosition is a property: its getter is get_HandPosition.
On_Player.get_HandPosition += (orig, self) =>
{
var hand = orig(self);
return hand;
};Everything above used lambdas, but a hook can be a normal method. The
delegate types are On_<Type>.orig_<Method> and On_<Type>.hook_<Method>:
public class NoFallDamage : Mod
{
public override void Load()
{
On_Player.Update += KeepFallStart;
}
// Terraria measures a fall from fallStart. Moving it to where the player
// is, every frame, makes every fall zero tiles long.
static void KeepFallStart(On_Player.orig_Update orig, Player self, int i)
{
orig(self, i);
int tileY = (int)(self.position.Y / 16);
self.fallStart = tileY;
self.fallStart2 = tileY;
}
}This is exactly how tModLoader's ExampleMod writes its hooks.
-= needs the same delegate you added, so keep it in a variable:
static On_MathHelper.hook_Clamp? clampHook;
public override void Load()
{
clampHook = (orig, value, min, max) => orig(value, min, max);
On_MathHelper.Clamp += clampHook;
}
void Later()
{
On_MathHelper.Clamp -= clampHook;
}Good to know: the first hook on a method patches the game's code once, and that patch stays until the game closes. After you remove every hook, calls still pass through it and go straight to the game, which costs a little. Hook only what you need (Performance).
Your mod and other mods can all hook Player.Update. They form
a chain: each one's orig is the next one, and the last orig is the
game.
Picture three mods hooking Player.Update. When the game calls the method, the
call reaches the hook that was added last. Its orig leads to the hook added
before it, that one's orig leads to the first hook, and only the first hook's
orig runs the game's own Player.Update.
The hook added last runs first (outermost), as in tModLoader. That is why
calling orig matters: if a hook in the middle skips it, the ones after it
and the game's method do not run.
-
In
Load(): the normal place. It runs once, when the game opens. - Later, in another hook, is allowed too. The first hook on a method takes a moment (it patches the game), so avoid installing them every frame.
- Hooks run on the thread that called the method. Almost everything runs on the game's main thread, but world generation and saving have their own. Keep shared state simple.
| What happens | Result |
|---|---|
| Your hook throws an exception | It goes to the error log (and the error panel). The game method still runs: if your hook had not called orig yet, Bunny Loader calls it for you. The game does not crash. |
The game throws inside orig
|
You receive a GameException with the game's message. Catch it if you want; otherwise it goes to the log like any other. |
// Collision.CanHit with a null entity throws inside the game.
On_Collision.CanHit_Entity_Entity += (orig, source, target) =>
{
try { return orig(source, target); }
catch (GameException e)
{
Logger.Warn($"CanHit failed: {e.Message}");
return false;
}
};| Mistake | What happens | Fix |
|---|---|---|
Forgetting orig
|
The game's method (and every hook after yours) never runs. | Call orig unless skipping is the point. |
Calling orig twice |
The game does the work twice: two items, two hits. | Once. |
Calling the hooked method itself inside its hook (Lang.GetItemNameValue(id) inside On_Lang.GetItemNameValue) |
It passes through your hook again: infinite recursion. | Call orig(id). |
| Heavy work in a hook the game calls hundreds of times per frame | Frame drops. | Filter first (if (type != ...) return), cache, see Performance. |
new Item() |
A null item and a NullReferenceException. |
Item.New(), see guide 4. |
On_T.M += (orig, self, a, b) => { orig(self, a, b); }; // instance, void
On_T.M += (orig, a, b) => orig(a, b); // static, returns
On_T.M += (orig, self, a) => { /* no orig: skips the game */ };
On_T.M_int_float += ...; // an overload
On_T.get_P += (orig, self) => orig(self); // property getter
On_T.M += Handler; static R Handler(On_T.orig_M orig, T self, A a) { ... }
On_T.M -= handler; // remove
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.
