HybridCLR turns the il2cpp runtime into a hybrid one

The problem is that il2cpp freezes the code at build time

Unity has two ways of running your C#. A scripting backend interprets the code at runtime, and il2cpp compiles it ahead of time into native code. The second gives better performance and is required on iOS, and it has one property that dominates the design of any live service game: the code is fixed when the binary is built.

HybridCLR changes that. It extends the il2cpp runtime so that it goes from a pure ahead of time runtime into an AOT plus interpreter hybrid runtime, and from there it natively supports loading assemblies dynamically, which is what makes hot update possible at the bottom level rather than through a patched interpreter.

The project describes the result as a native C# hot update solution for all platforms, and the platform reach is the point. Because the change happens inside the AOT runtime rather than in a scripting backend, a game using it can hot update not only on Android but on iOS, on consoles and on WebGL, in other words on all the platforms il2cpp supports.

The audience is a studio with a shipped game and a live operation. The stated cases are a bug fix that cannot wait for a store review, a configuration change, or a new event that would otherwise need a patch. The project calls this dynamic hotfix, fixing a code bug during execution with the player unaware, and it also supports hot reload, unloading assemblies completely.

The repository in question is the Unity package, the part that drops into a project. The package manifest gives the identity: the package name is `com.code-philosophy.hybridclr`, the version is 9.0.3, the category is Scripting, and the licence is MIT.

Differential Hybrid Execution keeps the untouched code on AOT

This is the most interesting idea in the project and the one that separates it from the other hot update approaches.

The project calls it Differential Hybrid Execution, DHE, and describes it as the ability to add, remove or modify an AOT dll arbitrarily, with the smart part being that unchanged functions continue to run in AOT mode while changed or newly added functions run in interpreter mode. The claim that follows is that the running performance of hot updated game logic basically reaches the level of native AOT.

That is a very different proposition from running everything through the interpreter. A hot update that replaces ten functions should not cost you the performance of the other thousand, and DHE is the mechanism that makes that true. The cost model is per function, and the unchanged functions are the majority in most updates.

The implementation of that idea depends on the rest of the system. To know which functions changed, the runtime has to be able to read the metadata of the modified assembly and compare it against what is already registered, and it has to be able to register new metadata at runtime. Which is why the next section is about metadata.

The feature list also includes support for modern dll encryption, described as a way to protect the code, which is the obvious counter-argument to shipping updated assemblies over a network. How the encryption is implemented is not documented in the repository, so the project documentation is the place to check what is actually protected.

Metadata parsing, dynamic registration and a register based interpreter

The working principle section describes where the design came from and what was built.

The inspiration is mono's mixed mode execution technique. HybridCLR takes the idea and applies it to AOT runtimes such as Unity's il2cpp, adding an interpreter module so the runtime becomes an AOT plus interpreter hybrid.

The list of concrete work items is the most useful part of that section, because it explains why this is a large piece of engineering rather than a small patch.

The first item is an efficient metadata parsing library, for reading the dll files. The second is a modified metadata management module that enables dynamic metadata registration, which is what allows an assembly that did not exist at build time to be introduced at runtime. The third is a compiler from the IL instruction set to a custom register instruction set, and the fourth is a highly efficient register interpreter that executes that custom set. The fifth is a large number of instinct functions, which are hand-written fast paths for common operations, added to raise interpreter performance.

The register machine is the key performance decision. A stack based interpreter, which is what a conventional bytecode interpreter does, needs to push and pop on every operation. A register based one works more like a compiled language, with the operands named in the instruction itself, and it is why the project can claim execution efficiency well ahead of other hot update approaches. The performance and memory reports are linked from the project documentation rather than reproduced here.

On the language coverage side, the project states a near complete implementation of the ECMA-335 specification, with only a very small set of unsupported features, and it notes that some features il2cpp itself does not support are supported here, naming the `__makeref`, `__reftype` and `__refvalue` instructions.

Generics, reflection and hot updated MonoBehaviours

The feature list is where a reader should look for the specific things that separate this from other hot update options, because several of them are described as unsupported elsewhere.

The claim about learning cost is that there is essentially no cost for most developers, that writing code is close to unrestricted, that hot update code works together with AOT code, and that you can write inheritance, generics and reflection freely without writing any special code and without code generation. The second part is the important one. A solution that requires annotating your classes or running a generator over your project has a cost that is paid on every project, and the claim here is that there is none.

The claim about multithreading is stated even more strongly. Full multithreading support, including volatile, ThreadStatic and async Task and related features, and the documentation adds that this is not supported by any other hot update solution. That is a big claim and it is a structural one, since an interpreter that cannot share state safely between threads cannot be used for anything that has a background worker, which is most live service games.

The claim about Unity workflow compatibility is the third. Support for hot updated MonoBehaviour and ScriptableObject, support for DOTS, and the fact that scripts attached to assets can be instantiated correctly, again described as not supported by other hot update solutions. This is the one that determines whether a hot updated script can be dropped onto a prefab in a scene and simply work, and it is the failure mode a studio would hit in the first week.

The project also supports MonoPInvokeCallback, for calling back from native code, which is what allows interaction with native code and with other languages such as lua, javascript or python, and it supports PInvoke for the other direction.

Supported Unity versions and the LeanCLR alternative

The support matrix is stated in one line and is easy to check against a project. The listed Unity versions are 2019.4.x, 2020.3.x, 2021.3.x, 2022.3.x, 2023.2.x and 6000.x.y, all of them LTS releases, and all platforms that il2cpp supports are supported, along with the Tuanjie engine and the HarmonyOS platform.

The official documentation is hosted separately, with an introduction, a quick start page, a business case page and a performance page, and the README links to them. The repository itself does not contain the install commands, so the quick start page is where to start. What the repository does contain is the package, with `Data~/`, `Editor/`, `Plugins/` and `Runtime/` directories and a `RELEASELOG.md` for the change history, which is what a Unity package manager expects to find.

{
    "name": "com.code-philosophy.hybridclr",
    "version": "9.0.3",
    "displayName": "HybridCLR",
    "category": "Scripting",
    "keywords": [
        "HybridCLR",
        "hotupdate",
        "hotfix"
    ]
}

The related project is worth understanding, because the README draws a clear line between the two. HybridCLR is only an interpreter module. If you need a complete, small, open source CLR implementation suitable for shipping to mobile and mini-game platforms, then LeanCLR is described as the most suitable option. It is a lean cross platform CLR that is highly compliant with ECMA-335 while offering a more compact, easy to embed runtime with low memory use, and it natively supports the AOT plus interpreter hybrid mode with built-in IL and IR dual interpreters.

LeanCLR can also be embedded in any app or game and can replace il2cpp as the runtime when publishing a Unity or Tuanjie project to WebGL and mini-game platforms, which the documentation says greatly reduces package size and memory overhead. So the choice is between adding hot update to an existing il2cpp project, and replacing the runtime entirely for a platform where il2cpp was the problem.

Editorial conclusion

HybridCLR suits a Unity studio whose live game needs to ship code changes without going through a store review, especially one already on IL2CPP and shipping to iOS or console where a scripting backend cannot be swapped at runtime. It is the wrong tool for a project that still has the option of choosing a scripting backend rather than a frozen AOT build, and the wrong tool for a project that cannot accept an interpreter in the build at all. Check first the version list, since the package declares support for 2019.4 through 6000.x LTS and the il2cpp platform set, then read the unsupported features page before assuming your C# features are covered.

Frequently asked questions

Official sources

1. focus-creative-games/hybridclr_unity on GitHub
2. Issues
3. License: MIT
4. Project website
5. README