If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/focus-creative-games/hybridclr shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2mo ago
• 2 active contributors
• MIT licensed
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live focus-creative-games/hybridclr repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/focus-creative-games/hybridclr.

What it runs against: a local clone of focus-creative-games/hybridclr — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in focus-creative-games/hybridclr | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 98 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of focus-creative-games/hybridclr. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/focus-creative-games/hybridclr.git
#   cd hybridclr
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of focus-creative-games/hybridclr and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "focus-creative-games/hybridclr(\\.git)?\\b" \\
  && ok "origin remote is focus-creative-games/hybridclr" \\
  || miss "origin remote is not focus-creative-games/hybridclr (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "hybridclr/Runtime.h" \\
  && ok "hybridclr/Runtime.h" \\
  || miss "missing critical file: hybridclr/Runtime.h"
test -f "hybridclr/interpreter/Interpreter.h" \\
  && ok "hybridclr/interpreter/Interpreter.h" \\
  || miss "missing critical file: hybridclr/interpreter/Interpreter.h"
test -f "hybridclr/metadata/Image.h" \\
  && ok "hybridclr/metadata/Image.h" \\
  || miss "missing critical file: hybridclr/metadata/Image.h"
test -f "hybridclr/metadata/MetadataModule.h" \\
  && ok "hybridclr/metadata/MetadataModule.h" \\
  || miss "missing critical file: hybridclr/metadata/MetadataModule.h"
test -f "hybridclr/transform/Transform.h" \\
  && ok "hybridclr/transform/Transform.h" \\
  || miss "missing critical file: hybridclr/transform/Transform.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 98 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~68d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/focus-creative-games/hybridclr"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HybridCLR is a native C# hot-reload runtime for Unity that transforms il2cpp's pure AOT execution model into an AOT+Interpreter hybrid runtime. It enables dynamic assembly loading and runtime C# code updates across all il2cpp platforms (iOS, Android, WebGL, Consoles) by implementing a custom IL-to-register compiler (hybridclr/interpreter/Instruction.cpp, Engine.cpp) and high-performance register interpreter, matching AOT execution speed while supporting full ECMA-335 specification compliance. Monolithic C++ core (hybridclr/) organized by subsystem: interpreter/ contains IL compilation/execution (Instruction.cpp, Engine.cpp, Interpreter_Execute.cpp), metadata/ handles assembly parsing and registration (Assembly.cpp, BlobReader.h, Coff.h), generated/ holds build outputs (MethodBridge.cpp, AssemblyManifest.cpp). Runtime bootstrap files (Runtime.cpp, RuntimeApi.cpp) expose C# interop; CommonDef.h provides shared IL2CPP compatibility shims.

Game developers and studios using Unity who need C# hot-update capabilities on restricted platforms (iOS, WebGL, Consoles) without sacrificing performance or rebuilding native binaries. Specifically targets teams shipping commercial titles on App Store/Google Play who cannot use Mono's just-in-time compilation and need seamless MonoBehaviour/DOTS hot-patching.

Production-ready and battle-tested: thousands of commercial games deployed (100+ in iOS top-500), including MMORPG and AAA titles from major Chinese studios. Active maintenance across 2019.4–6000.x.y Unity LTS versions. Well-documented official site (hybridclr.cn), substantial Discord/QQ community (multiple 3000-person groups), and consistent commit activity suggest ongoing development and support.

Low maintenance risk due to established commercial adoption and active community backing. Risk factors: core C++ implementation (1.4M lines) is largely single-maintainer focused; breaking changes possible across Unity version jumps (tested only on LTS releases 2019.4, 2020.3, 2021.3, 2022.3, 2023.2, 6000.x). Complex IL interpretation edge cases may not be fully covered in all ECMA-335 features—README lists unsupported features explicitly.

No recent commit data visible in provided file list, but project is described as 'actively developed' with support across six Unity LTS versions through 6000.x.y, suggesting continuous compatibility updates. Documentation references 'DHE (Differential Hybrid Execution)' technology and 'hot-reload'/'hot-fix' features as recent/ongoing work areas.

Clone the repository: git clone https://github.com/focus-creative-games/hybridclr.git. No npm/package.json present—this is a Unity native plugin. Integration requires: (1) downloading the compiled plugin for your Unity version, (2) placing it in Assets/Plugins or following official integration guide at hybridclr.cn/docs/beginner/quickstart, (3) configuring UnityVersion.h for your target version, (4) rebuilding il2cpp runtime or using precompiled binaries.

Daily commands: Not a runnable CLI tool. HybridCLR is a compiled native plugin (.so/.dll/.a) statically linked into Unity's il2cpp runtime. After integration into a Unity project: (1) build target for desired platform (Android, iOS, etc.) with il2cpp backend, (2) at runtime, call RuntimeApi methods (likely from C#) to load and execute hot-update assemblies. See official docs for example C# bridge code.

