# focus-creative-games/hybridclr architecture

> Architecture diagram of the GitHub repository focus-creative-games/hybridclr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/focus-creative-games/hybridclr
- Repository: https://github.com/focus-creative-games/hybridclr

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Host
    subgraph "Layer 1: Host"
        Engine["Unity Engine\nIL2CPP AOT Runtime"]:::external
    end

    %% Layer 2: Injected HybridCLR
    subgraph "Layer 2: Injected HybridCLR"
        RuntimeApi["RuntimeApi"]:::hooks
        RuntimeConfig["RuntimeConfig"]:::hooks
        CoreRuntime["HybridCLR Core Runtime"]:::hooks
    end

    %% Layer 3: Modules
    subgraph "Layer 3: Modules"
        subgraph "Metadata Module"
            MetaReader["MetadataReader"]:::data
            Image["Image Loader"]:::data
            AssemblyManifest["AssemblyManifest"]:::data
            VTableSetup["VTableSetup"]:::data
        end
        subgraph "Transform Module"
            TransformContext["TransformContext"]:::compile
            BasicBlockSplitter["BasicBlockSplitter"]:::compile
            TransformModule["TransformModule"]:::compile
            TemporaryMemoryArena["TemporaryMemoryArena"]:::compile
        end
        subgraph "Interpreter Engine"
            EngineVM["Engine"]:::interp
            Instruction["Instruction"]:::interp
            InstrinctDef["InstrinctDef"]:::interp
            InterpreterCore["Interpreter"]:::interp
            InterpreterUtil["InterpreterUtil"]:::interp
            MemoryUtil["MemoryUtil"]:::interp
        end
    end

    %% Layer 4: MethodBridge
    subgraph "Layer 4: MethodBridge"
        MB_Gen["MethodBridge (generated)"]:::hooks
        MB_Run["MethodBridge (runtime)"]:::hooks
    end

    %% Layer 5: Assemblies
    subgraph "Layer 5: Assemblies"
        AOTAssembly["Original AOT DLLs"]:::data
        HotUpdate["Hot-update Assemblies"]:::data
    end

    %% Startup and Data Flow
    Engine -->|startup hook| RuntimeApi
    Engine -->|load settings| RuntimeConfig
    RuntimeApi -->|register modules| MetaReader
    AOTAssembly -->|IL parsing| MetaReader
    HotUpdate -->|IL parsing| MetaReader
    MetaReader -->|metadata output| TransformContext
    TransformContext -->|split blocks| BasicBlockSplitter
    BasicBlockSplitter --> TransformModule
    TransformModule -->|Bytecode| InterpreterCore
    RuntimeConfig -->|"DHE decision"| MB_Gen
    Engine -->|invoke method| MB_Gen
    MB_Gen -->|bridge call| InterpreterCore
    InterpreterCore -->|native calls| InstrinctDef
    InterpreterCore -->|callback| CoreRuntime

    %% Click Events
    click RuntimeApi "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/RuntimeApi.cpp"
    click RuntimeConfig "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/RuntimeConfig.cpp"
    click CoreRuntime "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/Runtime.cpp"
    click MetaReader "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/metadata/MetadataReader.h"
    click Image "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/metadata/Image.cpp"
    click AssemblyManifest "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/metadata/AssemblyManifest.cpp"
    click VTableSetup "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/metadata/VTableSetup.cpp"
    click TransformContext "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/transform/TransformContext.cpp"
    click BasicBlockSplitter "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/transform/BasicBlockSpliter.cpp"
    click TransformModule "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/transform/TransformModule.cpp"
    click TemporaryMemoryArena "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/transform/TemporaryMemoryArena.cpp"
    click EngineVM "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/Engine.cpp"
    click Instruction "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/Instruction.cpp"
    click InstrinctDef "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/InstrinctDef.h"
    click InterpreterCore "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/Interpreter.cpp"
    click InterpreterUtil "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/InterpreterUtil.cpp"
    click MemoryUtil "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/MemoryUtil.h"
    click MB_Gen "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/generated/MethodBridge.cpp"
    click MB_Run "https://github.com/focus-creative-games/hybridclr/blob/main/hybridclr/interpreter/MethodBridge.cpp"

    %% Styles
    classDef external fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef hooks fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef compile fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef interp fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef data fill:#F0F0F0,stroke:#333,stroke-width:1px
```
