> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# game-ci/unity

Easily build and test Unity projects. The project artifacts and test results are stored in CircleCI and can be opened in the Workflow web app. Supports Windows, Linux and macOS.


## Commands

### build

This command builds an Unity project.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build-method` | string |  | The method used as argument for the Unity CLI "executeMethod" parameter.
It must be a valid path to a static method and the class exist in the Assets/Editor directory.
If left empty, the default build method will be used.
 |
| `build-name` | string |  | Enter the name for this build.
If left blank, the build will be named after the target platform.
 |
| `build-target` | string |  | The target platform of your build.
Accepted arguments vary with Unity's version and can be found in the docs: https://docs.unity3d.com/2021.2/Documentation/ScriptReference/BuildTarget.html
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason.
 |
| `compress` | boolean | true | Whether to compress the build output to a ".tar.gz" archive.
This is recommended if you want to download the built artifacts from the CircleCI web app.
If left to "false" for decompressed WebGL builds, you can run the project directly from the CircleCI web app.
 |
| `custom-parameters` | string |  | Additional arguments for the Unity CLI.
Use it to pass arguments defined on your custom "build-method" or Unity's build options. Environment variables are supported.
The parameters must be separated by space and must be in the format "-key value" or "-key" for booleans.
Example: "-customArg1 WebGL -EnableHeadlessMode -customArg2 $CIRCLE_WORKFLOW_ID".
 |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. |
| `persist-to-workspace` | boolean | false | Whether to persist the build output to workspace. |
| `project-path` | string | . | Enter the relative path of your Unity project.
This should be the directory that has an "Assets" folder inside it.
 |
| `step-name` | string | Build the project | Specify a custom step name for this command, if desired.
 |
| `store-artifacts` | boolean | true | Whether to store the build output.
If left to "false" you won't be able to download the build from the job's artifacts.
 |

### prepare-env

This command prepares the environment for testing or building an Unity project.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason.
 |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. |
| `project-path` | string | . | Enter the path of your Unity project.
This should be the directory that has an "Assets" folder inside it.
 |
| `unity-license-var-name` | env_var_name | UNITY_ENCODED_LICENSE | Enter the name of the environment variable containing your Unity license file encoded in base64.
Required if you have a Personal license.
 |
| `unity-password-var-name` | env_var_name | UNITY_PASSWORD | Enter the name of the environment variable containing your Unity password.
 |
| `unity-serial-var-name` | env_var_name | UNITY_SERIAL | Enter the name of the environment variable containing your Unity serial number.
Required if you have a Plus or Pro license.
 |
| `unity-username-var-name` | env_var_name | UNITY_USERNAME | Enter the name of the environment variable containing your Unity username.
 |

### return-license

This command returns the license used to build or test the project.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `unity-password-var-name` | env_var_name | UNITY_PASSWORD | Enter the name of the environment variable containing your Unity password.
 |
| `unity-username-var-name` | env_var_name | UNITY_USERNAME | Enter the name of the environment variable containing your Unity username.
 |

### test

This command tests an Unity project.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason.
 |
| `custom-parameters` | string |  | Additional arguments for the Unity CLI.
Use it to pass arguments to Unity's test options. Environment variables are supported.
The parameters must be separated by space and must be in the format "-key value" or "-key" for booleans.
Example: '-testFilter "MyNamespace.Something.MyTest" -assemblyNames "MyUnitTestAssembly" -testCategory "Unit;Integration"'.
 |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. |
| `project-path` | string | . | Enter the relative path of your Unity project.
This should be the directory that has an "Assets" folder inside it.
 |
| `step-name` | string | Run tests | Specify a custom step name for this command, if desired.
 |
| `test-platform` | string | playmode | Specify the test platform to run tests on.
Valid values are "editmode", "playmode" and Unity's target builds.
More information can be found on: https://docs.unity3d.com/Packages/com.unity.test-framework@2.0/manual/reference-command-line.html
 |

## Jobs

### build

Simple drop-in job to build your Unity game.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build-method` | string |  | The method used as argument for the Unity CLI "executeMethod" parameter.
It must be a valid path to a static method and the class exist in the Assets/Editor directory.
If left empty, the default build method will be used.
 |
| `build-name` | string |  | Enter the name for this build.
If left blank, the build will be named after the target platform.
 |
| `build-target` | string |  | The target platform of your build.
Accepted arguments vary with Unity's version and can be found in the docs: https://docs.unity3d.com/2022.2/Documentation/ScriptReference/BuildTarget.html
 |
| `compress` | boolean | true | Whether to compress the build output to a ".tar.gz" archive.
This is recommended if you want to download the built artifacts from the CircleCI web app.
If left to "false" for decompressed WebGL builds, you can run the project directly from the CircleCI web app.
 |
