Modding Against IL2CPP

Most Unity games are pleasant to mod. They ship Mono assemblies: real .NET DLLs you can open in a decompiler, reference from your own project, and call as though the game were a library someone published for you.

Sons of the Forest is compiled with IL2CPP. The C# is transpiled to C++ and compiled to a native binary. There is no managed assembly. There is nothing to reference. What survives the transpilation is a single file called global-metadata.dat, a binary blob describing every type, method and field the original C# had, which the runtime uses to bridge native code back to something reflectable.

So you cannot simply call LocalPlayer.Vitals. Something has to reconstruct a managed façade over a native binary first, and every call you make across that boundary reaches into memory the .NET runtime does not own.

Three consequences follow, and between them they shape every file in this project:

• Nothing can be assumed to exist. The menu draws on the title screen, where the player object and everything hanging off it has not been created yet.
• Objects vanish underneath you. A component destroyed between two frames leaves behind a wrapper whose native pointer is dead. Touching it throws.
• A wrong name is a crash, not a compile error, unless you go out of your way to arrange otherwise.

That third one is where the interesting work started.

Before writing a line of the menu, I had to establish what the game actually exposed. The starting point was the metadata file itself.

BepInEx 6's IL2CPP branch reads global-metadata.dat on first launch and generates managed proxy assemblies, one per game assembly, each containing a stub for every type and member the metadata describes. That gives you something to reference. It does not tell you which of those thousands of members are the ones you want, or whether the ones you picked still behave the way their names suggest.

So I parsed the metadata directly and built an index of every type mapped to its methods and fields, then validated that index two ways before trusting it: against a known-good probe that should resolve, and against a fabricated field name that should not. An index that confidently finds a member you invented is an index that will confidently find anything.

With that in hand, every game member the plugin intended to call was resolved against the live build, and not just by name. Names alone miss arity drift: a method that keeps its name across a patch but gains an argument. So the parameter count of every call was compared against the metadata's own parameterCount field.

Verifying once is useful. Verifying on every build is better, and it turned out to be free.

Because the project references those generated interop assemblies directly rather than looking members up by string at runtime, a game member that stops existing breaks the build. If Endnight renames a field in a patch, dotnet build fails with an error naming the exact line. It does not compile happily and then throw two hours into someone's play session.

Which is why every Harmony patch target is written with nameof instead of a string:

[HarmonyPatch(typeof(Vitals), nameof(Vitals.TriggerDeath))]

The string "TriggerDeath" would survive a rename and silently patch nothing at all, the worst failure mode available because everything looks fine. nameof(Vitals.TriggerDeath) cannot survive it.

Here is the daily reality of the second consequence from section one. Every call into the game can throw for reasons that are not bugs: no world loaded yet, a component mid-teardown, a wrapper whose native object was freed a frame ago. You have two honest options: guard every touch, or let the game crash.

My first pass guarded them inline, the obvious way. That produced 117 hand-written try/catch blocks, seventeen of which were completely empty. Seventeen places where a genuine failure disappeared without leaving a trace.

That is not error handling. It is error concealment wearing error handling's clothes, and I had written all of it myself.

The fix was to collapse them into a single guarded seam, one place that decides what gets logged, what gets swallowed, and what is genuinely fatal:

Safe.Get("player.vitals", () => LocalPlayer.Vitals);

Safe.Run("stat.peg", stat, s => s._currentValue = s._max);

Three things about that shape are deliberate.

Every guarded call is named

The site name comes first so each line labels itself. Names are dotted and grouped by subsystem: player.vitals, esp.actor-list, and boot.harmony-patchall. A log line points straight at the code that produced it, and the whole set can be listed with one search.

Noise level is declared, not assumed

A site says whether its failure is transient (a teardown race: report once, then stay quiet), a warning (unexpected but recoverable), or fatal. That middle category matters more than it sounds: the menu ticks every frame while the world simulates underneath, so an unsuppressed warning on a per-frame path emits thousands of lines a minute and buries the one that mattered. Suppression is keyed on the site name, which is precisely why the name is mandatory rather than optional.

Allocation was designed for, not hoped about

A lambda that captures a local variable allocates a closure object every single call. A lambda that captures nothing gets cached once by the compiler into a static field. On a path that runs sixty times a second across five different stats, that difference is real garbage pressure inside a game that is already working hard.

// captures nothing; allocated once, ever
Safe.Run("stat.peg", stat, s => s._currentValue = s._max);

// captures `stat`; a new closure on every frame
Safe.Run("stat.peg", () => stat._currentValue = stat._max);

Both compile. Only the first belongs in a tick. The seam carries state-passing overloads specifically so the hot paths can stay allocation-free without anyone having to remember why.

