superunitybuild/buildtool

A powerful automation tool for quickly and easily generating builds with Unity.

SuperUnityBuild

A powerful automation tool for quickly and easily generating builds with Unity.

Unity Forums Thread | Documentation Wiki | OpenUPM package

SuperUnityBuild is a Unity utility that automates the process of generating builds. It's easy and quick enough to use on small apps, but it's also powerful and extensible enough to be extremely useful on larger projects. The key to this flexibility lies in SuperUnityBuild's configurable degrees of granularity and its BuildActions framework which allows additional operations to be added into the build process.

Features:

• Manage and Build Multiple Versions - If you're targetting more than one platform or distribution storefront, the build process can quickly become very cumbersome with Unity's built in tools. SuperUnityBuild makes it easy to manage a wide array of build configurations targetting any number of versions, platforms, architectures, or distribution methods.
• One-Click Batch Builds - Easily kick-off batch builds for all or a specific subset of your build configurations.
• Expanded Build Capability - SuperUnityBuild offers many features not available in Unity's built in build workflow such as version number generation, and the BuildAction framework provides options for even more expanded build capabilities like automated file copying/moving, creating zip files, and building AssetBundles.
• Quick Initial Setup - If all you need is the bare essentials, you can be up and running in minutes. SuperUnityBuild scales to fit your project's specific needs whether it be large or small.
• Highly Extensible and Customizable - SuperUnityBuild's BuildAction framework provides simple hooks for adding in your own additional functionality.
• Free and Open-Source - Some similar tools available only on the AssetStore are as much as $50+.

Basic Usage

Requires Unity 2020.3 or higher. Supports building for Windows, macOS, Linux, iOS, Android, UWP and WebGL.

Installation

Official releases of SuperUnityBuild can be installed via Unity Package Manager from the OpenUPM package registry. See https://openupm.com/packages/com.github.superunitybuild.buildtool/ for installation options.

You can also download the source zip of this repository and extract its contents into your Unity project's Packages directory to install SuperUnityBuild as an embedded package.

You may also want to install the optional BuildActions package to expand SuperUnityBuild's capabilities.

Upgrading from previous versions

When upgrading to a new major version, it is strongly recommended to remove all traces of the previous SuperUnityBuild installation by uninstalling the package, deleting the current Build Settings asset (stored in the Assets/SuperUnityBuild directory by default), restarting Unity, installing the new release and then allowing SuperUnityBuild to create a fresh Build Settings asset.

Upgrades to new patch or minor versions (i.e. versions without breaking changes) can be performed in-place by simply updating the package.

Setup

See Standard Usage in the wiki.

Customizing and Expanding

Creating BuildActions

See Build Actions in the wiki for details.

Command Line Interface

See Command Line Interface in the wiki.

Contributing

Bug reports, feature requests, and pull requests are welcome and appreciated.

Credits

Creator

• Chase Pettit - GitHub, Twitter

Maintainer

• Robin North - GitHub

Contributors

You can see a complete list of contributors at https://github.com/superunitybuild/buildtool/graphs/contributors

License

All code in this repository (buildtool) is made freely available under the MIT license. This essentially means you're free to use it however you like as long as you provide attribution.

buildtool's Issues

Support for Unity 2017.3

There are a lot of warnings right now:

warning CS0618: `UnityEditor.BuildTarget.StandaloneOSXIntel' is obsolete: `StandaloneOSXIntel has been removed in 2017.3'
warning CS0618: `UnityEditor.BuildTarget.StandaloneOSXIntel64' is obsolete: `StandaloneOSXIntel64 has been removed in 2017.3'

etc.

Having the SuperUnityBuild editor window open in the inspector causes noticeable lag in play mode

It seems to only happen when the window is active -- if it's part of a tab group and not activated there's no lag. It doesn't appear to affect the actual framerate (according to the stats dropdown) but it seems to cause a bit of UI lag. Feels like every .25 seconds or something.

It seems to lag not only the play window, but other UI responsiveness such as editing text fields.

