Repository navigation
CSharp Hook Cost
Measured on MuMu 127.0.0.1:16384 on 2026-10-31, not on a phone yet. MuMu
translates ARM to x86 (houdini): microsecond numbers swing up to 2x between
runs, so every comparison below that matters was made inside one run.
The native C# hook profiler measures them:
-
adb shell setprop debug.bl.cshookprofile 1before the game starts turns it on (the log saysC# hook profiler: on). Off, nothing changes. - Every C# hook installed through the
NativeApigets an assembly link around it and around itsorig(script/dotnet/HookProfileThunks.S,HookProfile.cpp), and so do the per-frame C# callbacks the native content calls (ResourceDraw,NPCEvents,Dust.*,SystemStage,TileEvents,ItemDraw...). Per hook it counts calls, total time and self time: the time in C# without the game's original and without other hooks called inside. Only the game thread is timed. - The profiler's own cost per entry (
bias, 136-162 ns) is measured at the first read and subtracted;clock_gettimecosts 57-67 ns. -
BunnyLoader.HookProfile.Snapshot()reads the table from C#. -
tools/tests/csperfmeasures entering a hook;tools/tests/csperfmodmeasures a world with ExampleModCSharp. Both log frame times, managed allocations (GC.GetAllocatedBytesForCurrentThread;GC.GetTotalAllocatedBytes(false)always returns 0 on Mono) and Mono GCs.
csperf on three game methods, empty hooks that only call the original,
timed by the profiler (the whole C# stub without the original).
| Entry | 1 hook | 3 hooks | hooks removed |
|---|---|---|---|
Isolated, 1/frame (Main.DoUpdate_AnimateCursorColors) |
29.3 µs | 34.2 µs | 26.3 µs |
Right after, 1/frame (Main.DoUpdate_AnimateVisualPlayerAura) |
9.1 µs | 11.5 µs | 10.4 µs |
Burst, 400/frame (WorldItem.UpdateItem) |
1.45 µs | 1.95 µs | 1.47 µs |
| Burst, ms/frame | 0.58 | 0.83 | 0.60 |
- The cost is the transition, not
HookChain: with every hook removed the native stub stays and costs the same. Each extra hook in a chain adds about 0.25 µs. - Cold entries are expensive: the first C# entries of a frame cost 50-120 µs
each (
Main.DoUpdate113-126 µs,Player.Update59-121 µs with trivial bodies).
ExampleModCSharp plus csperfmod (which adds a ModSystem with
all 22 update hooks, empty), two runs. Frame values are averages over 5 s;
DoUpdate runs about twice per drawn frame at these frame rates, so per-frame
call counts of update hooks are about 2x the entity count.
| Idle (run 1 / run 2) | 60 SparklingBall + 15 ExampleCustomAISlimeNPC
|
|
|---|---|---|
| Frame | 32.4 / 35.5 ms | 38.3 / 42.8 ms |
| DoUpdate | 3.0 / 2.8 ms | 5.4 / 5.7 ms |
| DoDraw | 23.2 / 25.7 ms | 21.6 / 24.0 ms |
| C# self time | 17.5 / 20.2 ms | 22.5 / 25.3 ms |
of which ResourceDraw
|
14.2 / 15.9 ms | 13.2 / 14.7 ms |
C# without ResourceDraw
|
3.3 / 4.3 ms | 9.3 / 10.6 ms |
| C# entries per frame | 150 / 161 | 871 / 944 |
| Managed allocation, game thread | 9.4 / 9.8 KB/frame | 20.5 / 22.1 KB/frame |
| Mono GCs in 5 s | 0 / 1 (gen0) | 1 / 1 (gen0) |
The biggest entries with entities:
| Hook | Calls/frame | µs/call | ms/frame |
|---|---|---|---|
(callback) ResourceDraw |
24 | 550-660 | 13.2-14.7 |
Projectile.AI |
134-149 | 13.0 | 1.75-1.95 |
(callback) Dust.update (about 2000 Sparkle dusts) |
2.2-2.5 | 600-650 | 1.35-1.61 |
(callback) NPCEvents |
105-117 | 6.5 | 0.68-0.76 |
Projectile.HandleMovement |
134 | 5.0 | 0.67 |
Projectile.UpdatePosition |
134 | 4.4 | 0.59 |
Main.DrawNPCDirect |
16 | 20 | 0.32 |
Main.DrawProjDirect |
60 | 5.1 | 0.30 |
Projectile.GetAlpha |
60 | 2.7 | 0.16 |
(callback) SystemStage (the ModSystem update stages) |
14-16 | 8-9 | 0.11-0.15 |
A run with the profiler off gave 58 ms (idle) and 48 ms (entities) per frame: MuMu's run-to-run noise is larger than anything the profiler adds, so frame times only compare within a run.
-
ResourceDraw(ModResourceOverlay): 14-16 ms/frame, most of the C# time. Each heart and star draw makes anAsset<Texture2D>withAsset.ForTexture, which calls the nativeAssetOfTexture; that rebuilds the list of every texture asset of the game (content::textureAssets(), thousands of entries) on every call. A texture-to-asset cache would remove almost all of it. - Cold entries: ExampleModCSharp enters C# about 150 times per frame idle,
many of them once per frame and cold (30-120 µs each): about 3-4 ms. Some
run for nothing:
NetMessage.SendDataenters C# about 6 times per frame in singleplayer;Player.GetWeaponDamageMultiplier,RecalculateLuck,SetMatchand otherPlayerhooks run every update. Native filters (only enter when a mod type or flag needs it) and fewer, shared per-frame entries are the lever. - Per projectile, about 22 µs per update spread over
AI,HandleMovement,UpdatePosition,GetAlphaandDrawProjDirect; per NPC event 6.5 µs. Filtering vanilla entities natively and merging the per-projectile hooks would cut most of it. - Allocations of 10-22 KB per frame make a gen0 GC every 5-7 s; the frames with a GC were not slower than the average here. Low priority.
AssetOfTexture now keeps a texture-to-asset map: a hit is checked against
the asset's current texture, a miss scans again at most every 300 updates
for that texture. Asset.ForTexture looks up its wrapper before reading the
asset name. Same scenario, one run:
| Idle | 60 projectiles + 15 NPCs | |
|---|---|---|
ResourceDraw |
13-18 µs/call, 0.3-0.4 ms/frame | 13 µs/call, 0.3 ms/frame |
| C# self time | 4.2 ms/frame (was 17.5-20.2) | 12.7 ms/frame (was 22.5-25.3) |
| DoDraw | 12.6 ms (was 23-26) | 12.2 ms (was 22-24) |
| Managed allocation | 6.6 KB/frame | 17.2 KB/frame |
Items 2 to 4 above are still open.
Samsung Galaxy A15 (SM-A156M), reached through ZeroTier and wireless
debugging; csperf with debug.bl.cshookprofile 1, ExampleModCSharp on,
standing in the world. Four windows of 300 frames:
| Phone | MuMu (above) | |
|---|---|---|
| Frame | 16.7-16.9 ms (60 fps) | |
| DoUpdate / DoDraw | 2.7-3.3 ms / 5.7-6.4 ms | |
| C# self time | 2.07-2.23 ms/frame, ~90 hooks, 209-611 entries/frame | 4.2 ms/frame |
Hot hook entry (WorldItem.UpdateItem, 400/frame) |
0.52-0.60 µs/call | 1.45 µs (burst) |
| Cold hook entry, once per frame | 2.0-6.1 µs/call | 26-34 µs (isolated) |
| Managed allocation | 6.4 KB/frame, one gen0 GC per ~5 s, no frame spike | 6.6 KB/frame |
| Profiler bias / clock | 204 ns / 97 ns |
Entering a hook costs about a third of MuMu's on the phone, where the
emulator's translation is not in the way. The largest single costs are
handlers, not entries: TeleportPylonsSystem.IsPlayerNearAPylon takes
320-330 µs in its one call per frame (0.33 ms/frame, the mod pylon check),
LegacyPlayerRenderer.DrawPlayer_UseNormalLayers 150 µs, the ResourceDraw
callback 24 × 5.6 µs, Lighting.LightTiles 90 µs and Player.UpdateBiomes
65-95 µs.
The mod pylon check scanned the whole 121x123-tile pylon reach once per mod
pylon type every frame, even with no mod pylon in the world. It now looks at
the TEModdedPylon entities first and scans only when one is inside that
region: on MuMu, with ExampleModCSharp, 150-180 µs per frame before and
21-24 µs after (csperf now reports it as a focus hook).
Measured on MuMu 127.0.0.1:16384 with csperfmod and ExampleModCSharp, old
and new BunnyLoader.dll alternating on the same APK (two rounds each,
averages). Without mods nothing changed: only the test's own hooks enter C#.
| Idle, before | Idle, after | 60 projectiles + 15 NPCs, before | after | |
|---|---|---|---|---|
| Frame | 18.3 ms | 17.3 ms | 26.1 ms | 21.2 ms |
| C# self time | 6.62 ms | 4.92 ms | 12.69 ms | 8.56 ms |
| C# entries per frame | 1425 | 521 | 2594 | 1270 |
| Managed allocation | 12.3 KB/frame | 11.0 KB/frame | 20.7 KB/frame | 11.8 KB/frame |
What changed, most expensive first:
-
Main.DrawItementered C# for all 400 item slots every frame (the game calls it for every slot and returns early for inactive ones): 0.71 ms/frame. The world drawing stage now takes its item from a hook onMain.DrawItem_GetBasics, which only runs for items that are drawn. -
WorldItem.UpdateItem(PostUpdate) andPlayer.QuickHeal_GetItemToUse_TryChoosingItem(GetHealLife) entered C# for every slot: 434-624 and 58 entries per frame, 0.45-0.70 and 0.13 ms. They are now gated natively (script/dotnet/HookGate.S,NativeApi.InstallGatedHook): the link reads a field of an argument and goes straight to the next link when it is zero (WorldItem.inner.type,Item.healLife). The gatedUpdateItemlink is installed atContentReady, after the mods'Load, so anOn_WorldItem.UpdateItemadded during load still runs outside it.On_hooks of mods are never gated. After: 0 and 2 entries per frame. -
EntityInstances.Get(everyModItem,ModProjectile,ModNPC,ModPlayerand global lookup) checked the weak handle in native code on every call, a C# to native transition each time. It now checks once per game GC cycle, using the game'sSystem.GC.GetCollectionCount(GC_get_gc_no, a plain read, called without the GC transition). Per call:Projectile.AI13.7 → 8.6 µs,HandleMovement5.6 → 3.3,Damage5.0 → 2.9,UpdatePosition3.4 → 2.2,CutTiles/CanCutTiles3.1 → 1.9,DrawProjDirect4.7 → 2.4,GetAlpha2.5 → 1.7,DrawNPCExtras46 → 31,ResourceDraw7.9 → 5.5. -
HandleMovementallocated aMovementper projectile per update andRefreshInfoAccsa dictionary and one queue per item type per update: both are reused now. That is most of the 8.9 KB/frame less with projectiles. -
Asset<T>.FromGame(everyTextureAssets.X[i]of a game asset array) read the asset name through native field lookups and a new string before looking in its cache: it looks in the cache first. The ExampleMod map layer that draws one icon went from about 34 to 20 µs. - Smaller ones:
ModContent.GetInstance<T>(and soItemType<T>,GetGlobalItem<T>...) reads a static generic cache instead of a lock and a dictionary;Main.ActiveItemsand thePostUpdatecheck readinner.type(whatWorldItem.get_activedoes) instead of calling the getter per slot;ProjectileHooks.WantsandProjectileLoader.HasHooksuse the template instead of binding an instance; no closure per call inBuffHooks.OverandPlayerLoader.All; the interface layer list is reused.
Still open: MapIconOverlay.Draw (about 0.36 ms, almost all of it the game's
own map layers drawn from C# around the mod layers),
DrawPlayer_UseNormalLayers (about 0.27 ms, the vanilla layers called one by
one), Dust.update (the mod's own Lighting.AddLight per dust), and the
remaining per-slot entries that a field check cannot decide
(RefreshInfoAccsFromItemType, 64-75 per frame).
Players reported lag when hosting, and none with the JS engine. Hosting
(netMode 3) runs Main.TrySyncingMyPlayer, which calls Player.clientClone
once per update, and PlayerNetHooks takes a second copy for
ModPlayer.SendClientChanges. Each Player.clientClone calls
Item.clientClone for about 380 items (inventory, armor, dyes, banks,
loadouts). With any GlobalItem loaded, ItemLoader hooked
Item.clientClone to copy the ModItem and GlobalItem instances, so every
one of those copies entered C# and allocated. tModLoader copies only the net
state there (Item.CopyNetStateTo) and forbids Item.Clone inside
Player.clientClone.
Only the copy shown in the player's hand needs the instances:
lastVisualizedSelectedItem, refreshed with clientClone by ItemCheck and
at the end of ItemCheckWrapped. content/items/VisualItemClone.cpp already
watched those calls; it now also covers ItemCheckWrapped and calls C#
(NativeApi.OnVisualItemCopy, ItemLoader.VisualItemCopied) only when the
destination is that copy. ItemLoader no longer hooks Item.clientClone.
tools/tests/csvisualclone checks that the hand copy still follows the held
item's ModItem and GlobalItem (3/3 before and after).
tools/tests/csmpperf measures the host alone, with a client, and with 60
SparklingBall projectiles and 15 ExampleCustomAISlimeNPC; the client
measures its own frames. With ExampleModCSharp, the phone (SM-A156M) hosting
Limite_Petrificado and MuMu joining, old and new BunnyLoader.dll on the
same APK:
| Phone hosting | Alone, before | Alone, after | Client, before | after | Entities, before | after |
|---|---|---|---|---|---|---|
| Frame | 16.6 ms | 16.6 ms | 16.8 ms | 16.7 ms | 33.9 ms | 21.9 ms |
| DoUpdate | 6.9 ms | 4.5 ms | 7.7 ms | 5.1 ms | 11.5 ms | 9.1 ms |
| C# self time | 5.7 ms | 3.5 ms | 6.5 ms | 3.9 ms | 17.9 ms | 9.1 ms |
| C# entries per frame | 1369 | 606 | 1531 | 753 | 4259 | 1958 |
Item.clientClone entries |
761 | 0 | 763 | 0 | 1547 | 0 |
| Managed allocation | 125 KB | 40 KB | 132 KB | 46 KB | 264 KB | 60 KB |
| Mono GCs in 5 s | 9 | 3 | 9 | 4 | 9 | 4 |
The cost fed itself: a slower frame runs more updates per drawn frame, and each update copies the player twice. On MuMu hosting alone the copies took 10.5 ms of the 19.9 ms of C# per frame (1532 entries), with 186 KB allocated per frame and a gen0 GC every 0.8 s; after the change, 553 entries, 14 KB and no GC in 5 s.
NPC.TrySyncingUniqueTownNPCData (hooked when a mod NPC has
ActsLikeTownNPC) entered C# for every NPC on every update. The game only
acts there on a client, and only while needsUniqueInfoUpdate is set: the hook
is now gated on that field, and outside a client it clears the field, so each
NPC enters once.
Still open: with a second player, the host and the client allocate about
46-63 KB per frame against 14-40 KB alone (a gen0 GC every 1-2 s, no frame
spike on the phone), and PlayerNetHooks could compare against
Main.clientPlayer instead of taking its own copy every update.
Measured on MuMu 127.0.0.1:16384, from the tap on Play to startup: title on screen, with the mod already compiled. Old and new BunnyLoader.dll swapped
in place on the same device, in alternating rounds: six boots each with
ExampleModCSharp, four each with a generated mod of 1500 ModItem classes
with one texture file each. Both sets also have csauto. Medians, in seconds.
The phone is further down: there, the opening animation hides most of the gain.
| Stage | ExampleMod before | ExampleMod after | 1500 items before | 1500 items after |
|---|---|---|---|---|
| Game content loaded | 6.6 | 6.5 | 9.8 | 9.4 |
Host.LoadMod, all mods |
19.4 | 8.4 | 51.6 | 10.3 |
Initialize_AlmostEverything and fade |
3.6 | 3.6 | 3.3 | 3.0 |
Native install (tickMod*) |
1.9 | 2.0 | 3.2 | 3.4 |
ContentReady |
4.8 | 2.5 | 1.7 | 1.3 |
| Title on screen | 36.3 | 22.9 | 69.5 | 28.1 |
MuMu drifts: some boots ran 10 to 30 s slower than their neighbours, with the old DLL and with the new one. Medians and the alternating rounds are what make the columns comparable.
With ExampleModCSharp the load thread spends about 80% of its time in the JIT.
JIT time here is self time per method from a Mono profiler callback, starting
at Host.Initialize. It includes class loading done during compilation and
excludes nested compilations. System.Runtime.JitInfo.GetCompilationTime
counts nested compilations twice and reads higher: 10.0 s against the 7.9 s
below.
| JIT, whole boot | Before | After |
|---|---|---|
| Self time | 20.1 s | 7.9 s |
of which On_* hook classes |
10.8 s | 1.4 s |
of which On_* static constructors |
6.6 s | 0 |
| Methods compiled | 10393 | 10787 |
Before, the generated On_Main created the HookChain and the layout array of
all its 1373 methods in one static constructor, 2.1 s for that method alone,
and On_Player 1.2 s. The first touch of an On_* class also loaded a generic
type per hook. A mod uses few of them: ExampleModCSharp installs 372 of the
10626 hooks.
Three changes in the generated code and the load path:
- Each hook now lives in its own nested class (
On_Main.__H12345), loaded on first use. A hook actually installed costs about 4.8 ms of JIT on MuMu. - Method layouts are string literals read only on the first resolve, not
int[]fields filled by each proxy's static constructor. Together with the nested classes this adds about 0.4 MB to the API (30.8 MB to 31.3 MB, built the same way). - Reading the API version no longer loads
System.Reflection.Metadata(360 methods), and the tooltip tag regex is no longerRegexOptions.Compiled(about 200 ms ofDynamicMethodat load).
The rest is real work, and the part that scaled badly was one function.
ItemHooks.Overrides called GetMethods on every question, and registering an
item asks more than 100 of them: 23 ms per ModItem, 20 of them outside the
JIT. That is most of the 41 s the 1500-item column lost. It now builds the set
of overridden names once per type: about 2.3 ms per item, of which 0.3 ms is
JIT.
The 2.1 s step was ItemLootHooks.ContentReady, with 47 ms of JIT. It ran
SetDefaults on every item and reflection per item per GlobalItem, in one
slice. It now skips vanilla items unless a GlobalItem overrides
ModifyItemLoot, and yields after each item. csnpcloot covers that case.
| Before | After | |
|---|---|---|
| Longest step, three boots | 2539 ms (item loot) | 316 ms (ServerSyncHooks.Install) |
| Next longest | 506 ms | 290 ms (BestiaryHooks) |
tickModItems is one block in one frame: 1.9 s for 1564 items on MuMu (1500
plus the 64 reserve items), about 1.2 ms per item, and only 0.2 s more with one
texture file per item than with one shared texture. The duplicate check in
registerModItem is quadratic but does not show up at this size. The screen
holds the flower for those 2 s, so it is not split.
The Calamity pack on the phone is a texture pack and adds no items, so it says nothing about this path. It was not used as load.
Samsung Galaxy A15 (SM-A156M), com.bunnyloader.beta, one mod at a time, without
csauto, already compiled: ExampleModCSharp, then the generated mod of 1500
items. Four boots each, old and new DLL alternating. Medians, in seconds.
| Stage | ExampleMod before | ExampleMod after | 1500 items before | 1500 items after |
|---|---|---|---|---|
| Game content loaded | 3.5 | 3.5 | 3.5 | 3.6 |
Host.LoadMod |
8.3 | 2.5 | 11.3 | 2.5 |
From the end of LoadMod to the end of the splash |
2.9 | 8.4 | 1.7 | 7.7 |
Native install (tickMod*) |
1.0 | 1.0 | 1.4 | 1.5 |
ContentReady |
2.5 | 1.3 | 0.7 | 0.4 |
| Title on screen | 18.1 | 17.0 | 18.6 | 15.8 |
Host.LoadMod is 3.3 to 4.5 times faster, but the title moved by 1.1 s and 2.8 s,
because the game's own splash timer now decides. Mods are ready at about 6 s, and the
screen then waits for the animation to reach its end, at about 15 s. On MuMu
the mods were the slower of the two, so the gain shows there. Cutting the splash
once mods are ready already exists, under Quick start
(config().fastBoot, advanceSplashTimer). Doing it on every boot would remove
most of that 8.4 s wait, but the logo screen stays by decision (2026-11-04).
The longest ContentReady step on the phone is 163 ms. startup: C# compiled
reports about 10700 methods and 3.2 to 3.8 s of JIT.
- 7.9 s of JIT remain on MuMu, 2.9 s of it in the base library, and about 2.5 s
on the phone by the same
JitInfocount at the end ofLoadMod. Only precompiling would remove it: Mono AOT, with the packageMicrosoft.NETCore.App.Runtime.AOT.win-x64.Cross.android-arm6410.0.14. Not tried; it adds a build step and grows the APK. -
Layouts.Verifyruns on every boot, about 0.2 s inStructLayouts..cctor. - The first time a mod compiles on the device costs about 77 s on MuMu on top
of this (332 files, 21294 lines). The title came up at 109 s in that run. On
the Galaxy A15 it costs 12.8 s in the
:compileprocess, before the game opens, and the game then compiles about 10700 methods with the JIT instead of 33700. The time to the title is about the same; what changes is that the errors come first and the game process no longer runs Roslyn.
The log line startup: C# compiled N methods, K KB of IL, T ms of JIT comes at
the end of ContentReady on every boot, phone included. T is the JitInfo
number.
tools/startup/ has the rest:
-
bootrun.sh <out dir> <label> <runs> <uid>...makes cold boots and keeps the logs. On a phone, setDEVICE,BL_PKGandTAP(the Play button:1211 842in landscape,538 2118in portrait; the launcher follows the phone). It needs thecsautopack on the device.table.py <glob>...prints the stages above. -
genmany.py <out dir> [N]writes the pack of many items. -
jitprof.cis the profiler callback, built with the NDK clang into a.so. Copy it tofiles/libjitprof.so, addStartupProfile.csto the API, and callJitStart()inHost.InitializeandJitDump()at the end ofContentReady.jitreport.pyreads thefiles/jitprof.txtit writes.
Measured on the same phone on 2026-11-03: see Migration to C#.
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.
