CI/CD for Unity game development with GameCI's Unity orb

We recently partnered with GameCI to bridge the gap between CircleCI and the game development scene. This partnership brought forth the Unity orb, a reusable component of config you can plug into your CircleCI configuration file to build and test your Unity projects.

For a while now, continuous integration and delivery have been part of the software development cookbook of several software houses and IT departments. However, this is often not the case in game development. While the latter and software development are fundamentally the same, games are inherently more complex to integrate into a pipeline due to their size and hardware requirements.

The Unity orb is our first step toward streamlining CI/CD for game developers. With it, you can build your game with minimal configuration for several platforms, including macOS, Windows, Linux, Android, and iOS. And if you have tests written with the Unity Test Framework, the orb can run, parse the results to JUnit, and store them for you to visualize in the CircleCI web app.

In the following sections, you will learn about our partnership with GameCI and see what the Unity orb can do. If you can’t wait to set up the orb with your project, head to the Getting Started page.

GameCI

GameCI is a community of developers founded in 2019 by Webber and GabLeRoux focused on creating open source tools to automate the testing, building, and deployment of Unity projects. With the help of David, Fisher, and several contributors, it grew to support more than 1000 teams looking to improve their development process.

Initially, GameCI focused on offering Docker images containing everything needed to build Unity projects. They evolved to create and maintain comprehensive GitHub Actions that help developers test, build, and deploy. And now, their roadmap includes a massive decoupling from GitHub to become a CI-agnostic CLI tool.

Like GameCI, we believe in open source and want to help game developers incorporate CI/CD in their development process without turning it into the focus of the business. So we reached out to them and suggested a partnership to implement an orb that follows the philosophy and functionalities they included in their existing tools.

We are very proud of what we achieved together and highly encourage you to learn more about them on their website, GitHub, and Discord.

The Unity orb

The Unity orb packs many cool features distributed between the build and test jobs, and we will tour them here. If you want the nitty-gritty, visit the orb’s registry and source code,

As the name implies, build takes your Unity project, builds it, and optionally saves the resulting artifacts. We optimize the process by caching the project’s dependencies based on changes to your packages-lock.json, meaning you get cache working out of the box! Another cool feature is the ability to build your game for multiple platforms. And since the orb runs on multiple executors, you can choose between Mono and IL2CPP. In our tests, we got successful builds for:

• WebGL
• tvOS
• macOS
• Linux
• Windows
• iOS
• Android

You can download and run them in the test-build workflow here. You can even play in your browser by running decompressed WebGL builds straight from the CircleCI web app!

The test job helps you run your Unity tests and get insights from them. We achieve this by parsing Unity’s XML to JUnit and storing the results. You also can block jobs down the road using the requires key if the tests don’t pass.

You can utilize the orb’s commands if you need more control over caching or want to define custom behaviors for your jobs. A GameCI community member explored this concept and shared their findings in this gist. They used the persist_to_workspace functionality to deploy the build artifacts to itch.io in a post-build job.

Execution environments and how they affect you

The cool thing about Unity is the ability to write your game once and run it anywhere. However, nuances such as the scripting backend require you to have access to your game’s target platform to build for it. With that in mind, we designed the Unity orb to be flexible about its execution environment.

You can run the orb on macOS, Windows, and Linux executors, and the execution environment is not limited to the CircleCI cloud. You can build projects on self-hosted runners, giving you total control over the infrastructure. In the following sections, we discuss each option and learn which is the best choice for you.

Building Unity projects on CircleCI Cloud

The most significant advantages of running your pipeline on our cloud are zero infrastructure overhead and fast setup. You only have to worry about configuring your context and workflow. We recommend following this route if you have a small project, want to test the orb, or don’t care about generally longer build times. After getting everything ready, your config will look like this:

version: 2.1

orbs:
  unity: game-ci/unity@1.2

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build project for Windows using Cloud'
          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
          context: unity

This snippet uses the Windows executor to build an IL2CPP project for Windows. You can find more examples targeting different platforms in the config file of our demo project and in the documentation.

Building Unity projects with CircleCI self-hosted runners

Larger projects have bandwidth and hardware requirements that might exceed our cloud offering’s capacity. In these cases, you want to use the Unity orb with self-hosted runners. Due to their non-ephemeral nature, the checkout step won’t clone your entire repository every run, and you can pick hardware that meets your needs. With recent updates in the installation experience, you can get runner up and running in 5 minutes or less.

Once you have your runner set up, all you have to do is change your configuration file to use the macOS or Windows runner executor while passing your resource class label as an argument:

version: 2.1

orbs:
  unity: game-ci/unity@1.2

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build project for Windows using Runner'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-runner'
            editor_version: '2021.3.2f1'
            resource_class: 'ericribeiro/unity-runner'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          context: unity

Notice how only the executor’s parameters changed. The rest of your configuration stays the same, allowing you to try CircleCI cloud and quickly switch to the runner if the former doesn’t suit your needs. The figure below illustrates how the windows-runner fares against the windows-2019 cloud executor.

They are building the same project for the same target platform, but runner finishes twenty minutes sooner. The gap in build times lies in the fact that the runner ran a job once before. Consequently, all environment dependencies were cached or already installed. We conducted this comparison run using an m5.2xlarge EC2 instance for runner and a large resource class for cloud.

Final thoughts

We are very excited to start this journey with game developers and GameCI. With the knowledge acquired from this undertaking, we hope to develop more tools tailored to the game development community and evolve the Unity orb. If you have any suggestions or feedback, connect with us on Twitter, say hello in our discussion forum, or chat with us on Discord. `