unity-hybridclr

name	unity-hybridclr
description	Automate HybridCLR C# hot-update prebuild

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Configuring hot-update assemblies
• Compiling hot-update DLLs
• Generating AOTGenericReferences/link.xml
• Diagnosing HybridCLR setup
• Wiring output into YooAsset builds
• 配置热更程序集、编译热更 DLL、生成 AOTGenericReferences/link.xml、排查 HybridCLR 环境、把产物接进 YooAsset 打包链路

Unity HybridCLR Skills

Editor-side automation for HybridCLR — the zero-cost native C# hot-update solution for IL2CPP. Covers settings CRUD, installation probing, hot-update assembly compilation, the prebuild generation pipeline, and artifact staging for a YooAsset bundle build.

This module holds zero direct references to the package. Every call resolves through reflection against the HybridCLR.Editor assembly, so the UnitySkills Editor assembly compiles identically whether or not HybridCLR is installed — there is no scripting define to set and no recompile needed after installing.

Requires: com.code-philosophy.hybridclr (API anchored to 8.12.0), IL2CPP scripting backend, Unity 2019.4+ (2022.3+ recommended). Companion modules: yooasset for shipping the compiled DLLs as bundles, yooasset-design for the runtime loading contract, asmdef for assembly-boundary design.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): the seven read-only skills — hybridclr_status, hybridclr_install_status, hybridclr_get_paths, hybridclr_settings_get, hybridclr_validate_setup, hybridclr_get_hotupdate_dlls, hybridclr_aot_generic_refs — are SemiAuto and run directly. hybridclr_settings_set and hybridclr_copy_hotupdate_dlls are FullAuto: on MODE_RESTRICTED, run the grant protocol.
• Auto-forbidden (NeverInSemi, RiskLevel="high"): hybridclr_compile_dlls, hybridclr_generate_all, hybridclr_generate_step. Reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns MODE_FORBIDDEN. This is deliberate — all three block the Editor main thread for minutes.
• When the package is missing, every skill except hybridclr_status returns a MISSING_PACKAGE error with install instructions. When the package is present but a reflected member cannot be resolved (version drift), the skill returns MISSING_PACKAGE naming the exact member instead of throwing.

DO NOT (common hallucinations):

• hybridclr_install / hybridclr_init — do NOT exist. Installing il2cpp_plus clones two git repos and copies the entire editor il2cpp tree; it is a multi-minute network operation with no cancellation and is intentionally not a skill. Run it from HybridCLR/Installer... in the Editor, or via unity-cli (see Limitations). hybridclr_install_status only reports the state.
• hybridclr_build_player — NOT in this module. Building the player is build_player (Project module) or unity-cli. HybridCLR hooks the build via its own IPreprocessBuildWithReport processors; nothing extra is needed from this module.
• hybridclr_load_metadata / hybridclr_load_assembly — runtime APIs (HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly, System.Reflection.Assembly.Load) belong in game code, not the Editor REST surface. Write them yourself.
• Do NOT call hybridclr_generate_all before every bundle rebuild — see the workflow section below. It is a pre-player-build step, not a per-hot-update step.
• Do NOT pass extension=".dll" to hybridclr_copy_hotupdate_dlls. Unity would treat the staged files as managed plugins and try to load them into the Editor domain; the skill rejects it.

Routing:

• HybridCLR settings, install probing, DLL compilation, generation pipeline, artifact staging → this module.
• Packing the staged DLLs into bundles, collector configuration, build reports → yooasset.
• Runtime hot-update loading code (YooAssets.LoadAssetAsync → Assembly.Load → RuntimeApi.LoadMetadataForAOTAssembly) → write it yourself using yooasset-design.
• Deciding which assemblies belong on the hot-update side → asmdef.
• Actual player build → build_player or unity-cli.

Skills

Environment (3)

Skill	Purpose	Key Parameters
hybridclr_status	Reflection probe — the ONLY skill that works without the package. Reports installation, package version, enable, scripting backend, hot-update + AOT-patch assembly lists, and which generated artifacts exist. Call this first.	(none)
hybridclr_install_status	il2cpp_plus local install state via InstallerController: whether libil2cpp is patched, installed vs package version, expected hybridclr / il2cpp_plus branches, Unity compatibility.	(none)
hybridclr_get_paths	Resolve every input/output path for a build target — HybridCLRData root, local il2cpp dir, hot-update DLL dir, stripped AOT dir, link.xml, AOTGenericReferences.cs. Use to wire outputs into a YooAsset collector.	buildTarget?

Settings (2)

