Unity Hybridclr

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. outputLinkFile and outputAOTGenericReferenceFile are relative to Assets/; hotUpdateDllCompileOutputRootDir and strippedAOTDllOutputRootDir are relative to the project directory. hybridclr_get_paths returns both the raw and absolute forms.
8. The upstream field is misspelled externalHotUpdateAssembliyDirs. The skill parameter is spelled correctly (externalHotUpdateAssemblyDirs) and maps to it; hybridclr_settings_get returns the upstream spelling under settings.
9. Hot-update code must live in an asmdef listed in hotUpdateAssemblyDefinitions (or a name in hotUpdateAssemblies). Code outside those assemblies is AOT and cannot be hot-updated — changing it requires a new player build.
10. hybridclr_validate_setup distinguishes errors from warnings. Errors block hot update entirely (no IL2CPP, libil2cpp unpatched, no hot-update assemblies). Warnings are staleness signals (DLLs not compiled yet, patchAOTAssemblies empty) that are normal early in setup.

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 PatchedAOTAssemblyList initializer, but genericTypeCount counts comment lines in the generator's // {{ AOT generic types block and is an approximation. Pass includeContent=true 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:

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.

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.