Skip to main content
Version: v3

Build

The Unity Orb provides the build job to facilitate the process of building your Unity project for multiple platforms.

Parameters​

Below you will find information on each parameter that can be passed to the build job.

build-method​

The command used to build your project. A valid build-method contains the path to a static method in a class inside the Assets/Editor directory. The Unity Orb will fall back to the default script if this parameter is left empty.

To illustrate, if you were to modify the default script and use it to build your project, you would need to place its content in Assets/Editor/MyBuildMethod.cs and pass BuildCommand.PerformBuild as your build-method value.

If your custom build method requires additional parameters, see custom-parameters.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-method: 'BuildCommand.PerformBuild'
  • Default: N/A
  • Required: false
  • Type: string

build-name​

Your build's name. If left blank, the build will be named after the target platform.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-name: 'MyUnityProject'
  • Default: N/A
  • Required: false
  • Type: string

build-target​

The platform on which you want to run your game or application. Available targets can be found in the Unity Editor documentation.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-target: 'StandaloneLinux64'
  • Default: N/A
  • Required: true
  • Type: string

compress​

Whether to compress the build output to a .tar.gz file. Set it to true if you want to download the build artifacts from the CircleCI web app. Otherwise, you will have to download each file individually. If set to false for decompressed WebGL builds, the built project can be run directly from the GameCI dashboard.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          compress: true
  • Default: true
  • Required: false
  • Type: boolean

custom-parameters​

Additional parameters for the Unity CLI. This is useful if you want to change Unity's build options or pass custom parameters to your build method.

The parameters must be separated by space and must be in the format -key value or -key for booleans. Environment variables are supported and will be expanded in runtime.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          custom-parameters:
            '-customParam1 potato -customParam2 tomato -customParam3 $CIRCLE_WORKFLOW_ID
            -DetailedBuildReport'
  • Default: N/A
  • Required: false
  • Type: string

executor​

The executor that you want to run your build job on. Bear in mind that projects using IL2CPP for a scripting backend should run on the same OS as the build target. For example, if you want to build for macOS using IL2CPP, then you must use the macos or macos-runner executor.

Each executor has its set of parameters. See the Executors section for more details.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
  • Default: N/A
  • Required: true
  • Type: executor

no_output_timeout​

Elapsed time without output before the job is canceled and stopped. The value can be in hours, minutes or seconds - a digit followed by h, m or s respectively. Consider increasing it if you see this error:

Too long with no output (exceeded 20m0s): context deadline exceeded

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          no_output_timeout: 30m
  • Default: 20m
  • Required: false
  • Type: string

project-path​

If your project sits at the root of your repository, leave it to the default value. Otherwise, enter the path to your Unity project. It should be the directory that has the "Assets" folder inside it.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
  • Default: .
  • Required: false
  • Type: string

return-license​

Whether to manually return the Unity license after the build job is finished. This is usually unnecessary and only useful when running into an unrecoverable error while having a license active. Additionally, Unity only allows returning professional licenses.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          return-license: true
  • Default: false
  • Required: false
  • Type: boolean

step-name​

Specify a custom step name to be shown in the CircleCI web app.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          step-name: 'Build my Unity project'
  • Default: Build the project
  • Required: false
  • Type: string

store-artifacts​

Whether to store the build output. If set to false you won't be able to download your build in the CircleCI web app.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          store-artifacts: false
  • Default: true
  • Required: false
  • Type: boolean

fetch-submodules​

Whether to fetch git submodules relating to the project repository.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          fetch-submodules: true
  • Default: false
  • Required: false
  • Type: boolean

unity-license-var-name​

The name of the environment variable holding the license set in your Context. Only required when using a Personal License. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
  • Default: UNITY_ENCODED_LICENSE
  • Required: false
  • Type: env_var_name

unity-password-var-name​

The name of the environment variable holding the password set in your Context. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-password-var-name: 'UNITY_PASSWORD'
  • Default: UNITY_PASSWORD
  • Required: false
  • Type: env_var_name

unity-serial-var-name​

