Updated BuildReport API in Unity 2020.1 beta gives more details about the build times of your project, breaking them down to the asset level. This information will help you optimize your iteration times.
Jump to BuildOptions.DetailedBuildReport manual page to check out directly how to use the new API, and drop the Build Report Inspector into your project to inspect your new build reports easily.
Build times for projects with lots of content can become quite long. This makes iteration slower, especially when testing on several platforms.
Unity 2018.1 introduced the BuildReport API that gives information about the Unity build process. Since then, the BuildReport object returned from BuildPipeline.BuildPlayer has information about the steps happening during the build process, which assets contribute to the build size, and which engine modules are included in the build.
In Unity 2020.1, if you pass the new BuildOptions.DetailedBuildReport option to the API function BuildPipeline.BuildPlayer, you will have more information available in the BuildReport object, such as more detailed build steps, and a summary of which scenes are using the assets in the build.
Build Report Inspector package
The BuildReport API makes it possible to write custom tools to analyze your project’s build times.
One approach to learning how to use it is by looking at the Build Report Inspector provided by Unity to illustrate its usage.
Build Report Inspector can be added to a project from the Unity Package Manager window. Check Show Preview Packages in the Advanced menu and look for Build Report Inspector on the list. Finally, click the “Install” button.
Build Report Inspector in the Package Manager
You can also get the Build Report Inspector script (including future experimental versions), as well as contribute to improving it, from this GitHub repository.
Build Report Inspector adds a command menu Open Last Build Report to the Window menu. Clicking command menu Open Last Build Report copies the build report file generated during the last build under a location visible by the project, and selects it to make its contents visible in the inspector:
Simple Build Report for an incremental build of project BoatAttack
Additional details in BuildReport.steps
When building with the BuildOptions.DetailedBuildReport option, new build steps are listed in BuildReport.steps.
Build steps shorter than 1ms will not be listed, as this would create a lot of noise.
Those newly reported steps include:
- Assets load and write times for the build
- GarbageCollection times during the build
- Time to process asset dependencies
- Custom Asset Bundle build details and times
BuildOptions.DetailedBuildReport manual page has an example of Editor script showing how to use the option.
Here is how we can modify that example to build the BoatAttack project with the BuildOptions.DetailedBuildReport flag:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
using UnityEditor; using UnityEngine; public class DetailedBuildReportExample : MonoBehaviour { [MenuItem("Build/DetailedBuildReport example")] public static void MyBuild() { BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions(); buildPlayerOptions.scenes = new[] { "Assets/scenes/MainMenu.unity", "Assets/scenes/_levels/level_Island.unity" }; buildPlayerOptions.locationPathName = "DetailedReportBuild/MyGame.exe"; buildPlayerOptions.target = BuildTarget.StandaloneWindows64; buildPlayerOptions.options = BuildOptions.DetailedBuildReport; var buildReport = BuildPipeline.BuildPlayer(buildPlayerOptions); } } |
If we add the above script to the Boat Attack project’s Assets/Editor folder and click Editor menu Build/DetailedBuildReport example, a project build will begin. At the end of the build, additional data will be included in the Build Report.
Now if we use the Window/Open Last Build Report command like described in the previous section, we can see that additional steps have been included in the report:
Detailed Build Report for an incremental build of project BoatAttack
The additional information makes it possible to pinpoint which steps and which assets take more time when building the project.
After identifying those assets, you can swap them with lighter “development” versions, for better iteration times.
Find all scenes using a specific asset
In the process of replacing heavy assets, it might be useful to know exactly which scenes in the build include a given asset.
If the BuildOptions.DetailedBuildReport option was used during the build, this information is exposed in the BuildReport as member BuildReport.scenesUsingAssets.
If you added the Build Report Inspector to your project, you can review this information from the ScenesUsingAssets tab:
List of scenes using specific assets in the BoatAttack project
During development, replacing those assets by smaller ones, or creating build profiles without the scenes referencing them, will help in reducing iteration times.
Unity 2020.1 beta and webinar
Use Detailed Build Reports to discover what is making up your project build times, and use this information to optimize your iteration loops. Try this feature in Unity 2020.1 beta and let us know what you think. On April 20 at 9:00 am PST (6:00 pm CET), we will be hosting a 2020.1 beta webinar for people interested in a guided tour of the features and updates. You can register here for the webinar. If you have any additional questions about this or other features in 2020.1, we will be hosting a Q&A following our 2020.1 beta overview webinar. You can drop your questions in this forum thread.
9 replies on “Build times: Get the details”
Could you improve build time for HDRP/URP prjects? Moreover, could you reduce size of projects?
Hi Valarus, the screenshots in this blog post are taken from project https://github.com/Verasl/BoatAttack , which is using the Universal Render Pipeline.
You can definitely get Detailed Build Times for projects using Scriptable Render Pipelines.
A cause of long build times that I have seen several times is a high number of shader variants in the project.
You can use Shader Variants Stripping to reduce that number and improve your build times (and size). You can find more information about Shader Stripping from the following links:
https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@9.0/manual/shader-stripping.html
https://blogs.unity3d.com/2018/05/14/stripping-scriptable-shader-variants/
Is there any reason not to use the DetailedBuildReport option? Just wondering why that’s an option. The detailed report is much appreciated, thank you!
Thanks for your comment Peter.
If your build contains a lot of assets, the BuildOptions.DetailedBuildReport option can make the Build Report file much bigger.
The first time you inspect your project’s Build Report, you might prefer to start with a simpler overall view.
We made this feature an option, so that you can still start from the simpler view ; and later decide to dive into more details when you need.
Does the detailed report affect the build time? I know it sounds counterproductive, I’m curious about how is differs from normal reporting: Is there more info being pulled, or more analytics running, or just more already existing data being dumped into the report?
Hi Joaquin, the build steps executed by Unity during a call to BuildPlayer are the same when BuildOptions.DetailedBuildReport is disabled or enabled.
For each significant build step, we store a message into an internal list. We include that list to the final Build Report at the end of the build.
When you keep BuildOptions.DetailedBuildReport disabled, many of those steps will be executed silently, and no message about them will get into the list.
If you enable BuildOptions.DetailedBuildReport, we will include more new messages in the list. We will therefore copy more messages (strings) during the build process. We also execute a final loop to resolve the names of objects appearing in the messages.
When I checked on project https://assetstore.unity.com/packages/templates/tutorials/3d-game-kit-115747 for example, build time was 3% longer with BuildOptions.DetailedBuildReport enabled.
Thanks for your great answer!
So does this support addressables yet? Right now there is 0 info about addressables build times or build sizes.
Hi Mike, a future version of the Addressables package (maybe 1.8) will output two new report files containing timings and notes about a build.
At first the format of these new files will slightly differ from the format of the player BuildReport, but we are thinking about integrating them together.
With current Addressables package (1.7.5), you can inspect the size of the files on your disk: you can obtain their paths from the FileRegistry class.