Only three patches change how the game behaves. Everything else observes. All three landed on the same principle after the naive version failed.

God mode blocks death, it does not out-heal it

The obvious implementation writes health back to maximum every frame. It loses two races: a single hit larger than your entire health bar, and a death triggered before the next tick arrives. Both were reproducible in play; you could still die with god mode on, which rather defeats it.

Blocking the death call outright cannot lose a race, because death never runs. Health pegging stayed, but as a cosmetic nicety rather than the mechanism.

Infinite ammo stops the spend, it does not refill

Same reasoning a layer down. Refilling the magazine every frame means the round is consumed and then replaced, and both the HUD and the weapon's own state machine notice. Suppressing the event the controller raises as the round leaves is the earliest correct point to intervene.

The damage multiplier scales in flight

Rather than letting the hit land and correcting afterwards, the multiplier modifies the value before the original method ever sees it. Every downstream system then observes one consistent number instead of a raw figure followed by a suspicious adjustment.

Thirteen further patches exist, and none of them alter anything. They keep the item-tracking registry synchronised with the world by watching pickup, container and waypoint lifecycles.

The current menu does not manufacture a substitute island or export the game's artwork. It locates the live 4096×4096 Cartography surface already loaded for the handheld GPS and layers travel controls over that game-owned texture.

The difficult part was ownership. Holding an IL2CPP texture wrapper between frames eventually produced an ObjectCollectedException, even when ordinary managed references still appeared valid. The final path caches only stable value metadata, including Unity's integer instance ID, then reacquires and draws the texture inside the same guarded Repaint callback. A narrow tracker-to-surface lookup remains as a fallback. The plugin never copies, destroys, saves, embeds or redistributes the map asset.

The viewport uses the real map aspect ratio and supports FIT, 1X, cursor-anchored wheel zoom and press-drag panning. Current position, saved spots and GPS locations are projected through the same world bounds. Native marker art is used when it is alive; guarded procedural silhouettes cover missing icons without turning every point into an anonymous square.

Labels are normalized from the game's object names, placed in a second collision-aware pass and clustered when the full-island view is too dense. Hover keeps the complete details, and a click travels through the game's own teleport helper instead of performing a blind transform write.

Seeing through walls, honestly

The lazy ESP draws a box on every entry in the actor list and lets you sort it out. This one reads the classification the game already maintains internally, so the Enemies, Animals and Friendly toggles genuinely filter rather than just recolouring the same wall of boxes.

Health bars are assembled from each creature's individual damage regions. Every region with a break threshold contributes its maximum, and applied damage is summed against the total. That tracks real injury per body part instead of one hit-point number.

Avatars across a thread boundary

Steam profile pictures are the only place the mod touches the network, and they sit on an awkward constraint: Unity textures can only be created on the main thread, but a blocking HTTP call on the main thread stalls the frame.

So downloads run on the thread pool and hand raw bytes to a concurrent queue; the per-frame tick drains that queue and does the texture creation where it is legal. Three caches sit behind it: memory, disk, and a negative cache of IDs already known to have nothing stored. Without the third one, every uncached player triggers a filesystem probe on every single frame.

Thirteen categories, flat. It was originally three levels deep: rail, then a chip strip, then sections. Flattening it to one click was the single best usability change made to the thing.

The icons are worth a footnote. All fifty-nine are rasterised in code onto a 48-pixel canvas with coverage sampling, then downsampled. There is nothing to ship or load, and the result is resolution-independent. Colour is baked into each texture rather than tinted at draw time, which is what lets a single 18-pixel icon carry two or three tones and still read.

A write-up that only lists strengths is marketing. These are the real gaps, as of v1.2.0:

• The guarded-seam migration is partial. Thirteen files are converted; nine still use inline try/catch, including the whole UI layer. Forty-one raw try blocks and seven empty catches remain.
• Rapid fire does not restore the original fire rate. The weapon's design value is overwritten while the switch is on, and only reloading the save puts it back.
• World controls require local authority. They work in standalone and for the co-op host. Co-op guests and dedicated-server clients remain read-only and show HOST ONLY; no unfinished server bridge ships in the public client.
• Multiplayer features are client-side. A dedicated server stays authoritative and can overrule them. The rows it can overrule say so.

Windows x64 only. The one-file installer finds the Steam installation, downloads the pinned official BepInEx 6 Unity IL2CPP build, verifies its byte length and SHA-256, and installs the embedded mod as BepInEx/plugins/SonsOfTheDead.dll. BepInEx 5 will not work because it targets Mono.

Press ` in game to open the panel. Rebindable from Settings.