Continuous Integration

Tips and trips for setting up Continuous Integration (CI) for your projects

Tips for automated building

Continuous Integration means that any changes to the project are merged frequently into the main branch, and automation (especially of testing) is used to ensure quality. The main benefits of Continuous Integration (henceforth CI) are that it makes software development easier, faster, and less risky for developers. Building your Game Client with CI and automated testing might require coherence setup.

For automated delivery of your project changes and testing it in CI, you can take the following steps to make sure coherence is set up appropriately in your project before building a standalone Client.

Baking

You need to bake your code before building to ensure that your local schema file is up-to-date. This can be done by executing the BakeUtil.Bake method.

You can create a Bake method and call it from Unity via command line as a custom method.

using Coherence.Editor;

public static class ContinuousIntegration
{
    public static void Bake() => BakeUtil.Bake();
}

Example batch script

Here is an example batch script that could be saved as bake.bat and executed on a Windows machine to perform baking:

@echo off

:: Bake using Unity
"C:\Program Files\Unity\Hub\Editor\6000.1.2f3\Editor\Unity.exe" -projectPath "C:\Unity Projects\My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.Bake

Example shell script

Here is an example shell script that could be saved as bake.sh and executed on a Linux or OSX machine to perform baking:

#!/bin/bash

# Bake using Unity
"/home/user/Unity/Hub/Editor/6000.1.2f3/Editor/Unity" -projectPath "/home/user/Unity Projects/My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.Bake

Uploading Schema

If your project works using a Replication Server running in coherence Cloud, you will also need to upload your local schema file. This can be done by executing the Schemas.Upload method.

You will need to pass two arguments to the Schemas.Upload method: Project ID and Project Token. You can find these out by following the below steps:

Go to your Online Dashboard.
Select the Project into which you want to upload the schema file.
You should now see the Project ID displayed on the right.
Next go to the Settings page of the project, and scroll down to the Project Tokens section to find the Project Token.

You can provide the Project ID and Project Token as environment variables in your continuous integration setup, and create an UploadSchema method which can be called from Unity via command line as a custom method, and handles retrieving the environment variables and passing them to Schemas.Upload.

using System;
using Coherence.Editor.Portal;

public static class ContinuousIntegration
{
    public static void UploadSchema()
    {
        var projectId = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_ID");
        var projectToken = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_TOKEN");
        Schemas.Upload(projectId, projectToken);
    }
}

Example batch script

Here is an example batch script that could be saved as upload-schema.bat and executed on a Windows machine to upload your local schema:

@echo off

:: Set environment variables
set COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
set COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>

:: Upload local schema using Unity
"C:\Program Files\Unity\Hub\Editor\6000.1.2f3\Editor\Unity.exe" -projectPath "C:\Unity Projects\My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.UploadSchema

Example shell script

Here is an example shell script that could be saved as upload-schema.sh and executed on a Linux or OSX machine to upload your local schema:

#!/bin/bash

# Set environment variables
export COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
export COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>

# Upload local schema using Unity
"/home/user/Unity/Hub/Editor/6000.1.2f3/Editor/Unity" -projectPath "/home/user/Unity Projects/My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.UploadSchema

Running the Replication Server

To start the Replication Server in CI you can use the scripts generated in the 📁 Library/coherence folder: run-replication-server-rooms and run-replication-server-worlds.

Simulator build pipeline

You can use the Simulator Build Pipeline public API to build and upload your Simulator builds to the coherence Cloud from the command line. If you wish to learn more about Simulators, check out the dedicated section.

Building and uploading to the Cloud

There are two methods you will need to call, in order, to build and upload a Simulator build successfully:

SimulatorBuildPipeline.PrepareHeadlessBuild This method will add the COHERENCE_SIMULATOR scripting symbol, will set the build sub target to Server (for Unity 2021) and it will change the platform to Linux. It is necessary to perform these steps in an isolated Unity execution, because in batch mode, there is no editor loop that will make sure your assemblies are reloaded with the changes.
SimulatorBuildPipeline.BuildHeadlessLinuxClientAsync This method will build the Unity Client and upload it to your selected organization and project.

You will need to pass two arguments to the BuildHeadlessLinuxClientAsync method: Project ID and Project Token. See the Uploading Schema section for details on how to acquire them.

You can provide the Project ID and Project Token as environment variables in your continuous integration setup, and create a BuildAndUploadSimulator method which can be called from Unity via command line as a custom method, and handles retrieving the environment variables and passing them to SimulatorBuildPipeline.BuildHeadlessLinuxClientAsync.

using System;
using Coherence.Build;

public static class ContinuousIntegration
{
    public static void PrepareSimulator() => SimulatorBuildPipeline.PrepareHeadlessBuild();

    public static void BuildAndUploadSimulator()
    {
        var projectId = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_ID");
        var projectToken = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_TOKEN");
        SimulatorBuildPipeline.BuildHeadlessLinuxClientAsync(projectId, projectToken);
    }
}

The build will use the Simulator Build Options and and Simulator Slug that are configured in coherence Hub > Simulators.

Example batch script

Here is an example batch script that could be saved as upload-schema.bat and executed on a Windows machine to upload your local schema:

@echo off

:: Set environment variables
set COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
set COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>

:: Prepare Unity for creating a simulator build
"C:\Program Files\Unity\Hub\Editor\6000.1.2f3\Editor\Unity.exe" -projectPath "C:\Unity Projects\My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.PrepareSimulator

