Version: v4 (current)

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

Build

Parameters​

build-method​

build-name​

build-target​

compress​

custom-parameters​

executor​

no_output_timeout​

project-path​

return-license​

step-name​

store-artifacts​

fetch-submodules​

unity-license-var-name​

unity-password-var-name​

unity-serial-var-name​

unity-username-var-name​

Examples​

Personal License​

IL2CPP​

Mono​

Other Platforms​

Professional License​

IL2CPP​

Mono​

Other Platforms​

Parameters

build-method

build-name

build-target

compress

custom-parameters

executor

no_output_timeout

project-path

return-license

step-name

store-artifacts

fetch-submodules

unity-license-var-name

unity-password-var-name

unity-serial-var-name

unity-username-var-name

Examples

Personal License

IL2CPP

Mono

Other Platforms

Professional License

IL2CPP

Mono

Other Platforms