Use build callbacks
Implement build callbacks to insert custom behavior into the build process.
読み終わるまでの所要時間 5 分最終更新 11日前
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 directory or AssetBundle content builds.
For a Player build, Unity invokes the callbacks whether you trigger the build from the Build Profiles 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 for Player builds
The following table lists the build callbacks that Unity supports for Player builds:
Callback | Method | Description |
|---|---|---|
| | Add files and perform custom setup before the build starts. |
| | Called at the start of a build. |
| | Called at the end of the build. |
| | Remove assemblies from the build. |
| | Read or patch managed assemblies after compilation. |
| | Called while Unity processes each scene for the build. |
| | Filter the list of shader variants to reduce shader build times. |
| | Similar to |
| | Configure the managed code stripping stage of a Player build. |
| | Called if the Player is launched as a final step of the build. |
Supported callbacks for content builds
Content builds don't include managed assemblies, so they invoke only a subset of the interface-based callbacks as follows:
IPreprocessBuildWithContextIPostprocessBuildWithContextIProcessSceneWithReportIPreprocessShadersIPreprocessComputeShaders
The attribute callback also runs during content builds.
PostProcessSceneThese callbacks are invoked for AssetBundles built with , and for content directory builds.
BuildPipeline.BuildAssetBundlesAssetBundles built with the Scriptable Build Pipeline package, which the Addressables package uses, invoke only the following callbacks:
- (including
IProcessSceneWithReport)[PostProcessScene] IPreprocessShadersIPreprocessComputeShaders
Modify assets in a callback
If you want to modify assets within build callbacks before a build starts, for example in an implementation of , use 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.
BuildPlayerProcessorAssetDatabase.SaveAssetsOnly modify assets and data within the scope of the callback. For example, use to modify the scene being processed, but not any assets. The shader preprocessing callbacks ( and ) are designed to filter shader variants. Asset modifications aren't permitted within these callbacks.
IProcessSceneWithReportOnProcessShaderOnProcessComputeShaderFail a build from a callback
To deliberately fail a build from a callback, do one of the following:
- Throw a 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.
BuildFailedException - Log an error, for example with . A logged error fails the build only when the build uses strict mode.
Debug.LogError
Each build type has its own strict mode flag: for Player builds, for AssetBundle builds, and for content directory builds. Unity sets automatically when you use Build and Run.
BuildOptions.StrictModeBuildAssetBundleOptions.StrictModeBuildContentOptions.FailBuildWhenErrorsLoggedBuildOptions.StrictModeUnity records information, warning, and error messages in the Editor log. Most build messages are also captured in the and the file stored in the . Messages logged from currently appear only in the Editor log.
BuildReportBuildLog.jsonlBuildHistoryBuildPlayerProcessor.PrepareForBuildCallback ordering
You can use 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 has an order value of 2, it runs after another callback that has an order value of 1.
IOrderedCallback.callbackOrderIPreprocessBuildWithContextIPreprocessBuildWithContextBuild callbacks during incremental builds
The following build callbacks happen during the content step of a Player build:
- Scene callbacks:
IProcessSceneWithReport.OnProcessScene - Shader callbacks: ,
IPreprocessShaders.OnProcessShaderIPreprocessComputeShaders.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 or increment its version so the next build runs the callbacks again.
BuildCallbackVersionAttributeIf you are building a content directory, and your modifications depend on other assets in the project, call the methods in your callback implementations so that Unity runs the callback again if any of those assets change.
BuildPipelineContextSome 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) is the equivalent of[PostProcessScene]. It runs during Player, AssetBundle, and content directory builds.IProcessSceneWithReport - (
PostProcessBuildAttribute) is the equivalent of[PostProcessBuild]. It runs only during Player builds.IPostprocessBuildWithReport
For new code, use the interface callbacks. They receive the scene and build report as parameters, and and also run for AssetBundle and content directory builds.
IPreprocessBuildWithContextIPostprocessBuildWithContext