Skill	Purpose	Key Parameters
hybridclr_settings_get	Read every HybridCLRSettings field, plus the resolved assembly lists SettingsUtil derives from asmdef assets and raw names (this is what the pipeline actually uses).	(none)
hybridclr_settings_set	Write settings and persist to ProjectSettings/HybridCLRSettings.asset. Only the parameters you pass change; the full prior object is snapshotted for workflow undo.	enable?, useGlobalIl2cpp?, hotUpdateAssemblies?, hotUpdateAssemblyDefinitions?, preserveHotUpdateAssemblies?, patchAOTAssemblies?, externalHotUpdateAssemblyDirs?, hotUpdateDllCompileOutputRootDir?, strippedAOTDllOutputRootDir?, outputLinkFile?, outputAOTGenericReferenceFile?, maxGenericReferenceIteration?, maxMethodBridgeGenericIteration?, hybridclrRepoURL?, il2cppPlusRepoURL?

Diagnostics (1)

Skill	Purpose	Key Parameters
hybridclr_validate_setup	Pre-flight check: package present, enable, IL2CPP backend, libil2cpp patched and version-matched, hot-update assemblies configured and resolvable, patchAOTAssemblies populated, link.xml / AOTGenericReferences.cs present, hot-update DLLs compiled. Returns categorised errors (blocking) and warnings (advisory), each with a concrete fix.	buildTarget?

Compile & generate (3) — blocking, high risk

Skill	Purpose	Key Parameters
hybridclr_compile_dlls	CompileDllCommand.CompileDll(target, developmentBuild) — compile hot-update assemblies into HybridCLRData/HotUpdateDlls/<target>. Prior output is backed up for workflow undo.	buildTarget?, developmentBuild=false
hybridclr_generate_all	PrebuildCommand.GenerateAll() — the full pipeline for the active build target: compile_dll → il2cpp_def → link_xml → aot_dlls → method_bridge → aot_generic_reference. Rewrites C# under Assets/, so a domain reload follows.	(none)
hybridclr_generate_step	Run one pipeline step: il2cpp_def, link_xml, aot_dlls, method_bridge, aot_generic_reference, clean_il2cpp_cache. Assumes hot-update DLLs are already compiled.	step, buildTarget?

Artifacts (3)

Skill	Purpose	Key Parameters
hybridclr_get_hotupdate_dlls	List compiled DLL artifacts with size + UTC timestamp, reconciled against the configured assembly list — surfaces missing and unexpected entries.	buildTarget?
hybridclr_copy_hotupdate_dlls	Stage compiled DLLs (optionally the stripped AOT DLLs too) into a directory under Assets/, renamed to an importable extension so a YooAsset collector can pack them. Destination files are backed up for workflow undo.	destination, buildTarget?, extension=".bytes", assemblies?, includeAotAssemblies=false, clearDestination=false
hybridclr_aot_generic_refs	Read generated AOTGenericReferences.cs — timestamp, declared PatchedAOTAssemblyList, and an inSync comparison against settings.patchAOTAssemblies with missingFromSettings / extraInSettings diffs.	includeContent=false

HybridCLR × YooAsset workflow

The two modules split cleanly: HybridCLR produces DLLs, YooAsset ships them. The staging step in between is hybridclr_copy_hotupdate_dlls, which renames .dll → .bytes so Unity imports them as TextAsset (a bare .dll under Assets/ would be treated as a managed plugin).

One-time setup (per project, and again after any AOT-side code change):

u.call_skill("hybridclr_settings_set",
    enable=True,
    hotUpdateAssemblyDefinitions=["Assets/HotUpdate/HotUpdate.asmdef"])
u.call_skill("hybridclr_validate_setup")     # fix every `errors` entry before continuing
u.call_skill("hybridclr_generate_all")       # minutes; domain reload follows
refs = u.call_skill("hybridclr_aot_generic_refs")
u.call_skill("hybridclr_settings_set", patchAOTAssemblies=refs["patchedAOTAssemblyList"])
# then build the player normally (build_player / unity-cli)

