使用指南

📄️ Supported Unity Versions and Platforms

HybridCLR has stably supported the 2019.4.x, 2020.3.x, 2021.3.x, 2022.3.x LTS series and testing versions like 2023.2.x, 6000.x.y, and supports all platforms supported by il2cpp.

📄️ Configuration

After installing the com.code-philosophy.hybridclr package, you need to properly configure related parameters. For detailed configuration documentation, see hybridclr_unity Package Introduction.

📄️ Assembly Configuration

Generally speaking, hot update code must be organized into independent assemblies to facilitate hot updates.

📄️ Build Workflow

Due to the requirements of hot updating itself and some limitations of Unity's resource management, special handling is needed for the build workflow, mainly divided into several parts:

📄️ Publishing to WebGL Platform

Due to the many specificities of the WebGL platform, this document specifically describes how to publish to the WebGL platform. This document demonstrates the publishing process on the hybridclrtrial project (github gitee).

📄️ Code Stripping

Unity uses code stripping technology to help reduce package size for the il2cpp backend. If anti-stripping measures are not taken, since there is generally not much code in the AOT main project, a large number of C# types and functions are stripped, causing hot update calls to these stripped classes or functions to result in the following exceptions:

📄️ MonoBehaviour Support

HybridCLR fully supports hot update MonoBehaviour and ScriptableObject workflows, allowing you to add hot update scripts to GameObjects in code or directly attach hot update scripts to assets. However, due to the special nature of Unity's asset management mechanism, attaching hot update scripts to assets requires some special handling in the packaging workflow.

📄️ PInvoke Support

Prior to version v8.0.0, defining extern functions in hot update code and attempting to call them would throw an ExecutionEngineException: method body is null error.

📄️ MonoPInvokeCallback Support

When interacting with third-party languages like Lua, you need to call C# functions from these third-party languages. Two problems must be solved:

📄️ AOT Generics

CLR has two types of generic features: generic types and generic functions. Generics are an extremely widely used feature in C#. Even code that doesn't obviously contain generic usage may implicitly include generic-related definitions or operations.

📄️ Bridge Functions

HybridCLR's interpreter needs bidirectional function calls with AOT. For example, interpreter calling AOT functions, or AOT calling back to interpreter through interface or delegate callbacks.

📄️ DOTS Support

DOTS's TypeManager initializes too early and doesn't support dynamic registration of Components and Systems. To make hot update modules run properly in DOTS systems, DOTS source code needs to be modified to adjust the initialization timing of World.

📄️ Code Obfuscation

If hot update code is not obfuscated, tools like ILSpy can easily decompile it back to near-source-code C# code, posing serious threats to intellectual property and code security for commercial game projects and indie game development.

📄️ Memory and GC

HybridCLR runtime memory consumption mainly consists of several parts:

📄️ Execution Performance

Although HybridCLR also uses interpretation execution, both theoretical principles and real device testing data show that HybridCLR has dramatically improved performance (multiple times or even dozens of times) compared to popular hot update solutions like Lua and ILRuntime.

📄️ Impact on App Package Size

The impact on package size after integrating HybridCLR mainly consists of the following parts:

📄️ Impact on App Memory

After integrating HybridCLR, the impact on App runtime memory mainly consists of the following parts:

📄️ Unsupported Features

HybridCLR supports all features not listed in the limitations below. Please don't ask whether HybridCLR supports a specific feature.

📄️ hybridclr Package Manual

com.code-philosophy.hybridclr is a Unity package that provides Editor workflow tools and Runtime scripts required by HybridCLR. With the workflow tools provided by com.code-philosophy.hybridclr, packaging an App that supports HybridCLR hot update functionality becomes very simple. The hybridclr_unity package mainly contains the following content:

📄️ Best Practices

Don't Save assemblyBytes After Assembly.Load

📄️ Migrating from netstandard to .Net Framework

During Unity's packaging process, all references to netstandard.dll are converted to final references like mscorlib.dll, causing the original code's reference relationships to differ significantly from the final reference relationships. This difference causes the Generate/All/ commands to run with errors. Additionally, since the hot update dlls compiled by HybridCLR/CompileDll/ commands still reference netstandard rather than the final assemblies like mscorlib, loading and running hot update dlls will result in errors where types in netstandard cannot be found. Therefore, HybridCLR defaults to requiring the use of Net Framework Api Level.

📄️ HybridCLR + lua/js/python

Some projects are already online with most of their code implemented in lua; or some new projects have been developed halfway using lua. They cannot completely switch to full C# development, but they want to integrate HybridCLR to help gradually transition to full native C# hot updates. Since HybridCLR is a native C# hot update technology, it natively supports working with these scripting languages.