The name of the environment variable holding the serial set in your Context. Only required when using a Pro or Plus License. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-serial-var-name: 'UNITY_SERIAL'
  • Default: UNITY_SERIAL
  • Required: false
  • Type: env_var_name

unity-username-var-name​

The name of the environment variable holding the username set in your Context. See Activation for more details.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-username-var-name: 'UNITY_USERNAME'
  • Default: UNITY_USERNAME
  • Required: false
  • Type: env_var_name

Examples​

In this section, you will find examples of workflows using this job. However, notice that the separation used in the examples is only for the sake of visualisation. You can build for all target platforms in the same workflow. All examples are based on CircleCI's Demo Project.

Personal License​

This example shows how to build your project for several platforms using a Personal License.

IL2CPP​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # Linux IL2CPP
      - unity/build:
          name: 'build-linux64-il2cpp'
          step-name: 'Build StandaloneLinux64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows IL2CPP
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build StandaloneWindows64 il2cpp'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'windows-il2cpp'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity

      # macOS IL2CPP
      - unity/build:
          name: 'build-osx-il2cpp'
          step-name: 'Build macOS IL2CPP'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/macos'
            resource_class: 'large'
            editor_version: '2021.3.2f1'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity
Mono​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # Linux Mono
      - unity/build:
          name: 'build-linux64-mono'
          step-name: 'Build StandaloneLinux64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'base'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows Mono
      - unity/build:
          name: 'build-Windows64-mono'
          step-name: 'Build StandaloneWindows64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'windows-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneWindows64'
          context: unity

      # macOS Mono
      - unity/build:
          name: 'build-osx-mono'
          step-name: 'Build StandaloneOSX'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'mac-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneOSX'
          context: unity
Other Platforms​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # WebGL
      - unity/build:
          name: 'build-webgl'
          step-name: 'Build WebGL'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'webgl'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'WebGL'
          compress: false
          context: unity

      # Android
      - unity/build:
          name: 'build-android'
          step-name: 'Build Android'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'android'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'Android'
          context: unity

      # iOS
      - unity/build:
          name: 'build-ios'
          step-name: 'Build iOS'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'ios'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'iOS'
          context: unity

      # tvOS
      - unity/build:
          name: 'build-tvOS'
          step-name: "Build Apple's tvOS"
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'appletv'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: tvOS
          compress: true
          context: unity

Professional License​

This example shows how to build your project for several platforms using a Pro License.

IL2CPP​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # Linux IL2CPP
      - unity/build:
          name: 'build-linux64-il2cpp'
          step-name: 'Build StandaloneLinux64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows IL2CPP
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build StandaloneWindows64 il2cpp'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'windows-il2cpp'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity

      # macOS IL2CPP
      - unity/build:
          name: 'build-osx-il2cpp'
          step-name: 'Build macOS IL2CPP'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/macos'
            resource_class: 'large'
            editor_version: '2021.3.2f1'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneOSX
          compress: true
          context: unity
Mono​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # Linux Mono
      - unity/build:
          name: 'build-linux64-mono'
          step-name: 'Build StandaloneLinux64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'base'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows Mono
      - unity/build:
          name: 'build-Windows64-mono'
          step-name: 'Build StandaloneWindows64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'windows-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneWindows64'
          context: unity

      # macOS Mono
      - unity/build:
          name: 'build-osx-mono'
          step-name: 'Build StandaloneOSX'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'mac-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneOSX'
          context: unity
Other Platforms​
version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      # WebGL
      - unity/build:
          name: 'build-webgl'
          step-name: 'Build WebGL'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'webgl'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'WebGL'
          compress: false
          context: unity

      # Android
      - unity/build:
          name: 'build-android'
          step-name: 'Build Android'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'android'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'Android'
          context: unity

      # iOS
      - unity/build:
          name: 'build-ios'
          step-name: 'Build iOS'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'ios'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'iOS'
          context: unity

      # tvOS
      - unity/build:
          name: 'build-tvOS'
          step-name: "Build Apple's tvOS"
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'appletv'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: tvOS
          compress: true
          context: unity