Search Unity

Topics covered

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:

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"; = 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.

April 9, 2020 in Technology | 4 min. read
Topics covered