• hybridclr/Runtime.h — Core runtime header defining the main HybridCLR execution environment; all contributors must understand the runtime architecture
• hybridclr/interpreter/Interpreter.h — Central interpreter engine that executes IL instructions; critical for understanding hot-update code execution
• hybridclr/metadata/Image.h — Metadata image abstraction layer handling assembly loading and reflection; fundamental to dynamic assembly support
• hybridclr/metadata/MetadataModule.h — Metadata module orchestration; bridges loaded assemblies with runtime type resolution
• hybridclr/transform/Transform.h — IL transformation layer that prepares dynamically-loaded code for interpreter execution
• hybridclr/RuntimeApi.h — Public API surface for Unity integration; defines how game code interfaces with HybridCLR

• RuntimeApi (C++, IL2CPP interop) — C++ entry point for Unity; manages assembly loading, method invocation, and lifetime
  • Failure mode: Assembly load failure → exception propagated; invocation failure → NULL return or crash
• Interpreter — Executes IL bytecode on abstract stack machine; maintains execution context and frame stack

Add Support for a New IL Opcode

1. Define the opcode enum in (hybridclr/metadata/Opcodes.h)
2. Register opcode metadata and size in (hybridclr/metadata/Opcodes.cpp)
3. Implement instruction execution handler in (hybridclr/interpreter/Interpreter_Execute.cpp)
4. If transformation needed, add handler in (hybridclr/transform/TransformContext.cpp)

Add a New Metadata Image Type

1. Create header inheriting from Image interface (hybridclr/metadata/Image.h)
2. Implement LoadImageData() and type resolution methods (hybridclr/metadata/Image.cpp)
3. Register in MetadataModule's factory method (hybridclr/metadata/MetadataModule.cpp)
4. Update assembly loading logic in (hybridclr/metadata/Assembly.cpp)

Extend Runtime Configuration

1. Add config field to struct in (hybridclr/RuntimeConfig.h)
2. Implement initialization in (hybridclr/RuntimeConfig.cpp)
3. Expose via public API in (hybridclr/RuntimeApi.h)
4. Consume in Runtime initialization (hybridclr/Runtime.cpp)

Add Interpreter Intrinsic (Fast-Path Optimization)

1. Define intrinsic in (hybridclr/interpreter/InstrinctDef.h)
2. Add transformation logic in (hybridclr/transform/TransformContext_Instinct.cpp)
3. Implement execution handler in (hybridclr/interpreter/Interpreter_Execute.cpp)

• C++ for core runtime — Direct IL2CPP integration and zero-overhead abstraction required; C++ matches IL2CPP codebase
• Interpreter pattern for dynamic code — Enables runtime assembly loading without AOT compilation; portable across all IL2CPP platforms
• Metadata image abstraction — Unified interface for interpreter and AOT assemblies; enables seamless hot-update interop
• IL transformation pipeline — Optimizes and normalizes IL before interpretation; reduces interpreter complexity and improves performance

• AOT + Interpreter hybrid model

  • Why: Allows shipping pre-compiled code (AOT) for performance while enabling hot updates (interpreter)
  • Consequence: Two execution paths require consistent type resolution and method interop; higher initial complexity

• Bytecode interpretation over JIT

  • Why: JIT not available on iOS/Consoles; interpretation works on all IL2CPP platforms
  • Consequence: Interpreter code inherently slower than JIT; mitigated by intrinsics and AOT fallback

• Metadata pooling and sharing

  • Why: Reduces memory footprint and enables efficient string/blob deduplication
  • Consequence: Complex pool lifecycle management; pools must outlive all loaded images

• Does not support unsafe pointer arithmetic in interpreter code (uses safe bridges to AOT for interop)
• Does not JIT-compile; all dynamic code is interpreted
• Does not modify il2cpp runtime source code; extends via C++ API layer only
• Does not support all ECMA-335 features (explicitly documents unsupported features)

IL2CPP version lock: compiled plugin only works with exact Unity/il2cpp version it was built for (UnityVersion.h hardcodes this). No dynamic discovery—requires rebuilding native code or using precompiled binaries. Generated files (AssemblyManifest.cpp, MethodBridge.cpp) must match your AOT assemblies; mismatch causes linker errors. Memory model: interpreter uses stack-based locals but shares il2cpp heap; custom GC hooks required (not exposed in visible files—check generated/). AOT homologous images (AOTHomologousImage.h) must be present for certain platform behaviors (iOS, WebGL); absent stubs fail silently.