| `custom-parameters` | string |  | Additional arguments for the Unity CLI.
Use it to pass arguments defined on your custom "build-method" or Unity's build options. Environment variables are supported.
The parameters must be separated by space and must be in the format "-key value" or "-key" for booleans.
Example: "-customArg1 WebGL -EnableHeadlessMode -customArg2 $CIRCLE_WORKFLOW_ID".
 |
| `executor` | executor |  | Pick an Executor to run the build job with.
 |
| `fetch-submodules` | boolean | false | Whether to fetch git submodules
 |
| `no_output_timeout` | string | 20m | Elapsed time the command can run without output. |
| `persist-to-workspace` | boolean | false | Whether to persist the build output to workspace. |
| `project-path` | string | . | Enter the path of your Unity project.
This should be the directory that has an "Assets" folder inside it.
 |
| `return-license` | boolean | false | Whether to return the license used to build the project.
Unity only allows returning professional licenses.
 |
| `step-name` | string | Build the project | Specify a custom step name for the build command, if desired.
 |
| `store-artifacts` | boolean | true | Whether to store the build output.
If left to "false" you won't be able to download the build from the job's artifacts.
 |
| `unity-license-var-name` | env_var_name | UNITY_ENCODED_LICENSE | Enter the name of the environment variable containing your Unity license file encoded in base64.
Required if you have a Personal license.
 |
| `unity-password-var-name` | env_var_name | UNITY_PASSWORD | Enter the name of the environment variable containing your Unity password.
 |
| `unity-serial-var-name` | env_var_name | UNITY_SERIAL | Enter the name of the environment variable containing your Unity serial number.
Required if you have a Plus or Pro license.
 |
| `unity-username-var-name` | env_var_name | UNITY_USERNAME | Enter the name of the environment variable containing your Unity username.
 |

### create-activation-file

Simple drop-in job to create a Unity activation file.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string | 2021.3.7f1 | Pick the editor version for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
 |

### test

Simple drop-in job to build your Unity game.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-parameters` | string |  | Additional arguments for the Unity CLI.
Use it to pass arguments to Unity's test options. Environment variables are supported.
The parameters must be separated by space and must be in the format "-key value" or "-key" for booleans.
Example: '-testFilter "MyNamespace.Something.MyTest" -assemblyNames "MyUnitTestAssembly" -testCategory "Unit;Integration"'.
 |
| `executor` | executor |  | Pick an Executor to run the build job with.
 |
| `no_output_timeout` | string | 20m | Elapsed time the command can run without output. |
| `project-path` | string | . | Enter the path of your Unity project.
This should be the directory that has an "Assets" folder inside it.
 |
| `return-license` | boolean | false | Whether to return the license used to test the project.
Unity only allows returning professional licenses.
 |
| `step-name` | string | Run tests | Specify a custom step name for the test command, if desired.
 |
| `test-platform` | string | editmode | Specify the test platform to run tests on.
Valid values are "editmode", "playmode" and Unity's target builds.
More information can be found on: https://docs.unity3d.com/Packages/com.unity.test-framework@2.0/manual/reference-command-line.html
 |
| `unity-license-var-name` | env_var_name | UNITY_ENCODED_LICENSE | Enter the name of the environment variable containing your Unity license file encoded in base64.
Required if you have a Personal license.
 |
| `unity-password-var-name` | env_var_name | UNITY_PASSWORD | Enter the name of the environment variable containing your Unity password.
 |
| `unity-serial-var-name` | env_var_name | UNITY_SERIAL | Enter the name of the environment variable containing your Unity serial number.
Required if you have a Plus or Pro license.
 |
| `unity-username-var-name` | env_var_name | UNITY_USERNAME | Enter the name of the environment variable containing your Unity username.
 |

## Executors

### macos

Drop-in executor to build project in macOS.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the Unity Editor version.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://unity3d.com/get-unity/download/archive.
 |
| `resource_class` | enum | medium | Resource class used for the executor.
If you are receiving a "CircleCI received exit code 137" from the build job, you may need to increase the resource class.
For details on resource class availability, see https://circleci.com/docs/using-macos#available-resource-classes.
 |
| `xcode_version` | string | 13.4.1 | Pick the Xcode version.
Available options can be found at https://circleci.com/docs/using-macos#supported-xcode-versions.
 |

### macos-runner

Drop-in executor to build projects in a macOS runner.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the Unity Editor version.
Available options can be found at https://unity3d.com/get-unity/download/archive.
 |
| `resource_class` | string |  | Enter your Runner resource class.
For information on how to setup a Runner agent, see: https://circleci.com/docs/2.0/runner-overview/.
 |
| `working_directory` | string | /var/opt/circleci/workdir | Enter the working directory of your runner agent.
 |

### ubuntu

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.
This executor only supports the "ubuntu" OS.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `resource_class` | enum | large | Resource class used for the executor.
If you are receiving a "CircleCI received exit code 137" from the build job, you may need to increase the resource class.
 |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |

### ubuntu-container-runner

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.
For information on how to setup a Runner agent, see: https://circleci.com/docs/container-runner-installation/.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `resource_class` | string |  | Enter your Runner resource class.
For information on how to setup a Runner agent, see: https://circleci.com/docs/container-runner-installation/.
 |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |

### windows-2019

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `size` | enum | large | The size of Windows resource to use. |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |
| `version` | string | current | The Windows image version to use.
 |

### windows-2019-cuda

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `size` | enum | medium | The size of Windows resource to use. |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |
| `version` | string | current | The Windows image version to use.
 |

### windows-2022

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `size` | enum | large | The size of Windows resource to use. |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |
| `version` | string | current | The Windows image version to use.
 |

### windows-runner

Select the Editor version and Target Platform for the GameCI image.
Available target platforms can be found at: https://game.ci/docs/docker/versions.
This executor only supports the "windows" OS and should be used with a CircleCI Runner.
For information on how to setup a Runner agent, see: https://circleci.com/docs/2.0/runner-overview/.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `editor_version` | string |  | Pick the editor version for the GameCI image.
Make sure to pick the same major version as the Unity version you generated the license for.
Available options can be found at https://game.ci/docs/docker/versions.
 |
| `resource_class` | string |  | Enter your Runner resource class.
For information on how to setup a Runner agent, see: https://circleci.com/docs/2.0/runner-overview/.
 |
| `target_platform` | enum |  | Pick the target platform for the GameCI image.
Available options can be found at https://game.ci/docs/docker/versions.
The 2018 release doesn't support the "linux-il2cpp" target platform.
 |
| `working_directory` | string | C:\ProgramFiles\CircleCI\Workdir | Enter the working directory of your runner agent.
 |

## Examples

### test_and_build_personal_license

Drop-in solution to automatically run tests and build your Unity project using a Personal license. Make sure to read the documentation before using the orb: https://game.ci/docs/circleci/getting-started. For runner examples, see: https://game.ci/docs/circleci/executors#macos-runner and https://game.ci/docs/circleci/executors#windows-runner.


```yaml
version: '2.1'
orbs:
  unity: game-ci/unity@1.3.0
