How code stripping affects content
Understand how your managed code stripping configuration can affect content builds and how to preserve code your content depends on.
Read time 6 minutesLast updated 12 days ago
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:
- Entire C# types such as classes derived from or
MonoBehaviour. Unity can strip these from core Unity assemblies likeScriptableObjectandUnityEngine.dll, but preserves them in custom assemblies once those assemblies are marked as used.Unity.dll - Regular C# structures and classes.
- Portions of classes (for example, methods that aren't used).
- Entire Unity modules, such as AI or Physics, if no type from that module is referenced.
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:
- Prevent code stripping of types used in content directories
- Prevent code stripping of types used in AssetBundles
- Prevent code stripping of types used in Addressables
- Prevent module code stripping
Prevent code stripping of types used in content directories
A content directory that you build with 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.
BuildPipeline.BuildContentDirectoryEach content directory build records the C# types and the Unity object types it uses in a file in its build report directory. Because this record includes the Unity object types, it also preserves the modules those types belong to.
ScriptsOnlyCache.yamlTo 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:
- Use when you exclusively trigger Player builds from a custom build script, rather than from the Build Profiles window.
BuildPlayerOptions.previousBuildReportDirectories - works for both custom build scripts and the Build Profiles window, because you call it from a
BuildPlayerContext.AddPreviousBuildReportDirectorybuild callback. You can build the content directory in the callback, or locate the build report directories of earlier builds another way, such as through theBuildPlayerProcessorAPI or your own project configuration.BuildHistory
Both APIs take the build report directory, not the path to the file inside it. If the directory isn't a valid build report directory, the Player build fails with an error.
ScriptsOnlyCache.yamlFor a complete build script that builds a content directory and preserves its types in the Player, refer to Create a custom build script.
Prevent code stripping of types used in AssetBundles
This section applies to AssetBundles that you build with , which produces a file. For AssetBundles that you build with Addressables or the Scriptable Build Pipeline, which use a file instead of a manifest, refer to Prevent code stripping of types used in Addressables.
BuildPipeline.BuildAssetBundles.manifestlink.xmlUnity 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:
- Build the AssetBundle before building the Player. The output folder includes one file for each AssetBundle, and a root
.manifestfile with the same name as the output folder..manifest - Pass the path of the root file into the Player build process with the
.manifestAPI.BuildPipeline.BuildPlayer
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.assetBundleManifestPathYou can also use the Preserve attribute, or manually author a file in your project, to further influence the code stripping behavior.
link.xmlPrevent code stripping of types used in Addressables
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 file inside the folder describing types used in the content. The Player build takes this file into account, provided the Addressables content has been built before, or at the same time as, the Player build.
link.xmlLibrary/com.unity.addressableslink.xmlYou can also use the Preserve attribute, or manually author a file in your project, to further influence the code stripping behavior.
link.xmlPrevent module stripping
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 file to prevent entire Unity modules (for example AI or Physics) from being stripped.
link.xmlThis workaround isn't required for AssetBundles built with 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.
BuildPipeline.BuildAssetBundlesType usage records
Both Player builds and content directory builds record the types they use in a file, which you can look at to diagnose code stripping issues:
ScriptsOnlyCache.yaml- A Player build writes this file to the 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.
Library/PlayerDataCache - A content directory build writes this file to its build report directory. When you pass that directory to a Player build, the Player build passes the recorded type usage to the Unity linker. For more information, refer to Build history file reference.
Note
The file uses an internal format that might change in future Unity versions. To control code stripping, use files in your project instead of modifying this file directly.
ScriptsOnlyCache.yamllink.xml