BuildHistory

Description

Provides access to the build history generated during builds.

This class provides programmatic access to the build history: for each Player or Content Directory build, Unity creates a "build report directory" that holds the BuildReport file and the supporting data captured during that build. Use this class to enumerate builds, query their summaries, and locate the files in their build report directories. For a conceptual overview of the build history and a description of each file it contains, refer to Build history.

Build report directories are self-contained and portable. The BuildHistory API can read a build report directory even if a different machine or a different Unity project produced it, so you can consolidate build reports from multiple build servers into a single build history folder.

Unity assigns each build a unique GUID, which the BuildHistory API uses to precisely identify each build. For more information, refer to BuildReportSummary.BuildSessionGUID.

Retention policy

To prevent unbounded growth of the build history folder, Unity applies a retention policy at the start of each Player and Content Directory build. BuildHistory.BuildHistoryLimit sets the maximum number of builds to retain. When a new build pushes the count over the limit, the oldest entries are deleted. Set the limit to 0 to disable automatic deletion. You can also invoke the policy manually with BuildHistory.ApplyRetentionPolicy.

Build lifecycle

For Player builds, BuildPlayerProcessor.PrepareForBuild runs before the Player build is added to the history. This allows any content builds triggered during that callback to appear in the history before the Player build itself, resulting in a chronological ordering.

Unity adds a build to the history early in the build process (but after BuildPlayerProcessor.PrepareForBuild) and sets the result to BuildResult.Pending. If the Editor process terminates during a build, the build remains in the history with its initial Pending result.

Some BuildHistory methods, for example BuildHistory.TryGetBuildReportDirectory and BuildHistory.TryGetFilePath, are available for use in the IPreprocessBuildWithReport and IPostprocessBuildWithReport build callbacks.

When the build completes, the BuildReportSummary is updated with the final result (BuildResult.Succeeded, BuildResult.Failed, or BuildResult.Cancelled).

Additional resources: BuildReportSummary, BuildReport

using System;
using System.Text;
using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;
using UnityEngine;

/// <summary>
/// Example showing how to scan build history and generate a statistics report.
/// </summary>
public class BuildHistoryStatsExample
{
    [MenuItem("Example/BuildHistory/Print Build Statistics")]
    static public void PrintBuildStatistics()
    {
        int buildCount = BuildHistory.GetBuildCount();

        if (buildCount == 0)
        {
            Debug.Log("No builds found in build history.");
            return;
        }

        // Collect statistics by scanning the summary of all builds
        long totalTimeMs = 0;
        int succeededCount = 0;

        GUID[] allBuilds = BuildHistory.GetAllBuilds();
        foreach (var buildGuid in allBuilds)
        {
            BuildReportSummary summary = BuildHistory.GetBuildSummary(buildGuid);
            totalTimeMs += summary.TotalTimeMs;
            if (summary.BuildResult == BuildResult.Succeeded)
                succeededCount++;
        }

        var sb = new StringBuilder();
        sb.AppendLine($"=== Build History Statistics ===");
        sb.AppendLine($"Total Builds: {buildCount}");

        double successRate = (double)succeededCount / buildCount * 100;
        sb.AppendLine($"  Success rate: {successRate}%");

        TimeSpan totalTime = TimeSpan.FromMilliseconds(totalTimeMs);
        sb.AppendLine($"Total Build Time: {totalTime:g}");
        TimeSpan averageTime = TimeSpan.FromMilliseconds(totalTimeMs / buildCount);
        sb.AppendLine($"Average Build Time: {averageTime:g}");

        Debug.Log(sb.ToString());
    }
}

Static Properties

Static Methods