When you build a Player in Unity, the UnityLinker process runs to reduce the size of the assemblies by removing unused types. This process can strip the following:
MonoBehaviour or ScriptableObject. Unity can strip these from core Unity assemblies like UnityEngine.dll and Unity.dll, but preserves them in custom assemblies once those assemblies are marked as used.The effect that code stripping has on content appears in the Player as null reference exceptions, missing type errors, or crashes. Content that you build separately from the Player can’t use types that have been stripped out of the Player build. This applies to AssetBundle content, Addressables content, and content directories.
You can use the Build Report Inspector’s Stripping tab to inspect which modules and types have been preserved in a Player build.
You can prevent the linker from stripping code in the following circumstances:
A content directory that you build with BuildPipeline.BuildContentDirectory can contain types that aren’t in any scene or asset in the Player build. Unity might strip those types from the Player, so the content fails to load at runtime.
Each content directory build records the C# types and the Unity object types it uses in a ScriptsOnlyCache.yaml file in its build report directory. Because this record includes the Unity object types, it also preserves the modules those types belong to.
To preserve these types in the Player, build the content directory before the Player, then pass the content directory’s build report directory to the Player build with one of the following APIs:
BuildPlayerOptions.previousBuildReportDirectories when you exclusively trigger Player builds from a custom build script, rather than from the Build Profiles window.BuildPlayerContext.AddPreviousBuildReportDirectory works for both custom build scripts and the Build Profiles window, because you call it from a BuildPlayerProcessor build callback. You can build the content directory in the callback, or locate the build report directories of earlier builds another way, such as through the BuildHistory API or your own project configuration.Both APIs take the build report directory, not the path to the ScriptsOnlyCache.yaml file inside it. If the directory isn’t a valid build report directory, the Player build fails with an error.
For a complete build script that builds a content directory and preserves its types in the Player, refer to Create a custom build script.
This section applies to AssetBundles that you build with BuildPipeline.BuildAssetBundles, which produces a .manifest file. For AssetBundles that you build with Addressables or the Scriptable Build Pipeline, which use a link.xml file instead of a manifest, refer to Prevent code stripping of types used in Addressables.
Unity might strip a Unity object type that’s present in AssetBundles, but not in any scene or asset included in a Player build. This means that content from the AssetBundle might work when testing in Play mode, or on builds with minimal code stripping, but errors or crashes occur in a Player built with code stripping enabled.
To resolve this, you can create a custom build script that directly includes the AssetBundle’s manifest file, as follows:
.manifest file for each AssetBundle, and a root .manifest file with the same name as the output folder..manifest file into the Player build process with the BuildPipeline.BuildPlayer API.The manifest lists the types of Unity objects that the AssetBundles use, so this approach also preserves the modules those types belong to.
For more information, refer to AssetBundle file format reference and BuildPlayerOptions.assetBundleManifestPath.
You can also use the Preserve attribute, or manually author a link.xml file in your project, to further influence the code stripping behavior.
This section applies when Addressables builds AssetBundles. When you configure Addressables to build content directories instead, follow Prevent code stripping of types used in content directories.
If a type of Unity object is present in content built with Addressables, but not in any scene or asset built into the Player, then Unity might strip that type.
Addressables automatically generates a link.xml file inside the Library/com.unity.addressables folder describing types used in the content. The Player build takes this link.xml file into account, provided the Addressables content has been built before, or at the same time as, the Player build.
You can also use the Preserve attribute, or manually author a link.xml file in your project, to further influence the code stripping behavior.
If you need to use types from a module in an Addressables or Scriptable Build Pipeline AssetBundle build, make sure the Player build includes some content that references that module. For example, to keep the Physics module, add a component such as a Rigidbody or Collider to a GameObject in a scene included in your build. This creates a dependency that the Player build process recognizes, and preserves the module.
This is required because you can’t use a link.xml file to prevent entire Unity modules (for example AI or Physics) from being stripped.
This workaround isn’t required for AssetBundles built with BuildPipeline.BuildAssetBundles or for content directory builds, including content directories built by Addressables. Both record the Unity object types that they use, so passing the manifest or build report directory to the Player build also preserves the modules those types belong to.
Both Player builds and content directory builds record the types they use in a ScriptsOnlyCache.yaml file, which you can look at to diagnose code stripping issues:
Library/PlayerDataCache folder to support the Incremental build pipeline, which can reuse the content from a previous Player build. In that case the Player build passes the cached type usage from the file to the Unity linker.
Note: The ScriptsOnlyCache.yaml file uses an internal format that might change in future Unity versions. To control code stripping, use link.xml files in your project instead of modifying this file directly.