[SkowronskiAndrew]

Summary

Unity 6.7 changes how content directory builds handle circular references between assets. Unity 6.6 merges each cycle into a single Content File at build time. Unity 6.7 keeps every asset in its own Content File and loads the files of a cycle together at runtime. Users will analyze builds from both versions with UnityDataTool, so the Content Directory Format page now describes what each version produces.

Changes

• New Circular references subsection under Build layout granularity in contentdirectory-format.md:
  • What counts as a cycle: only direct references. Loadable and LoadableSceneId references don't count, and scenes can never be part of a cycle.
  • 6.6: the cycle is merged into one Content File, and that file's SourceAssets entry in ContentLayout.json lists every asset in the loop.
  • 6.7: the granular layout is kept, and the cycle shows up in SerializedFileDependencies. The files load as one unit at runtime, and the build fails if a cycle's combined size is over the limit.
  • The circularrefs.json report that 6.7 writes to the build history directory, with an example. The example is anonymized from a real build.
• The MonoScript grouping bullet now says that all MonoScripts in the build share a single Content File.
• The intro of contentdirectory-format.md now says that its ContentLayout.json excerpts use the v3 schema (Unity 6.7), and links to the v2 differences.
• contentlayout.md, Binary artifacts:
  • ArtifactReferences never records dependencies between serialized files. A contentfile artifact references only .resS/.resource files, and those are leaf nodes. That is why the graph never contains cycles, and the design will keep it that way.
  • The section now explains how to find everything needed to load a file: follow SerializedFileDependencies, which can contain cycles in 6.7, and collect each file's artifact references.

Testing

Documentation only. I checked the doc excerpts against the v3 reference layout in TestCommon. I checked the behavior described against the 6000.6 and 6000.7 build code. I also checked the circularrefs.json schema, and the claim that each fileId matches a StableId in ContentLayout.json, against a real 6.7 build.