:: Create and upload the simulator
"C:\Program Files\Unity\Hub\Editor\6000.1.2f3\Editor\Unity.exe" -projectPath "C:\Unity Projects\My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.BuildAndUploadSimulator

Example shell script

Here is an example shell script that could be saved as upload-schema.sh and executed on a Linux or OSX machine to upload your local schema:

#!/bin/bash

# Set environment variables
export COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
export COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>

# Prepare Unity for creating a simulator build
"/home/user/Unity/Hub/Editor/6000.1.2f3/Editor/Unity" -projectPath "/home/user/Unity Projects/My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.PrepareSimulator

# Create and upload the simulator
"/home/user/Unity/Hub/Editor/6000.1.2f3/Editor/Unity" -projectPath "/home/user/Unity Projects/My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.BuildAndUploadSimulator

Customizing your Simulator builds

You can create your custom build steps by implementing Unity interfaces IPreprocessBuildWithReport and IPostprocessBuildWithReport. In order to verify that the build being created is a Simulator, you can check for the SimulatorBuildPipeline.IsBuildingSimulator boolean.

Game build pipeline

You can use the UploadBuildToCoherence API to upload your game builds to the coherence Cloud from the command line. Windows, WebGL, Linux and macOS builds are supported, via the UploadWindowsBuild, UploadWebGlBuild, UploadLinuxBuild and UploadMacOsBuild methods respectively.

You will need to pass three arguments to UploadBuildToCoherence's build methods: path to the game build, Project ID and Project Token. See the Uploading Schema section for details on how to acquire the latter two.

You can provide the arguments as environment variables in your continuous integration setup, and create a UploadGameBuilds method which can be called from Unity via command line as a custom method, and handles retrieving the environment variables and passing them to UploadBuildToCoherence's build methods.

using System;
using System.IO;
using Coherence.Editor;

public static class ContinuousIntegration
{
    public static void UploadGameBuilds()
    {
        var projectId = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_ID");
        var projectToken = Environment.GetEnvironmentVariable("COHERENCE_PROJECT_TOKEN");

        var windowsBuildPath = Environment.GetEnvironmentVariable("BUILD_PATH_WINDOWS");
        if (Exists(windowsBuildPath))
        {
            UploadBuildToCoherence.UploadWindowsBuild(windowsBuildPath, projectId, projectToken);
        }

        var webGlBuildPath = Environment.GetEnvironmentVariable("BUILD_PATH_WEBGL");
        if (Exists(webGlBuildPath))
        {
            UploadBuildToCoherence.UploadWebGlBuild(webGlBuildPath, projectId, projectToken);
        }

        var linuxBuildPath = Environment.GetEnvironmentVariable("BUILD_PATH_LINUX");
        if (Exists(linuxBuildPath))
        {
            UploadBuildToCoherence.UploadLinuxBuild(linuxBuildPath, projectId, projectToken);
        }

        var macOsBuildPath = Environment.GetEnvironmentVariable("BUILD_PATH_MACOS");
        if (Exists(macOsBuildPath))
        {
            UploadBuildToCoherence.UploadMacOsBuild(macOsBuildPath , projectId, projectToken);
        }
    }

    static bool Exists(string path) => Directory.Exists(path) || File.Exists(path);
}

Example batch script

Here is an example batch script that could be saved as upload-game-builds.bat and executed on a Windows machine to upload your local game builds:

@echo off

:: Set environment variables
set COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
set COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>
set BUILD_PATH_WINDOWS=C:\Unity Projects\My Game\Builds\Windows\My Game
set BUILD_PATH_WEBGL=C:\Unity Projects\My Game\Builds\WebGL\My Game
set BUILD_PATH_LINUX=C:\Unity Projects\My Game\Builds\Linux\My Game
set BUILD_PATH_MACOS=C:\Unity Projects\My Game\Builds\macOS\My Game

:: Upload the builds
"C:\Program Files\Unity\Hub\Editor\6000.1.2f3\Editor\Unity.exe" -projectPath "C:\Unity Projects\My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.UploadGameBuilds

Example shell script

Here is an example shell script that could be saved as upload-game-builds.sh and executed on a Linux or OSX machine to upload your local game builds:

#!/bin/bash

# Set environment variables
export COHERENCE_PROJECT_ID=<YOUR_PROJECT_ID>
export COHERENCE_PROJECT_TOKEN=<YOUR_PROJECT_TOKEN>
export BUILD_PATH_WINDOWS='/home/user/Unity Projects/My Game/Builds/Windows/My Game'
export BUILD_PATH_WEBGL='/home/user/Unity Projects/My Game/Builds/WebGL/My Game'
export BUILD_PATH_LINUX='/home/user/Unity Projects/My Game/Builds/Linux/My Game'
export BUILD_PATH_MACOS='/home/user/Unity Projects/My Game/Builds/macOS/My Game'

# Upload the builds
"/home/user/Unity/Hub/Editor/6000.1.2f3/Editor/Unity" -projectPath "/home/user/Unity Projects/My Game" -batchmode -nographics -quit -executeMethod ContinuousIntegration.UploadGameBuilds

After executing your script, if everything was configured properly, you should see the uploaded builds appear in your Online Dashboard under the project you targeted, in the Schemas & Builds > Game Builds section.

Last updated 3 days ago

Was this helpful?