Cpu spikes linux master

Downloaded the master branch & tested it out on Linux. It built correctly when I added assembly definitions.

But I've encountered a performance error. I think it's either Linux related, or Unity 2020.2.5f1 related.

RuntimeType.IsAssignableFrom() gets called 54000 times. Also, Assembly.GetTypes() 320 times. Which together take around 100ms to update the editor.

Here's the entire tree

Script Compilation Defines appear to have stopped working

I'm not sure what happened, but I removed a script compilation define from one of the builds, and now no custom defines are coming through when building.

Any ideas on how to debug?

I've clicked the "Refresh BuildConstants and Apply Defines" button and that appears to apply the script defines for that one selected project as the defaults in the build settings, which is not what I want I think.

Thanks in advance

Import scene list from Build Settings

It would be really nice to import the scenes I added to Build Settings (unity's default way of building) to the SuperUnityBuild SceneList

Update README

• Document installation via UPM (using OpenUPM: https://openupm.com/packages/com.github.superunitybuild.buildtool/)
• Update releases
• Update credits

Update wiki documentation

The wiki documentation could do with updating to document the various changes and improvements made to SuperUnityBuild in the last few years. This should include all-new screenshots using the new Unity Editor skin.

Build Action filter UI shown for 'Single Run' actions

As per #63 (comment), 'Single Run' build actions should not present the filter UI to users, as their filter conditions are not evaluated when performing these actions

Can't add any pre/post actions

I don't see any buttons to add actions.
Linux, Unity 2018.4

Custom build paths

An option to easily specify the results of $ARCHITECTURE in the build path settings would be nice. A simple wiki entry as to where and how the variables are stored would be enough. For example changing "Windows x86" to "Win32".

Plugin does not appear in Top Bar in 2017.2.0f3

Unlike previous versions, the controls for the plugin are accessible once the user selects it from the Window Tab.

using Unity 2017.2.0f3 on Windows 10

Update iOS build platform

Whilst a working iOS build platform was added in #52, I overlooked that it didn't make use of the build variant settings, and may benefit from having some additional variant options (e.g. Target Device).

Unity PostProcessBuild not firing

Hi,
Interesting alternative to UCB for those with a lot of Build targets, but I am running into one issue. The PostProcessBuild attribute methods are not being called for each platform after the build completes in 2017.3

Not sure if I am missing something.

thanks!

JSON Import/Export

It may be nice to be able to import/export build configurations via a JSON file. This JSON file could then also be directly used via the command-line. Some people may also just simply prefer editing the JSON formatted files rather than using the editor interface.

This may require some serialization tweaks/cleanup to work properly.

This enhancement idea is inspired in part by criticisms made in this article: https://libsora.so/posts/make-unity-build-system/

After upgrading to Unity 2018, releaseType.sceneList no longer has a "GetSceneList()" function

On this line:

string error = BuildPipeline.BuildPlayer(releaseType.sceneList.GetSceneList(), Path.Combine(buildPath, exeName), architecture.target, options);

SceneList does not have a "GetSceneList()" function

Is there any alternative way to get the information that BuildPlayer needs to run?

Wiki links from UI have incorrect hash id.

Build actions give this link: https://github.com/Chaser324/unity-build/wiki/Parameter-Details#build-actions
Should be: https://github.com/Chaser324/unity-build/wiki/Parameter-Details#user-content-prepost-build-actions

Version 0.9.8

Post build actions per distribution

Is it possible to perform a post build action after each distribution rather than waiting for the entire thing to finish? I have a post build action that uploads the build to Steamworks, and another that uploads to GOG Galaxy. Both actions happen at the same time and the Steamworks cmd tool interferes with GOG Galaxy so I always have to launch one manually afterwards.

Improve SceneListDrawer performance.

As noted in PR #18 and #19, SceneListDrawer causes significant performance issues on large projects.

Does not build to Linux x64

No matter what is checked, it always builds to Linux x86. Universal is being depreciated.

Complete implementation of command line interface.

Update for compatibility with latest Unity 2017.

As noted in #21, there are some functions from Unity 5.x that are now obsolete in 2017.

Complete Android, iOS, WebGL BuildPlatforms.

• Android
• WebGL
• iOS

Set scene list when applying a configuration.

When you click the "Refresh BuildConstants and Apply Defines" it should also set the necessary scenes in the editor's Build Settings.

Auto-Generate Build not working

I'm not sure what I'm doing wrong here. When I press build, my builds complete successfully and upload to itch (via the plugin) but the build number does not advance.

Is there something I am doing wrong?

Enabling an action after disabling it prior stops it from being performed

I noticed that after I disabled a Post-build action (in this case, UploadItch), when I enabled it again, the action would still be skipped.

Adding a new action and copying over the properties works.

Anyone else seeing the same thing?

Building wipes out scripting define symbols

I have multiple assets (like the post processing stack) that set scripting define symbols in ProjectSettings/ProjectSettings.asset.

Building with this tool always wipes them out. It would be nice if it could just add its own symbols to the list rather than replacing them. I can't really move the symbols into SuperUnityBuild because the assets themselves automatically define these symbols. Many assets seem to do it so it is apparently a common pattern.

This issue is also described here: #12 (comment)

Here's my git diff after running a build:

--- a/ProjectSettings/ProjectSettings.asset
+++ b/ProjectSettings/ProjectSettings.asset
@@ -118,7 +118,7 @@ PlayerSettings:
     16:10: 1
     16:9: 1
     Others: 1
-  bundleVersion: 1010
+  bundleVersion: 1011
   preloadedAssets: []
   metroInputSource: 0
   wsaTransparentSwapchain: 0
@@ -553,7 +553,7 @@ PlayerSettings:
   webGLCompressionFormat: 1
   webGLLinkerTarget: 1
   scriptingDefineSymbols:
-    1: DOTWEEN_TMP;DOTWEEN_TMP;UNITY_POST_PROCESSING_STACK_V2;FIRST_PERSON_CONTROLLER;THIRD_PERSON_CONTROLLER;ULTIMATE_CHARACTER_CONTROLLER_SHOOTER;ULTIMATE_CHARACTER_CONTROLLER_MELEE;AMPLIFY_SHADER_EDITOR;GPU_INSTANCER
+    1: BUILD_TYPE_PRIMARY;BUILD_PLATFORM_PC;BUILD_ARCH_WINDOWSX64
     4: DOTWEEN_TMP
     7: UNITY_POST_PROCESSING_STACK_V1;DOTWEEN_TMP;UNITY_POST_PROCESSING_STACK_V2
     13: UNITY_POST_PROCESSING_STACK_V1;DOTWEEN_TMP;UNITY_POST_PROCESSING_STACK_V2

Refactor BuildPlatform to make it easier to work with and customize.

Creating a class works well enough, but some people may be less inclined to tangle with code. Converting BuildPlatform into a ScriptableObject (or a field in another ScriptableObject) that can be instantiated and customized from the inspector may work better.

How to get the version set in Super Unity Build at runtime (script)?

I tried using Application.version but that just gets the one unity sets in the player settings and not the one set in Super Unity Build. How do you get it? (if you can)

Add support for custom defines.

User should be able to add/toggle compiler defines.

Improve inspector for settings assets.

Right now the inspectors are the bare minimum. Some custom editor and property drawers could improve usability a lot.

Advanced build path support.

Should support things like making a different folder per version or build date.

Linux build does not work

Although I have Linux enabled, it doesn't build to linux.

It also doesn't show that there are 6 enabled builds as opposed to 4 (Mac and Windows for two releases).

Continuous Error

I continuously get this error Unity 207.1

Assets/UnityBuild/Editor/Build/Settings/UI/ProjectConfigurationsDrawer.cs(177,53): warning CS0618: `UnityEditor.EditorUserBuildSettings.SwitchActiveBuildTarget(UnityEditor.BuildTarget)' is obsolete: `Please use SwitchActiveBuildTarget (BuildTargetGroup targetGroup, BuildTarget target)'

BuildAddressables issues

I'm struggling to get BuildAddressables working properly. Occasionally I'm seeing the wrong Addressable sets copied when building multiple platforms; OSX getting the Android addressables, etc). BuildAddressables is tagged as a pre-build action.

Enhancement: Change VR/XR Player Settings based on Distribution

Along the same lines as Issue #6 and #27, it would be great if you could also set VR/XR Player settings according to the existing Filter system.

For example, we could re-arrange the preferred SDK order based on the distribution platform, or even leave them all out except for "None" for a non-VR build.

Enable/disable option for BuildActions.

Although the filter can be used to fulfill a similar purpose, it might be nice to just have a checkbox in the interface to allow any given BuildAction to be temporarily disabled. Without this, I think some users may be inclined to just temporarily delete a BuildAction, but this is an inefficient workflow since it will cause all of those settings to be lost.

Spacing issue with Unity's new UI in 2019.3x

https://crayz.tv/files/sharex/Unity_2019-06-01_18-30-22.png

https://github.com/Chaser324/unity-build/blob/e600119a8449bfe4e72f9540bb6986ca8a9e46f9/Editor/Build/UI/UnityBuildGUIUtility.cs#L66

Setting the above line to GUI.skin.textArea solves the problem.

Add "Not Equals" and "Does Not Contain" to FilterCondition.

FilterCondition currently allows for "Equals" and "Contains" tests, but it might be nice in some cases to have inverse versions of these.

Platform instances do not call overridden ApplyVariant methods on build

This is due to platform objects being cast to BuildPlatform on serializing. Currently, only Android and iOS platforms make use of this feature.

I believe a possible fix may be to create an IBuildPlatform interface for platforms to derive from and converting the serialized array of platforms to use this, rather than force its contents to be cast to BuildPlatform.

Execute unit tests (Unity Test Tools) before building. If a test fails, abort build process.

Crashes Unity Editor on Unity 2018.1b

Crashes Unity Editor upon complete build. Below are the last lines of the Editor.log"

*** Completed 'Build.Player.WindowsStandaloneSupport' in 18 seconds (18037 ms)

Receiving unhandled NULL exception
Obtained 0 stack frames.
Launching bug reporter
[Performance] ApplicationTickTimer          :    34073 samples, Peak.  2.86 s (2622.3x), Avg.  1.09 ms, Total. 37.14 s (5.1%)
[Performance] VCProvider                    :    34074 samples, Peak.  64.0 us (49.8x), Avg.  1.28 us, Total. 43.77 ms (0.0%)
[Performance] ReloadAllUsedAssemblies       :     2461 samples, Peak.  2.25 s (1060.5x), Avg.  2.13 ms, Total. 5.233 s (0.7%)
[Performance] Internal_SwitchSkin           :    34074 samples, Peak.  26.9 us (171.7x), Avg.   157 ns, Total. 5.346 ms (0.0%)
[Performance] UnityConnect                  :     7112 samples, Peak.  3.03 ms (107.5x), Avg.  28.1 us, Total. 200.1 ms (0.0%)
[Performance] VerifyUpdate                  :    34074 samples, Peak.  43.0 us (142.2x), Avg.   303 ns, Total. 10.31 ms (0.0%)
[Performance] Collab                        :     7112 samples, Peak.   655 us (291.3x), Avg.  2.25 us, Total. 15.99 ms (0.0%)
[Performance] CEF                           :    10136 samples, Peak.   694 ms (1251.2x), Avg.   555 us, Total. 5.625 s (0.8%)
[Performance] CurlRequestCheck              :     4214 samples, Peak.  97.0 us (64.8x), Avg.  1.50 us, Total. 6.311 ms (0.0%)
[Performance] HubClient                     :    34074 samples, Peak.  22.1 us (51.8x), Avg.   426 ns, Total. 14.52 ms (0.0%)
[Performance] SceneBackgroundTask           :     3199 samples, Peak.  27.1 us (112.4x), Avg.   241 ns, Total. 770.0 us (0.0%)
[Performance] DoScheduler                   :    14653 samples, Peak.  2.07 ms (161.2x), Avg.  12.9 us, Total. 188.6 ms (0.0%)
[Performance] HandlePlayerUpdates           :     7113 samples, Peak.   131 us (6.1x), Avg.  21.4 us, Total. 152.2 ms (0.0%)
[Performance] GlobalCallbacks               :    34074 samples, Peak.  19.3 ms (338.5x), Avg.  57.1 us, Total. 1.947 s (0.3%)
[Performance] PreloadManager                :    34074 samples, Peak.   314 us (28.1x), Avg.  11.2 us, Total. 380.2 ms (0.1%)
[Performance] SceneTracker                  :    34074 samples, Peak.  56.8 ms (226.2x), Avg.   251 us, Total. 8.549 s (1.2%)
[Performance] UpdateConsoleLog              :     1710 samples, Peak.   277 us (40.3x), Avg.  6.86 us, Total. 11.74 ms (0.0%)
[Performance] ChangeLayoutIfNeeded          :    34073 samples, Peak.  32.9 us (285.7x), Avg.   115 ns, Total. 3.923 ms (0.0%)
[Performance] RepaintAll                    :    33960 samples, Peak.  51.8 ms (322.4x), Avg.   161 us, Total. 5.451 s (0.8%)
[Performance] RepaintAllProfilerWindows     :    29467 samples, Peak.   687 us (1473.6x), Avg.   466 ns, Total. 13.74 ms (0.0%)
[Performance] ConsoleAndStatusBar           :      682 samples, Peak.   837 us (110.3x), Avg.  7.59 us, Total. 5.176 ms (0.0%)
[Performance] UpdatePackageImport           :      682 samples, Peak.  2.98 us (7.7x), Avg.   389 ns, Total. 265.2 us (0.0%)
[Performance] HierarchyWindowTick           :      898 samples, Peak.  1.35 ms (308.6x), Avg.  4.36 us, Total. 3.914 ms (0.0%)
[Performance] UpdateInspectorMonoBehaviours :      897 samples, Peak.  1.15 ms (2.9x), Avg.   397 us, Total. 356.4 ms (0.0%)
[Performance] UpdateTooltip                 :     2513 samples, Peak.  49.4 ms (84.0x), Avg.   588 us, Total. 1.478 s (0.2%)
[Performance] UpdateScene                   :    29466 samples, Peak.   566 ms (2837.1x), Avg.   199 us, Total. 5.876 s (0.8%)
[Performance] UpdateVideoTextures           :    29466 samples, Peak.  36.0 us (95.8x), Avg.   376 ns, Total. 11.07 ms (0.0%)
[Performance] Video                         :    29466 samples, Peak.  51.0 us (42.0x), Avg.  1.21 us, Total. 35.76 ms (0.0%)

"Single-run" post-build action does not match filter to all build configurations

I'm trying to build both Mac and Windows versions of our game, and then upload both to Steam. I've set up a single-run ScriptRunner action to fire after all builds are completed. The filter for the ScriptRunner is set to Distribution == Steam and Release Type == Release.

However, just as a test, I ran a build with the following configurations enabled:

• Release/Windows/Steam
• Release/OSX/Steam
• Release/OSX/Standalone

Despite the latter configuration not matching the filter, the ScriptRunner still fires after all three builds are complete.

In my particular case, I think I can get by with a ScriptRunner per-platform, using separate scripts to upload the Mac & Windows builds to Steam individually. However, the behaviour posted above does seem like a bug – is there no way to make sure a single-run filter matches all build configurations?

Add enable/disable option for BuildActions.

It might be nice to be able to temporarily disable a BuildAction without deleting it and losing your settings.

Ability to set alternate icon.

Unity already allows setting different icons based on platform, but it might be nice to have an option to have a different icon for different distributions (Steam, itch, etc.) or different release types (demo, full, etc.).

Build actions are not being called.

I have created 2 build actions, one post and one pre build. The first updates the description in the steam app vdf file with the version number of the build. The second executes the batch file that uploads the build to the steam depots.

I tried adding a Debug.Log() to the execute method and only the post build gets called, however the rest of the code does not seem to execute.

public class SteamAppVersionNumber : BuildAction, IPreBuildAction
{
    private const string FILE_PATH_WINDOWS = @"C:\Unity Data\steamworks_sdk_142\sdk\tools\ContentBuilder\scripts\app_build_<my app build number>_rr.vdf";

    public override void Execute()
    {
        Debug.Log("EXECUTE VERSION NUMBER");
            
        // Update the version number in the Steam app .vdf file prior to building.
        string content = File.ReadAllText(FILE_PATH_WINDOWS);
        string pattern = @"""desc"" "".*""";
        string replacement = $@"""desc"" ""{UnityEngine.Application.version}""";
        content = Regex.Replace(content, pattern, replacement);

        File.WriteAllText(FILE_PATH_WINDOWS, content);
    }
}

public class SteamBuildUpload : BuildAction, IPostBuildAction
{
    private const string FILE_PATH_WINDOWS = @"C:\Unity Data\steamworks_sdk_142\sdk\tools\ContentBuilder\run_build_radical_relocation.bat";

    public override void Execute()
    {
        UnityEngine.Debug.Log("EXECUTE STEAM UPLOAD");

        Process.Start(FILE_PATH_WINDOWS);
    }
}

Optionally write log to text file.

Having all log messages go into a text file would be particularly useful while running Unity in batch mode from the command line or when doing larger sets of builds.

Maintain consistent editor state before and after batch build.

The state of things in the editor should be the same before and after a batch build is run to reduce friction and prevent any possible confusion. The most notable thing here is making sure the status of the script defines and BuildConstants is saved before a batch build and restored after.

Recursive Serialization is not supported. You can't dereference a PPtr while loading.

Recursive Serialization is not supported. You can't dereference a PPtr while loading. (Constructors of C# classes may not load objects either. See stacktrace.)
UnityEditor.BuildPipeline:BuildPlayer(String[], String, BuildTarget, BuildOptions)
SuperSystems.UnityBuild.BuildProject:BuildPlayer(String, BuildReleaseType, BuildPlatform, BuildArchitecture, BuildDistribution, DateTime, BuildOptions, String) (at Assets/UnityBuild/Editor/Build/BuildProject.cs:321)
SuperSystems.UnityBuild.BuildProject:PerformBuild(String[], BuildOptions) (at Assets/UnityBuild/Editor/Build/BuildProject.cs:220)
SuperSystems.UnityBuild.BuildProject:BuildAll() (at Assets/UnityBuild/Editor/Build/BuildProject.cs:20)
UnityEditor.EditorApplication:Internal_CallDelayFunctions()

Building on windows in Unity 2019.1.12f1.
Build platforms: OSX, Windows x86

Seems to happen consistently.

Warning 'BuildTarget.StandaloneLinux' is obsolete - 2019.2+

I get the following warnings on 2019.3 (went to the beta because of a SSAO rendering bug.. first version I could find without it)
I also get a few other errors (LInux build seems to work for me)

Assets/unity-build/Editor/Build/Platform/BuildLinux.cs(33,39): warning CS0618: 'BuildTarget.StandaloneLinux' is obsolete: 'StandaloneLinux has been removed in 2019.2'

Assets/unity-build/Editor/Build/Platform/BuildLinux.cs(32,39): warning CS0618: 'BuildTarget.StandaloneLinuxUniversal' is obsolete: 'StandaloneLinuxUniversal has been removed in 2019.2'

Add $VERSION variable that can be used in build path

For instance, having a build path like

bin/$VERSION/$RELEASE_TYPE/$PLATFORM/$ARCHITECTURE/$DISTRIBUTION

is more useful to me than only having access to the build number variable, especially when the build number is part of my version name.