Repository navigation
Under the Hood
You do not need this page to write mods. It explains how C# mods work inside the game, for the curious and for whoever works on Bunny Loader itself.
Three pieces of code share the game's process. There is Terraria itself,
compiled to ARM by Unity's IL2CPP; there is libbunny, Bunny Loader's native
core, which hooks into the game; and there is Mono, the .NET runtime that runs
the C# mods and reaches the game through libbunny.
Terraria Mobile is C# compiled to native ARM code by Unity's IL2CPP: there is no .NET runtime in the game. Bunny Loader brings its own: the official Mono runtime for Android (the one .NET for Android uses), in the same process as the game. It starts with the game, even without C# mods, because the Host screen, the server sync and the config screens run on it.
A generator (app/src/main/csharp/ProxyGen) reads the game's metadata (the
types and signatures that IL2CPP keeps) and writes C# for each game type:
-
Classes (
Player,Item...) become small structs holding the object's address. Each field is a property that reads or writes at the field's offset; each method builds the call and enters the game. -
Structs (
Vector2,Matrix...) become C# structs with the same memory layout as the game's, so they can be passed by value. -
Enums and constants (
ItemID.Minishark) are copied as they are. -
Hooks: one
On_<Type>class with one event per method.
Names are resolved at runtime, by name: field offsets and methods are looked up the first time they are used and cached. A game update that moves a field does not break a mod; only one that renames or removes it does. At startup, the size of every mirrored struct is checked against the game, and a mismatch is logged instead of silently reading the wrong bytes.
The game's methods are native functions with the ARM64 calling convention
(AAPCS64): integers and pointers in registers x0–x7, floats in d0–d7,
small structs split across registers, big structs passed by address, big
returns through x8. The generator decides where each argument goes when
it generates the code, so at runtime a call is: fill a register frame, enter
the game.
Take Vector2.Distance(a, b). The generated proxy puts a.X, a.Y, b.X and
b.Y in the registers d0 to d3, where the game's compiled code expects
them, and calls into libbunny; unless the method is on the fast path, the
runtime first switches the thread out of .NET. libbunny jumps into the game's
method inside its exception guard. The game leaves the result in s0,
libbunny hands it back, and your C# receives 5.0, or a GameException if
the game threw.
The exception guard. A C# exception in IL2CPP is a native C++ exception.
If one crossed the .NET frames on its way up, the process would die. The
guard stops it right at the boundary and hands its message to C#, which
throws a GameException.
The fast path. Normally .NET marks the thread as "outside .NET" during the call, so its garbage collector does not have to wait for it (~130 ns on a phone). For XNA math and property getters, which are short and never call mod code, that step is skipped.
A hook is the same trip in the other direction: this time the game calls into C#, and the steps below take the call from the patched method to your code and back.
- The first
+=on a method patches the game's entry point, through the core's hook chain (the same one the core's own C++ hooks use). - The patch jumps into a generated trampoline: a C# method the native code can call directly, with the exact native signature.
- The trampoline turns registers into typed values (
refparameters become real C# references to the game's variables) and calls your hooks. -
origcalls the next link: another hook or the game. - If your hook throws, the trampoline logs it and makes sure the game's method still ran.
The game has its collector (Boehm, from IL2CPP) and .NET has its own (SGen). Two consequences shape the API:
- They used the same signals to pause threads. Bunny Loader pauses the game's collector while .NET starts, gives the signals back to the game, and runs .NET in cooperative mode, where it never sends them.
-
Neither sees the other's memory. A game object referenced only from a
C# field can be collected by the game. That is what
GameHandleis for. Inside one call or one frame, the object is on the stack, where the game's collector does look, so nothing is needed.
To keep the app small, it ships part of the .NET libraries: the ones a mod commonly uses, plus the ones the compiler of mods with sources needs.
System.Private.CoreLib (the base: strings, collections like List and
Dictionary, Math, Stopwatch, threads, StringBuilder...),
System.Runtime, System.Runtime.Extensions, System.Runtime.InteropServices,
System.Runtime.Loader, System.Runtime.Intrinsics, System.Runtime.Numerics,
System.Collections (and .Concurrent, .Immutable, .NonGeneric,
.Specialized), System.Linq, System.Linq.Expressions, System.Console,
System.Memory, System.Threading (and .Thread, .ThreadPool,
.Channels, .Tasks.Parallel), System.Text.RegularExpressions,
System.Text.Encoding.Extensions, System.Text.Encoding.CodePages,
System.Numerics.Vectors, System.ObjectModel, System.ComponentModel,
System.Security.Cryptography, System.IO.Compression,
System.IO.MemoryMappedFiles, System.Reflection.Metadata,
System.Reflection.Emit, System.Private.Xml and System.Xml.*,
System.Diagnostics.*, System.Private.Uri.
The exact list is assets/dotnet/references.txt in the APK: it is also what a
mod with sources compiles against. A mod that needs another one
(System.Text.Json...) fails to load with FileNotFoundException.
Libraries of your own are fine: a .dll you ship next to your mod's, in
the mod folder (a NuGet package, a shared library of yours) is found when your
code first uses it. It must target .NET 10 or .NET Standard, and its own
dependencies must be there too. In the .csproj,
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> makes
dotnet build copy your NuGet packages into the output.
A mod that ships its sources instead of a .dll (see
Mod structure) is compiled by
BunnyLoader.Compiler (app/src/main/csharp/BunnyLoader.Compiler), a small
library over Roslyn, the C# compiler. The same library runs:
| Where | When | How it starts |
|---|---|---|
| Bunny Loader, before the game | Play, Restart or the BL Editor's Test, when a mod with sources looks out of date |
CompileActivity, in its own :compile process (app/src/main/cpp/compile/CompilerHost.cpp) |
| Bunny Loader, in the game | loading a mod whose bin/ stamp still does not match |
Host.LoadMod, in the game's Mono |
| The catalog app | uploading the package, before publishing | its own Mono (catalog/src/main/cpp/CompilerHost.cpp) |
| A PC |
tools/mods/publish.py and the manager site |
tools/mods/csbuild on the PC's .NET |
Compiling before the game shows the errors with the game still closed: in a
dialog on the launcher, or back in the BL Editor after Test. The launcher decides
by file dates (SourceBuild.looksCurrent), without starting Mono; the compile
in the game stays as the fallback, for a mod that arrives some other way or a
compile process that died.
All of them compile against the same references.txt with the same options,
and Roslyn's deterministic mode makes the output identical, so a stamp
written in one place is valid in the others.
The check costs no compiler: ModBuild.IsCurrent hashes the sources and
reads the stamp, and Roslyn's assemblies are only loaded when something has to
be compiled. The stamp (bin/<Name>.build.json):
{
"format": 1,
"api": "1.0.0.0",
"compiler": "roslyn 5.6.0.0",
"fingerprint": "bd644d18…",
"dll": "e16145d6…"
}api is the version of BunnyLoader.dll; it changes only when the API
breaks, so a normal app update does not make every mod compile again.
fingerprint covers the relative path and the bytes of every source file and
shipped library; dll is the hash of the compiled file.
On Android, .NET's cryptography (the SHA-256 of the stamp, the SHA-1 Roslyn
computes for every strong-named reference) goes through Java: Bunny Loader
loads libSystem.Security.Cryptography.Native.Android.so from Java, so its
JNI_OnLoad runs and finds its Java classes.
- Only the types listed in
ProxyGen/types.txthave members and hooks; the others are handles (see guide 4). - The game's
Asset<T>comes out typed: a field, property, parameter, return value or hook argument of typeAsset<Texture2D>(orAsset<SpriteFont>...) is aReLogic.Content.Asset<T>, the same classModContent.Requestreturns (guide 9), and anAsset<T>[]is anAssetArray<T>(indexer,Length,Resized). A game asset that is not set reads asnull, so compare withnull, as in tModLoader. Inside a mirrored struct, or passed byref, an asset is still a plain handle (GameObject). - Other generic types (
List<T>,Dictionary<TKey, TValue>...) and generic methods (T Get<T>()) are not generated: a generic type is a plain handle. - Game events of the listed types are generated as C# events whose type is
Action<...>orFunc<...>with the proxy types:Main.OnPostDraw += (GameTime time) => ...,Player.Hooks.OnEnterWorld += player => ...,Main.OnResolutionChanged,LanguageManager.OnLanguageChanged... Each subscriber becomes a game delegate (built with the delegate's own constructor, so the game can combine it with others),-=removes it, and an exception inside a handler is logged once and does not stop the other subscribers. An event whose delegate hasref/outparameters, more than sixteen parameters or a large struct return is skipped (skipped.txt). - A game method or constructor that takes one of the game's delegates also has
an overload taking the matching
Action<...>/Func<...>, so a lambda goes straight in:Utils.PlotLine(0, 0, 20, 0, (x, y) => ...). The game delegate stays alive while the game holds it; the ones it drops are cleaned up later. Passingdefaultornullto such a parameter needs a type (default(GUISlider.DrawBackingHandler)), since both overloads take it. - Methods with more than eight
float/doublearguments are skipped. - A struct with a field the generator cannot describe is not mirrored, and methods that use it are skipped.
- Every type and member the generator leaves out is in
app/build/generated/csharp/skipped.txt, one per line with the reason (type X: not found in Assembly-CSharp,Player.Foo: parameter 'bar': ... has no C# mapping,generic methods are not generated yet...).
types.txt lists the types that get members and hooks. A listed type that is
not in the game is skipped (and written to skipped.txt); the build only
fails if none is found, which means the dump is wrong. A nested type can be
written with a dot (Terraria.NPC.Spawner) or a slash (Terraria.NPC/Spawner).
To try new types, write them in a second list and run ProxyGen with both,
with the dump in refs/DummyDll:
dotnet build app/src/main/csharp/ProxyGen/ProxyGen.csproj -c Release
dotnet app/src/main/csharp/ProxyGen/bin/Release/net10.0/ProxyGen.dll --dummy refs/DummyDll --types app/src/main/csharp/ProxyGen/types.txt --types /tmp/new-types.txt --out /tmp/proxiesThen read /tmp/proxies/skipped.txt, move to types.txt the types that
generate, and build BunnyLoader.dll to see that the generated code
compiles. A member whose type is not generated (a type nested in one that is
not listed, a struct without a layout) is left out and written to
skipped.txt as type X is not generated, so the generated code always
compiles; a listed nested type brings the types around it along.
- .NET cannot unload an assembly: a new build of your mod needs a game restart.
| Part | Path |
|---|---|
| The runtime host (start, load mods, signals) | app/src/main/cpp/script/dotnet/DotnetHost.cpp |
| The calls into the game and the guard | app/src/main/cpp/script/dotnet/DotnetCall.cpp |
| What C# can ask the native side | app/src/main/cpp/script/dotnet/NativeApi.cpp |
| The C# runtime library | app/src/main/csharp/BunnyLoader/ |
| The generator | app/src/main/csharp/ProxyGen/ |
| The compiler of mods with sources | app/src/main/csharp/BunnyLoader.Compiler/ |
| The compiler in the catalog app |
catalog/src/main/cpp/CompilerHost.cpp, CompilerRuntime.kt, CSharpBuild.kt
|
| The compiler on a PC |
tools/mods/csbuild/, tools/mods/csharp_build.py
|
| Tests and benchmarks |
tools/tests/hookcs, benchcs, cssource, compilebench, csitems, csload, csassets, csmodtarget, csmodref, cssourceref, csloc, csinstances, csglobals, cssave, csnet, csuse, csheal, cspickup, csdraw, csopen, csnetitem, cstooltip, csrarity, csprefix
|
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.
