Use build callbacks

You can implement build callbacks to insert custom behavior into the build process. Unity invokes these callbacks during Player builds, and invokes a subset of them during content-only builds such as AssetBundle and content directory builds.

For a Player build, Unity invokes the callbacks whether you trigger the build from the Build ProfilesA set of customizable configuration settings to use when creating a build for your target platform. More info
See in Glossary window, from a custom menu, or from a command line build. Build callbacks are useful when adding custom build behavior for a package used across different Unity projects.

Supported callbacks

The following table lists the build callbacks that Unity supports for Player builds:

Player builds support all of these callbacks. Content-only builds, which don’t include managed assemblies, invoke only a subset of the interface-based callbacks as follows:

• IPreprocessBuildWithContext
• IPostprocessBuildWithContext
• IProcessSceneWithReport
• IPreprocessShaders
• IPreprocessComputeShaders

The PostProcessScene attribute callback also runs during content-only builds.

The set of callbacks a content-only build invokes depends on how you build the AssetBundles. AssetBundles built with BuildPipeline.BuildAssetBundles invoke all the callbacks in the previous list. AssetBundles built with the Scriptable Build Pipeline package, which the Addressables package uses, invoke only IProcessSceneWithReport (including [PostProcessScene]), IPreprocessShaders, and IPreprocessComputeShaders. They don’t invoke IPreprocessBuildWithContext or IPostprocessBuildWithContext.

If you want to modify assets within build callbacks before a build starts, for example in an implementation of BuildPlayerProcessor, use AssetDatabase.SaveAssets to save those changes to disk. Failing to save asset modifications can result in undefined behavior, build indeterminism, cache inconsistencies, and increased build times. For more information about build determinism, refer to Build determinism.

Only modify assets and data within the scope of the callback. For example, use IProcessSceneWithReport to modify the scene being processed, but not any assets. The shader preprocessing callbacks (OnProcessShader and OnProcessComputeShader) are designed to filter shader variants. Asset modifications aren’t permitted within these callbacks.

Fail a build from a callback

To deliberately fail a build from a callback, do one of the following:

• Throw a BuildFailedException to fail the build. It reports a clear message without a call stack and fails the build whether or not the build uses strict mode. Throwing a different exception type isn’t guaranteed to stop the build: outside strict mode, some callbacks log it and continue.
• Log an error, for example with Debug.LogError. A logged error fails the build only when the build uses strict mode.

Each build type has its own strict mode flag: BuildOptions.StrictMode for Player builds, BuildAssetBundleOptions.StrictMode for AssetBundle builds, and BuildContentOptions.FailBuildWhenErrorsLogged for content directory builds. Unity sets BuildOptions.StrictMode automatically when you use Build and Run.

Unity records information, warning, and error messages in the Editor log. Most build messages are also captured in the BuildReport and the BuildLog.jsonl file stored in the BuildHistory. Messages logged from BuildPlayerProcessor.PrepareForBuild currently appear only in the Editor log.

Callback ordering

You can use IOrderedCallback.callbackOrder to control the execution order of a build callback relative to other implementations of the same callback interface. Unity sorts the callbacks from lowest to highest order value, and you can assign any negative or positive integer value. For example, if your implementation of IPreprocessBuildWithContext has an order value of 2, it runs after another IPreprocessBuildWithContext callback that has an order value of 1.

Build callbacks during incremental builds

The following build callbacks happen during the content step of a Player build:

• Scene callbacks: IProcessSceneWithReport.OnProcessScene
• Shader callbacks: IPreprocessShaders.OnProcessShader, IPreprocessComputeShaders.OnProcessComputeShader

When Unity reuses content from a previous build, it doesn’t trigger these callbacks again because they already ran during the previous build. Unity caches any content change caused by the callback in the output from the previous build.

When you change a callback’s code, add BuildCallbackVersionAttribute or increment its version so the next build runs the callbacks again.

If you are building a content directory, and your modifications depend on other assets in the project, call the BuildPipelineContext methods in your callback implementations so that Unity runs the callback again if any of those assets change.

Some callback implementations from a package or third-party code might not be deterministic. In that case, perform a clean build, or manually modify the content of one of the scenes or assets included in the build to force the callbacks to run again.

Other build callbacks that run before or after the content stage might trigger again during incremental builds. These callbacks must handle running multiple times on the same build output. For example, if a callback adds entries to an Android app manifest, it must check if those entries already exist to avoid creating an invalid manifest file.

Attribute-based callbacks

Unity also supports two older attribute-based callbacks. Each one is an equivalent of an interface callback, so Unity tracks and invokes the attribute together with its matching interface and with the same behavior:

• PostProcessSceneAttribute ([PostProcessScene]) is the equivalent of IProcessSceneWithReport. It runs during Player, AssetBundle, and content directory builds.
• PostProcessBuildAttribute ([PostProcessBuild]) is the equivalent of IPostprocessBuildWithReport. It runs only during Player builds.

For new code, use the interface callbacks. They receive the scene and build report as parameters, and IPreprocessBuildWithContext and IPostprocessBuildWithContext also run for AssetBundle and content directory builds.

Additional resources

• Customize the build pipeline
• Create a custom build script
• Create a clean build