How focus-creative-games/hybridclr works
Project Type and Purpose
• HybridCLR is a native C++ library integrated into Unity’s IL2CPP runtime.
• It converts a pure AOT runtime into a hybrid AOT+Interpreter runtime, enabling full-platform C# hot update without codegen or workflow changes.
File-Structure Analysis
• Top-level “hybridclr” folder contains:
• CommonDef*/*.cpp, .h – shared definitions
• Runtime*/Runtime.cpp, RuntimeApi, RuntimeConfig – core runtime hooks and configuration
• generated – auto-generated binding code (AssemblyManifest, MethodBridge)
• interpreter – the register-VM interpreter engine, instruction definitions, execution logic, method bridges
• metadata – ECMA-335 metadata reader, image loader, manifest, PDB support, vtable setup
• transform – IL→register instruction compiler, basic block splitting, transform contexts, memory arena
• No frontend/backend split; it’s a library subdivided into major modules.
• Build/deployment is governed by CMake scripts (not shown), Unity plug-in packaging, and runtime registration.
README Insights
• Describes a five-part architecture (metadata parser, IL→reg compiler, interpreter, instinct functions, metadata registration)
• Emphasizes mixed-mode execution inspired by Mono’s mixed mode
Main Components
a. Unity IL2CPP AOT Runtime
• The host process that executes native code and loads modules
b. HybridCLR Core Runtime
• RuntimeConfig: read settings, decide AOT vs Interpreter
• RuntimeApi: hooks into IL2CPP, registers metadata, assembly loader
c. Metadata Module
• MetadataReader, Image loader, AssemblyManifest – parse ECMA-335 DLLs at runtime
d. Transform (IL→Reg Compiler)
• TransformContext, BasicBlockSplitter, compiler front end that emits custom register-based bytecode
e. Interpreter Engine
• InstrinctDef, Engine, Interpreter, MemoryUtil – executes register bytecode, supports threading, reflection, PInvoke
f. MethodBridge Layer
• Generated code + runtime bridges to call between AOT and interpreter functions
g. Differential Hybrid Execution (DHE)
• Decision layer that routes unmodified methods through AOT paths, modified methods to interpreter
Relationships and Interactions
• At startup, RuntimeApi hooks into IL2CPP and registers HybridCLR modules.
• Metadata module scans and registers new assemblies (hot-update DLLs).
• Transform module compiles IL methods into register bytecode.
• RuntimeConfig/DHE layer flags methods for AOT or interpreter execution.
• Calls from Unity engine or AOT code into updated methods go through MethodBridge into the interpreter.
• Interpreter executes bytecode, may invoke native instinct functions or call back into AOT code.
Architectural Patterns and Principles
• Modular decomposition: clearly separated metadata, transform, interpreter, runtime APIs
• Mixed-mode execution pattern (AOT + interpreter)
• Plug-in style dynamic assembly loader (hot update)
• Zero-cost invocation for unmodified code via Differential Hybrid Execution
• ECMA-335 compliance center via metadata reader module