fix: restore Unity API xref links and update to Unity 6 LTS#32
Merged
NormandErwan merged 5 commits intomainfrom Apr 20, 2026
Merged
fix: restore Unity API xref links and update to Unity 6 LTS#32NormandErwan merged 5 commits intomainfrom
NormandErwan merged 5 commits intomainfrom
Conversation
DocFX v2 requires Roslyn to resolve Unity types (MonoBehaviour, AudioClip, etc.) to their fully-qualified UIDs before the xref map can link them to docs.unity3d.com. Without assembly references, crefs become !:AudioClip which never matches the xref map. A MSBuild Target globs all *.dll from $(UnityManagedPath) (defaulting to lib/UnityEngine/, populated by CI) so users never need to manually add <Reference> entries when new Unity types are used in their scripts. UNITY_MANAGED_PATH env var allows pointing to a local Unity installation for development without running Docker. .gitignore: replace broad *.csproj + negation with specific Unity-generated patterns (Assembly-CSharp*.csproj) so DocFxForUnity.csproj stays tracked without a fragile negation rule. Add lib/ to ignore extracted DLLs. https://claude.ai/code/session_01N4YoJdJc2JDaoAbk5Nt8vf
allowCompilationErrors: true was masking the root cause (missing Unity assembly references). With the glob-based csproj now providing full Unity type resolution, compilation succeeds cleanly and the flag is no longer needed. Removing it makes future compilation errors visible. Pin the UnityXrefMaps URL to the Unity 6 (6000.0) version-specific map instead of the floating "latest" root URL, matching ProjectVersion.txt. https://claude.ai/code/session_01N4YoJdJc2JDaoAbk5Nt8vf
Unity managed DLLs are required for Roslyn to resolve UnityEngine types during DocFX metadata extraction. Rather than committing binaries, the workflow pulls the public game-ci editor image (no license required) and copies the full UnityEngine/ directory (~60-80 modules) into lib/. A cache keyed on the Unity version (6000.0.73f1) stores the extracted DLLs (~50-150 MB) so Docker is only pulled on the first run or when the Unity version changes. Subsequent runs skip the extract step entirely. To update Unity version: bump the version in ProjectVersion.txt, docfx.json xref URL, DocFxForUnity.csproj comment, and the cache key + Docker tag here. https://claude.ai/code/session_01N4YoJdJc2JDaoAbk5Nt8vf
NormandErwan
changed the title
The ubuntu-6000.0.73f1-base-3 tag does not exist. Only platform-specific images are published for Unity 6000.0.73f1: android, webgl, linux-il2cpp, mac-mono. Switch to ubuntu-6000.0.73f1-linux-il2cpp-3.2.2, which includes the full editor with all managed DLLs. Also add mkdir -p lib before docker cp since the cache step may not have restored the directory on a cache miss. https://claude.ai/code/session_01N4YoJdJc2JDaoAbk5Nt8vf
This was referenced Apr 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
DocFX v2 uses Roslyn to compile the project during metadata extraction. Without Unity assembly references, Roslyn cannot resolve
AudioClip→UnityEngine.AudioClip, so<see cref="AudioClip"/>tags in XML doc comments become!:AudioClipin the generated YAML. The xref map atUnityXrefMapsmapsUnityEngine.AudioClip→ Unity docs URL but has no entry for!:AudioClip, so links are never emitted.allowCompilationErrors: truewas silently masking this root cause.Solution
unityci/editor:ubuntu-6000.0.73f1-base-3Docker image (no license required — Unity is never activated, only files are copied) and extracts the fullUnityEngine/directory (~60–80 modules) intolib/. A cache keyed on the Unity version means Docker is only pulled on the first run or when the version changes.DocFxForUnity.csprojreferences all*.dllfrom$(UnityManagedPath)via a batched MSBuild Target — users never need to manually add<Reference>entries when new Unity types appear in their scripts.allowCompilationErrorsremoved: Compilation now succeeds cleanly, making future errors visible rather than silent.6000.0version.Changes
bf7e191ProjectSettings/ProjectVersion.txtc410089DocFxForUnity.csproj,.gitignorelib/7aed77bDocumentation/docfx.jsonallowCompilationErrors; pin xref to6000.0a979486.github/workflows/documentation.ymlTest plan
_site/api/DocFxForUnity.Player.htmlcontains hyperlinks onMonoBehaviour,AudioClip, andAudioSourcepointing todocs.unity3d.com[Warning] xrefmissing lines in DocFX outputCS0246compilation warnings in DocFX outputhttps://claude.ai/code/session_01N4YoJdJc2JDaoAbk5Nt8vf