HybridCLR: native C# hot update for Unity's IL2CPP runtime
HybridCLR是一个特性完整、零成本、高性能、低内存的Unity全平台原生c#热更新解决方案。 HybridCLR is a fully featured, zero-cost, high-performance, low-memory solution for Unity's all-platform native c# hotupdate.
At a glance
- What is it?
- HybridCLR turns Unity's IL2CPP AOT runtime into an AOT plus interpreter hybrid so assemblies can be loaded at runtime. It is aimed at teams shipping C# hot updates on iOS, Android, consoles and WebGL.
- Who is it for?
- Adopt HybridCLR if you ship Unity games on IL2CPP targets and need C# hot updates without rewriting gameplay in Lua or TypeScript. Do not adopt it if your project is small enough that a full rebuild per release is acceptable, or if you cannot accept that the interpreter path, not the AOT path, runs your changed code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What HybridCLR solves for Unity teams on IL2CPP
Unity's IL2CPP backend compiles C# ahead of time. That is good for startup and steady-state performance, and it is the only way to ship to iOS, consoles and WebGL. It also means the set of types in the build is fixed at build time. Shipping a gameplay fix therefore means shipping a new binary and waiting for store review.
HybridCLR's answer is to keep IL2CPP as the AOT compiler and add an interpreter beside it. The README describes the result as an "AOT + Interpreter" hybrid runtime, which is what makes dynamic assembly loading possible. The audience is Unity teams already on IL2CPP who want to patch game logic in C# rather than move that logic into a scripting language. The README is explicit that this is a Unity-specific solution, not a general CLR: HybridCLR is described as an interpreter module, and a separate project, LeanCLR, is offered for those who want a standalone CLR implementation.
How the AOT plus interpreter runtime is built
The README states the design was inspired by Mono's mixed mode execution work. Five pieces are listed as the actual engineering: a metadata (dll) parsing library, a reworked metadata management module that supports dynamic registration, a compiler from IL instructions to a custom register instruction set, a register interpreter, and a set of instinct functions added to improve interpreter performance. The architecture diagram in the repository, docs/images/architecture.png, is the reference for how these fit together.
The important consequence is where code executes. The README describes Differential Hybrid Execution (DHE) as letting unchanged AOT functions keep running as AOT code while changed or newly added functions run in the interpreter. That is a real trade-off rather than a free lunch: hot-updated methods pay interpreter cost, and the README's performance claims are stated relative to other hot-update approaches, not relative to a pure AOT build. The README also claims full multithreading support including volatile, ThreadStatic and async Task, and compatibility with hot-update MonoBehaviour, ScriptableObject and DOTS. Those are the claims that separate it from interpreter-only schemes, and they are the ones worth checking against your own codebase.
Installing HybridCLR and running a first hot update
The README points to the official documentation and a quickstart page rather than embedding install steps, so the procedure below follows that quickstart entry point. The package is a Unity package; the repository's top-level entries are .github/, .gitignore, LICENSE, README.md, README_EN.md, docs/ and hybridclr/.
The quickstart describes adding the package to your Unity project, then opening the HybridCLR installer window. The README does not print the package identifier or the manifest entry, so check the quickstart page linked from the README for the exact value before editing anything. After the package resolves, the installer copies the IL2CPP changes into your Unity installation, and the HybridCLR settings list the assemblies you mark as hot update. What you should see is a settings asset naming those assemblies, and an IL2CPP build that still completes. If the installer step is skipped, the build will not contain the interpreter and dynamic loading will fail at runtime.
The runtime side is a load call. The README does not print the exact API, so confirm the method name and the assembly-loading helper against the quickstart before writing this into your startup path. The shape is: read the hot-update dll bytes from wherever you downloaded them, hand them to the loader, then invoke an entry point by reflection. The README states there is no code generation and no special code required for inheritance, generics or reflection, so ordinary C# in the hot-update assembly works once it is loaded.
Where HybridCLR is the wrong tool
The README links to a page of unsupported features, and that page is the first thing to read. The claim is a near-complete ECMA-335 implementation, not a complete one. Any project relying on a feature on that list has a hard blocker, and no amount of configuration removes it.
The second limitation is structural. HybridCLR is a Unity IL2CPP solution. If your game ships on a Mono backend, or is not a Unity project at all, the architecture does not apply. The README frames LeanCLR as the option for embedding a CLR into arbitrary apps and games, which is a signal that HybridCLR itself is scoped to Unity.
The third is operational, and the README is silent on it: there is no documented rollback path for a hot update that breaks a live build. The README does describe hot reload and hotfix, including unloading assemblies completely and repairing bugs without restarting the game, but those are capabilities of the runtime, not a deployment safety net. If your team has no way to ship a corrective hot update quickly, the ability to push code without store review cuts both ways.
HybridCLR compared with Lua and TypeScript hot-update stacks
The conventional alternative is to keep gameplay in a scripting language and drive it from C#. The README names two projects from the same author for exactly that pattern: ZLua for Lua and ZenTS for TypeScript. The difference in approach is where the logic lives. With a Lua or TypeScript stack, hot-update code is written in that language, and the C# side is a host. With HybridCLR, hot-update code is C#, and the interpreter runs it inside the same runtime as the AOT code.
That changes what you can express. The README claims hot-update MonoBehaviour and ScriptableObject support, and says hot-update scripts attached to assets instantiate correctly, which is the kind of thing a separate scripting VM makes awkward. It also claims multithreading support including async Task, which the README presents as something other hot-update schemes do not support. The cost is that you are modifying the IL2CPP runtime rather than running alongside it, which is why the installer step exists and why Unity version support matters.
If you want to compare against a fully separate runtime, LeanCLR is the project the README positions as the standalone option, including as a replacement for IL2CPP when publishing Unity or Tuanjie Engine builds to WebGL and mini-game platforms.
Version support, licence and the cost of upgrading
The README lists support for Unity 2019.4.x, 2020.3.x, 2021.3.x, 2022.3.x, 2023.2.x and 6000.x.y, all LTS lines, plus all platforms IL2CPP supports, Tuanjie Engine and HarmonyOS. Because the installer patches your Unity installation's IL2CPP code, the Unity version is not a detail you can defer: moving to a new Unity LTS line means re-running the installer against that editor version and re-verifying the build.
The last push to the repository was on 2026-08-20, and the repository is not archived. The README does not describe a release cadence or a versioning policy, and no recent releases were retrieved, so there is no published upgrade schedule to plan against. Budget for the installer step on every Unity upgrade rather than assuming it carries over.
The licence is MIT, stated in the README and present as the LICENSE file at the repository root. MIT is permissive and places few conditions on redistribution; the README also mentions a commercial support offering and a business contact. Whether the free licence covers your distribution model is a question for your own legal review, not something the README answers.
Editorial conclusion
Adopt HybridCLR if you ship Unity games on IL2CPP targets and need C# hot updates without rewriting gameplay in Lua or TypeScript. Do not adopt it if your project is small enough that a full rebuild per release is acceptable, or if you cannot accept that the interpreter path, not the AOT path, runs your changed code. Before committing, verify three things against your own project: that your Unity version appears in the supported LTS list, that every feature you use is listed as supported in the not-supported-features page, and that your hot-update assembly layout matches what the quickstart describes, since the README does not document a rollback procedure for a bad hot update.
Frequently asked questions
What is HybridCLR in Unity?
HybridCLR is a Unity hot-update solution that extends the IL2CPP runtime with an interpreter, turning it from a pure AOT runtime into an AOT plus interpreter hybrid. That lets it load assemblies dynamically and run hot-update C# code on platforms IL2CPP supports.
Which Unity versions and platforms does HybridCLR support?
The README lists Unity 2019.4.x, 2020.3.x, 2021.3.x, 2022.3.x, 2023.2.x and 6000.x.y LTS lines. It states support for all platforms IL2CPP supports, plus Tuanjie Engine and HarmonyOS.
Does HybridCLR work with IL2CPP?
Yes. The README describes HybridCLR as extending the il2cpp runtime code so it becomes an AOT plus Interpreter hybrid runtime, which is what enables dynamic assembly loading on IL2CPP targets.
How do I install HybridCLR in a Unity project?
The README directs readers to the official documentation and a quickstart page rather than listing steps itself. The quickstart covers adding the package and running the installer that applies the IL2CPP changes to your Unity installation.
Is HybridCLR free to use?
The README states HybridCLR is licensed under MIT, and a LICENSE file sits at the repository root. The README also mentions a separate commercial support offering with a business contact address.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/focus-creative-games-hybridclr)