workflows:
  test-build-with-executors:
    jobs:
      - checkout
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/ubuntu
            resource_class: medium
            target_platform: linux-il2cpp
          name: test-linux
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneLinux64
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/ubuntu
            resource_class: large
            target_platform: linux-il2cpp
          name: build-linux64-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-linux
          step-name: Build StandaloneLinux64
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/windows-2022
            size: large
            target_platform: windows-il2cpp
          name: test-windows
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneWindows64
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/windows-2019
            size: large
            target_platform: windows-il2cpp
          name: build-Windows64-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-windows
          step-name: Build StandaloneWindows64 il2cpp
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/macos
            resource_class: large
          name: test-osx
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneOSX
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/macos
            resource_class: large
          name: build-osx-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-osx
          step-name: Build macOS IL2CPP
          unity-license-var-name: UNITY_ENCODED_LICENSE
          unity-password-var-name: UNITY_PASSWORD
          unity-username-var-name: UNITY_USERNAME
```

### test_and_build_pro_or_plus_license

Drop-in solution to automatically run tests and build your Unity project using a Pro or Plus license. Make sure to read the documentation before using the orb: https://game.ci/docs/circleci/getting-started. For runner examples, see: https://game.ci/docs/circleci/executors#macos-runner and https://game.ci/docs/circleci/executors#windows-runner.


```yaml
version: '2.1'
orbs:
  unity: game-ci/unity@1.3.0
workflows:
  test-build-with-executors:
    jobs:
      - checkout
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/ubuntu
            resource_class: medium
            target_platform: linux-il2cpp
          name: test-linux
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneLinux64
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/ubuntu
            resource_class: large
            target_platform: linux-il2cpp
          name: build-linux64-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-linux
          step-name: Build StandaloneLinux64
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/windows-2022
            size: large
            target_platform: windows-il2cpp
          name: test-windows
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneWindows64
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/windows-2019
            size: large
            target_platform: windows-il2cpp
          name: build-Windows64-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-windows
          step-name: Build StandaloneWindows64 il2cpp
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
      - unity/test:
          context: unity
          executor:
            editor_version: 2021.3.1f1
            name: unity/macos
            resource_class: large
          name: test-osx
          project-path: Unity2D-Demo-Game-CI-CD/src
          step-name: Check if the tests run and results are uploaded
          test-platform: playmode
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
      - unity/build:
          build-target: StandaloneOSX
          compress: true
          context: unity
          executor:
            editor_version: 2021.3.2f1
            name: unity/macos
            resource_class: large
          name: build-osx-il2cpp
          project-path: Unity2D-Demo-Game-CI-CD/src
          requires:
            - test-osx
          step-name: Build macOS IL2CPP
          unity-password-var-name: UNITY_PASSWORD
          unity-serial-var-name: UNITY_SERIAL
          unity-username-var-name: UNITY_USERNAME
```