• AOT (Ahead-of-Time) Compilation — HybridCLR's entire purpose is extending AOT-only il2cpp with interpreter capability; understanding AOT constraints (no reflection, static analysis only) explains why interpreter support was necessary.
• Register-based Intermediate Representation — HybridCLR compiles ECMA-335 IL into custom register IR (not stack-based); this is why Instruction.cpp and Engine.cpp are complex—you must understand register allocation to modify the VM.
• ECMA-335 Common Language Infrastructure (CLI) — HybridCLR claims 'near-complete' ECMA-335 support; understanding CLI's type system, metadata format, and IL instruction set is essential to evaluate unsupported features and debug metadata issues.
• Mixed-Mode Execution (AOT + Interpreter) — Core architectural innovation: some functions run as pre-compiled AOT code, others interpret IL at runtime; this dual model is why DHE (Differential Hybrid Execution) is possible and why metadata dynamic registration exists.
• Portable Executable (PE) / Common Object File Format (COFF) — .NET assemblies are PE files with COFF metadata; BlobReader.h and Coff.h parse this binary format; understanding PE structure is crucial for metadata parsing bugs.
• MonoPInvokeCallback — HybridCLR explicitly supports MonoPInvokeCallback for native/script interop; this is a Unity-specific attribute allowing interpreter C# code to be called from native C++, essential for game integration.
• Stack Machine vs. Register Machine Interpretation — HybridCLR's register-based interpreter (Engine.cpp) differs from naive stack-based IL execution; register machines are faster but more complex; understanding this tradeoff explains the custom IR design.

• focus-creative-games/leanclr — Official lightweight variant of HybridCLR targeting minimal memory/binary size; referenced in HybridCLR docs as an alternative approach.
• Tencent/InjectFix — Predecessor hot-fix framework for Unity; inspired similar AOT+interpreter design before HybridCLR existed.
• mono/mono — Original mixed-mode execution inspiration (mono-project.com/news/2017/11/13/mono-interpreter/); HybridCLR's architectural approach derived from Mono's interpreter design.
• Unity-Technologies/il2cpp_plus — Official il2cpp open-source contributions; HybridCLR extends il2cpp internals, so tracking official il2cpp changes is essential for compatibility.
• egametang/ET — Popular Unity game framework with documented HybridCLR integration; example of production architecture using HybridCLR for C# hot-updates.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Interpreter execution engine

The interpreter module (hybridclr/interpreter/Interpreter_Execute.cpp, Engine.cpp) is critical to HybridCLR's core functionality but lacks visible test coverage. This is a high-risk area where bugs could silently break hotupdate functionality across all platforms. New contributors can add unit tests covering instruction execution, stack operations, and method invocations.

• [ ] Create tests/interpreter/test_instruction_execution.cpp covering opcode execution in Interpreter_Execute.cpp
• [ ] Add tests for Engine.cpp stack frame management and exception handling
• [ ] Test edge cases in MethodBridge.cpp bridge invocations between interpreted and AOT code
• [ ] Integrate tests into CI pipeline via .github/workflows (currently only FUNDING.yml exists)

Add metadata reader/writer validation tests for InterpreterImage and AOTHomologousImage

The metadata layer (hybridclr/metadata/InterpreterImage.cpp, AOTHomologousImage.cpp, MetadataReader.h) handles critical assembly parsing and layout calculation. Bugs here can cause crashes or incorrect behavior across all platforms. New contributors can add tests validating ECMA-335 compliance, field layout calculations, and assembly manifest consistency.

• [ ] Create tests/metadata/test_interpreter_image.cpp validating InterpreterImage.cpp assembly loading
• [ ] Add tests/metadata/test_field_layout.cpp for ClassFieldLayoutCalculator.cpp edge cases (padding, alignment)
• [ ] Create tests/metadata/test_aot_homologous.cpp validating AOTHomologousImage and ConsistentAOTHomologousImage consistency
• [ ] Add regression tests for ECMA-335 edge cases (generic methods, custom attributes, nested types)

Add platform-specific integration tests for il2cpp runtime compatibility

The Il2CppCompatibleDef.cpp/h and RuntimeApi.cpp expose critical interfaces to Unity's il2cpp runtime. Different Unity versions and platforms (iOS, Android, WebGL, Console) may have subtle compatibility issues. New contributors can add integration tests validating runtime initialization, assembly loading, and method invocation across supported platforms.

• [ ] Create tests/integration/test_il2cpp_compat.cpp validating Il2CppCompatibleDef.h interface compatibility
• [ ] Add tests/integration/test_runtime_initialization.cpp for Runtime.cpp/RuntimeConfig.cpp initialization flows
• [ ] Create platform-specific test stubs in tests/platform/ for iOS, Android, WebGL validation paths
• [ ] Document expected test results in docs/testing.md for contributor reference