Iterative hot-update loop (every time hot-update C# changes — no generate_all, no player rebuild):

# 1. edit hot-update C# (script_* skills) — must live in a hotUpdateAssemblyDefinitions asmdef
# 2. compile
u.call_skill("hybridclr_compile_dlls", buildTarget="Android")
u.call_skill("hybridclr_get_hotupdate_dlls", buildTarget="Android")   # verify `missing` is empty

# 3. stage into the YooAsset collector directory
u.call_skill("hybridclr_copy_hotupdate_dlls",
    destination="Assets/HotUpdateDlls",
    buildTarget="Android",
    extension=".bytes",
    includeAotAssemblies=True,      # ships the stripped AOT metadata DLLs too
    clearDestination=True)

# 4. pack (yooasset module) — the collector only needs adding once
u.call_skill("yooasset_add_collector",
    packageName="DefaultPackage", groupName="HotUpdateCode",
    collectPath="Assets/HotUpdateDlls",
    addressRule="AddressByFileName", packRule="PackDirectory")
u.call_skill("yooasset_build_bundles",
    packageName="DefaultPackage", buildTarget="Android", packageVersion="auto")

Where the boundary sits: runtime loading is game code you write, not a skill. Load the .bytes TextAsset through YooAsset, then RuntimeApi.LoadMetadataForAOTAssembly(aotBytes, HomologousImageMode.SuperSet) for each AOT metadata DLL before Assembly.Load(hotUpdateBytes). Order matters. See yooasset-design for the handle-lifecycle rules.

When to re-run generate_all: only when AOT-side code changes (anything outside the hot-update asmdefs), when you add/remove a hot-update assembly, or before shipping a new player build. Generic instantiations reachable only from new hot-update code also require it — that is what AOTGenericReferences.cs records.

Critical Rules (must read)

1. hybridclr_status is the only skill that works without the package. Every other skill returns MISSING_PACKAGE. Unlike the YooAsset module there is no compile define — detection is pure reflection, so no recompile is needed after installing.
2. hybridclr_compile_dlls, hybridclr_generate_all and hybridclr_generate_step block the Editor main thread. UnitySkills runs all skills on the main thread through a single queue, so /health and /jobs also stall for the duration. Raise the client timeout to at least 10 minutes; a socket timeout does not cancel the operation.
3. generate_all and generate_step step="aot_dlls" run a scripts-only BuildPipeline.BuildPlayer internally into HybridCLRData/StrippedAOTDllsTempProj/<target>. Both refuse to start when BuildPipeline.isBuildingPlayer is true. The step temporarily flips EditorUserBuildSettings.buildScriptsOnly and the platform "export project" flags, restoring them in a finally — an Editor crash mid-step can leave them changed.
4. patchAOTAssemblies must match the generated PatchedAOTAssemblyList. Run hybridclr_aot_generic_refs after any generation and copy missingFromSettings into hybridclr_settings_set(patchAOTAssemblies=[...]). inSync=false means generic instantiations will throw at runtime. The generated list carries .dll suffixes and the setting does not; the skill compares on the stem, so pass either form.
5. Array parameters replace, they do not merge. hybridclr_settings_set(hotUpdateAssemblies=["A"]) discards any previously configured names. Read with hybridclr_settings_get first and pass the full intended array.
6. HybridCLRSettings is not an AssetDatabase asset. It is a ScriptableObject serialized to ProjectSettings/HybridCLRSettings.asset via InternalEditorUtility.SaveToSerializedFileAndForget, so it will not appear in asset_* skills, and Unity's undo stack cannot revert the file — only the workflow snapshot can.
7. Path fields use two different bases. and are relative to ; and are relative to the project directory. returns both the raw and absolute forms.

Limitations

• No install skill. InstallerController.InstallDefaultHybridCLR() is reachable by reflection but deliberately not exposed: it clones two git repos over the network and copies the editor's entire il2cpp tree, with no progress reporting or cancellation, and would hold the main-thread queue for the whole time. Use the HybridCLR/Installer... window, or unity-cli in batch mode.
• Synchronous execution. These operations are not AsyncJobService jobs — HybridCLR's commands are synchronous main-thread Unity APIs with no step boundaries to pump, so there is no jobId to poll. Treat them as long blocking calls.
• Workflow undo is partial for generation. hybridclr_settings_set restores fully. hybridclr_compile_dlls and hybridclr_copy_hotupdate_dlls restore the affected directory from a file backup under Library/UnitySkills/HybridCLRBackups/. hybridclr_generate_all and hybridclr_generate_step restore only the two Assets-side artifacts (link.xml, AOTGenericReferences.cs) plus the hot-update DLL directory — intermediates under HybridCLRData/ and generated C++ under LocalIl2CppData-*/ are rebuildable and deliberately out of scope. Re-run the pipeline rather than relying on undo for those.
• Backups keep 5 generations per label. Older undo steps for compile_dlls / copy_hotupdate_dlls degrade to "added files removed, previous files not restored". Library/ is not version-controlled, so backups do not survive a Library wipe.
• No control over build processors. HybridCLR's IPreprocessBuildWithReport / IPostprocessBuildWithReport hooks (CheckSettings, CopyStrippedAOTAssemblies, PatchScriptingAssemblyList, the Xcode source injectors) run automatically during the player build and are not configurable from this module.
• Version drift is reported, not guessed. Reflection targets are anchored to 8.12.0. If a member cannot be resolved the skill returns MISSING_PACKAGE naming it, rather than silently doing nothing.
• hybridclr_aot_generic_refs parses generated text, not IL. patchedAOTAssemblyList is read exactly from the initializer, but counts comment lines in the generator's block and is an approximation. Pass when you need the file verbatim.

unity-cli fallback

Every generation entry point is a [MenuItem]-annotated public static parameterless method, so anything this module cannot do is reachable through -executeMethod in batch mode:

Menu	-executeMethod target
HybridCLR/Generate/All	HybridCLR.Editor.Commands.PrebuildCommand.GenerateAll
HybridCLR/CompileDll/ActiveBuildTarget	HybridCLR.Editor.Commands.CompileDllCommand.CompileDllActiveBuildTarget
HybridCLR/Generate/LinkXml	HybridCLR.Editor.Commands.LinkGeneratorCommand.GenerateLinkXml
HybridCLR/Generate/Il2CppDef	HybridCLR.Editor.Commands.Il2CppDefGeneratorCommand.GenerateIl2CppDef
HybridCLR/Generate/AOTDlls	HybridCLR.Editor.Commands.StripAOTDllCommand.GenerateStripedAOTDlls
HybridCLR/Generate/MethodBridgeAndReversePInvokeWrapper	HybridCLR.Editor.Commands.MethodBridgeGeneratorCommand.GenerateMethodBridgeAndReversePInvokeWrapper
HybridCLR/Generate/AOTGenericReference	HybridCLR.Editor.Commands.AOTReferenceGeneratorCommand.CompileAndGenerateAOTGenericReference

Running these headless avoids the main-thread blocking problem entirely — see unity-cli. Installation has no parameterless menu method; it must go through the Installer window.

Reflection Anchors

Every skill resolves these against the HybridCLR.Editor assembly. Verified against hybridclr_unity 8.12.0 source.

Skill	Reflected target
hybridclr_status	SettingsUtil.Enable, SettingsUtil.HotUpdateAssemblyNamesExcludePreserved, SettingsUtil.AOTAssemblyNames, Installer.InstallerController
hybridclr_install_status	Installer.InstallerController — HasInstalledHybridCLR(), PackageVersion, InstalledLibil2cppVersion, MajorVersion, GetCompatibleType(), GetCurrentUnityVersionMinCompatibleVersionStr(), HybridclrLocalVersion, Il2cppPlusLocalVersion, LocalVersionFile
hybridclr_get_paths	SettingsUtil.{ProjectDir, HybridCLRDataDir, LocalUnityDataDir, LocalIl2CppDir, GeneratedCppDir, HotUpdateDllsRootOutputDir}, GetHotUpdateDllsOutputDirByTarget(BuildTarget), GetAssembliesPostIl2CppStripDir(BuildTarget)
hybridclr_settings_get / _set	Settings.HybridCLRSettings.Instance public fields + HybridCLRSettings.Save(); resolved lists via SettingsUtil.HotUpdateAssemblyNames{Exclude,Include}Preserved and HotUpdateAssemblyFilesIncludePreserved
hybridclr_compile_dlls	Commands.CompileDllCommand.CompileDll(BuildTarget, bool)
hybridclr_generate_all	Commands.PrebuildCommand.GenerateAll()
hybridclr_generate_step	Commands.Il2CppDefGeneratorCommand.GenerateIl2CppDef(), Commands.LinkGeneratorCommand.GenerateLinkXml(BuildTarget), Commands.StripAOTDllCommand.GenerateStripedAOTDlls(BuildTarget), Commands.MethodBridgeGeneratorCommand.GenerateMethodBridgeAndReversePInvokeWrapper(BuildTarget) and .CleanIl2CppBuildCache(), Commands.AOTReferenceGeneratorCommand.GenerateAOTGenericReference(BuildTarget)

Note SettingsUtil.HotUpdateAssemblyNamesIncludePreserved throws when a name appears in both hotUpdateAssemblies and preserveHotUpdateAssemblies. The skills catch it and surface the message in resolveErrors / hotUpdateAssemblyResolveError rather than failing the call.

Version Scope

• Target: com.code-philosophy.hybridclr 8.12.0. All type names, member names and signatures above are taken from that Editor source.
• Minimum Unity: HybridCLR itself supports 2019.4.0+ / 2020.3.0+ / 2021.3.0+ / 2022.3.0+ / 2023.2.0+ / 6000.0.0+ (6000.3.0+ on the 6000.3 branch); hybridclr_install_status reports the exact minimum for the running editor. This Skill module is verified against Unity 2022.3 and 6000.3.
• IL2CPP only. Mono builds cannot use HybridCLR; hybridclr_validate_setup reports this as a blocking error.
• Older/newer package versions still work for anything whose members resolve; unresolved members are reported by name, not silently skipped.

Exact Signatures

For authoritative parameter names, defaults, and return fields, query GET /skills/schema?category=HybridCLR or unity_skills.get_skill_schema(). This document is a routing / best-practice guide, not the signature source.