A recent question about Continuous Integration and Unity led me to try and get something up and running.
The motivation was to see how hard it is to setup a basic CI system for auto building Unity projects and later on be used for running automated testing as well.
Here are my observations.
Disclaimer: although I consider myself to be a Unity noob, I am well experienced with CI, build servers, unit tests and other fancy software engineering practices.
Continuous Integration
The term “Continuous Integration” as I see it is actually an umbrella term for a few things:
- Code Integration – Building your code quickly that is triggered on every check in to the source control system.
- Automated Builds – Your code gets built automatically (and repeatedly) in a single automated step.
-
Automated Testing – Automated tests (whether unit tests or other types) that validate various pieces of functionality of your code.
Although many CI products are available today (free and commercial), i will focus on TeamCity out of 2 reasons:
- It is absolutely FREE (with some limitations).
- There is an open source project that offers building Unity projects from it directly.
Let’s get started!
Ingredients
In order to get started you will need to get the following:
Setup
Installing TeamCity
Installation of TeamCity is pretty straightforward, just “Next, Next” your way through it.
TeamCity uses a concept of “Build Agents”, which are basically a piece of software that does the actual building of the game.
The free version of TeamCity supports up to 3 build agents. For the sake of this example we are installing the server + agent on the same machine.
* Note that for larger setups, Unity must be installed on each machine that the agent will be installed on.
Installing Unity Build Runner
Configuring a new project
Here are the basic steps for configuring a new TeamCity project and 2 build configurations, that will build the “AngryBots” demo that comes with unity in 2 flavors (Web and Windows).
- Create a new project in TeamCity: Administration menu -> Create Project
Add build configurations per platform you’d like to build (One for Windows and another for Web Player)- Per configuration, add a build step with “Unity build runner”
Example of a windows build
- Example configuration of a Web player build
That’s all there is to it! We have a basic CI system running that can automatically build Unity games in different flavors.
Optionally, A build trigger can be set per each configuration to start a build upon a source control check in. For the sake of our example the build will be started on demand from the TeamCity UI.
Caveats
Here’s a list of issues I’ve come across:
- In case of certain errors during the build, Unity build runner will fail to report these to the build log. I have already contacted the owner of this project, although i may attempt to fix it myself.
- When building a Windows version of the game, the path given to the build runner should be the .exe file’s full path. When building a web player project, the path should be a folder name.
- There are no mobile platforms (iOS/Android) available in the build runner dropdown. These are also not documented in Unity’s command line reference page (not sure if they are available).
- Unity enforces a single running instance per project. The command line mode runs the same executable, and so it will fail to work when an instance of the engine is running and has the project being built open.
- Unity doesn’t have a separate compiler/builder platform. The engine’s executable needs to be loaded to build the game, which can be CPU and memory intensive.