• Add comprehensive unit tests for hybridclr/metadata/BlobReader.h edge cases (malformed metadata, truncated headers, unsupported signatures)—currently no test files visible; add to a new test/ directory using a C++ framework (gtest/catch).
• Document the ECMA-335 unsupported features listed in the README with code comments in relevant interpreter files (e.g., mark InstrinctDef.h instructions that are no-ops or stubs with TODO comments linking to the unsupported features page).
• Implement missing ConsistentAOTHomologousImage.cpp functionality for WebGL platform support—file exists but is likely incomplete; add platform-specific metadata resolution logic compared to AOTHomologousImage.cpp.

• Medium · Potential Memory Safety Issues in C++ Implementation — hybridclr/interpreter/*, hybridclr/metadata/*. The codebase is written in C++ and implements a runtime interpreter for C# code. C++ is prone to memory safety vulnerabilities including buffer overflows, use-after-free, and heap corruption. The interpreter implementation (Interpreter.cpp, Engine.cpp) and metadata parsing (MetadataReader.h, BlobReader.h) are critical attack surfaces where malformed or malicious assemblies could trigger memory corruption. Fix: Implement strict input validation for all assembly metadata parsing. Use memory-safe patterns, bounds checking, and consider using static analysis tools (AddressSanitizer, Valgrind) to detect memory vulnerabilities. Implement fuzzing tests with malformed assemblies.
• High · Unrestricted Dynamic Assembly Loading — hybridclr/metadata/InterpreterImage.cpp, hybridclr/metadata/Assembly.cpp, hybridclr/RuntimeApi.cpp. The runtime supports dynamic loading of C# assemblies (InterpreterImage.cpp, Assembly.cpp). Without proper verification mechanisms, this could allow loading of malicious or untrusted assemblies that execute arbitrary code. The RuntimeApi.cpp exposes assembly loading APIs that may not validate assembly signatures or origins. Fix: Implement assembly signature verification and whitelisting. Validate assembly integrity using cryptographic signatures. Restrict which sources (files, URLs) assemblies can be loaded from. Log all assembly loading attempts.
• High · Lack of Sandboxing for Interpreted Code — hybridclr/interpreter/Interpreter.cpp, hybridclr/interpreter/Engine.cpp, hybridclr/interpreter/Interpreter_Execute.cpp. The interpreter executes arbitrary C# code with minimal isolation. The Interpreter.cpp and Engine.cpp implementations do not appear to provide sandboxing or capability restrictions. Malicious code could access reflection APIs, native code, or memory directly. Fix: Implement code verification passes to reject dangerous operations. Restrict reflection API access. Disable access to native interop unless explicitly needed. Implement resource limits (CPU, memory) for interpreted code execution.
• Medium · Potential Integer Overflow in Metadata Parsing — hybridclr/metadata/MetadataReader.h, hybridclr/metadata/Tables.h, hybridclr/metadata/BlobReader.h. Metadata parsing code (MetadataReader.h, Tables.h) performs calculations on untrusted binary data. Integer overflows in size calculations or buffer allocations could lead to out-of-bounds access or heap corruption. Fix: Use safe integer arithmetic that checks for overflows. Validate all size values before allocation. Implement bounds checking on all buffer operations. Add static analysis to detect integer overflow patterns.
• Medium · Missing Input Validation in Assembly Manifest — hybridclr/generated/AssemblyManifest.cpp. The AssemblyManifest.cpp is generated code that processes assembly metadata. Generated code may not include proper validation of malformed input, leading to potential vulnerabilities. Fix: Ensure the code generator produces robust validation logic. Add runtime checks for all manifest entries. Implement fuzz testing of manifest parsing with malformed data.
• Low · Potential Information Disclosure via Debug Symbols — hybridclr/metadata/PDBImage.cpp. The PDBImage.cpp processes debug information which could leak sensitive information about code structure and internal APIs if exposed. Fix: Ensure debug symbols are stripped from production builds. Implement secure handling of debug metadata. Document which information is sensitive.
• Medium · No Visible Access Control Mechanisms — hybridclr/RuntimeApi.h, hybridclr/Runtime.h. The RuntimeApi.h and Runtime.h do not show clear access control or authentication mechanisms for exposing runtime functionality to loaded assemblies. Fix: Implement capability-based security model. Define and enforce which APIs can be accessed by untrusted code. Use privilege separation between trusted and untrusted code execution contexts.
• Low · Missing Security Documentation — Repository root. No visible security.md or security guidelines in the repository root. Security considerations for using HybridCLR are not documented. Fix: Create a SECURITY.md file documenting:

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.