Managed Game Server Hosting (Clanforge) API

Note: The content on this page pertains to Managed Game Server Hosting (Clanforge). If you’re using Game Server Hosting (Multiplay), refer to the Game Server Hosting (Multiplay) documentation.

There are two primary methods for updating your game image binary (build): through the Game Server Hosting web interface, or through the Game Server Hosting API. This topic details the process for updating through the Game Server Hosting API.

Prerequisites

  • You have completed the Game Server Hosting Integrations Process.
  • You have received your Service Identifiers from the Integrations Team.
  • You have an updated game image that you’re ready to deploy to your fleet.
  • You have your service identifier document.

These instructions assume that you have a new game build ready in Steam, and have an S3 bucket or a Google Cloud bucket. If you have opted to have the Game Server Hosting support team manually install your game build to your jump machine, you can skip Create an image update on your build machine.

Process overview

The process for updating your game image through the Game Server Hosting API includes the following steps:

  1. Create an image update on your build machine.
  2. Create a difference analysis from the update.
  3. Create a new image version from the difference analysis results.

Unity recommends that you test your game image on your build machine before proceeding from step one to step two.

Update game image workflow.

Step 1: Create an image update on your build machine

Use the Image Update Create endpoint to deploy an updated game image to your build machine. You have the option to use Steam, Google Cloud, or AWS. If you don’t have a cloud bucket or Steam account configured with your game image, contact the Multiplayer Support Team.

It's recommended that you test the updated game image on your build machine before continuing to the next step of this process. This ensures that you’ll identify any issues before deploying the updated game image to the rest of your infrastructure.

Step 2: Create a difference analysis from the update

Use the Image Diff Create endpoint to create a difference analysis (also called a diff analysis) based on the updated game image on your build machine. When you have generated a diff analysis, you can check the status of the diff analysis creation job, reject the diff analysis, or create a new image version from the diff analysis.

Action

Endpoint

Explanation

Check the diff analysis status

Image Diff Status

After you send the request to create the diff analysis, you can use the Image Diff Status endpoint to check the current status of the diff analysis job.

Reject the diff analysis

Image Diff Reject

Reject the results of the diff analysis (using the diff's unique diff ID value) if it has any unexpected changes. After you reject the diff analysis, you can generate a new diff analysis. If you try to generate another diff analysis from the same game image before rejecting or accepting the outstanding diff analysis, you receive an error stating that the image is locked by the diff ID XXXX.

Retry the diff analysis

Image Diff Retry

If the diff analysis failed, troubleshoot the failure, and then retry the diff analysis.

Create a new image version from the diff analysis

Image Version Create

Creating a new image version from a diff analysis is the same as accepting the results of the diff analysis.

Step 3: Create a new image version from the difference analysis

To accept the changes generated from the diff analysis, use the Image Version Create endpoint with the diff ID that the Image Diff Create request returned. The Image Version Create endpoint uses the diff analysis (as specified by the diff ID in the request body), packages the differences, and once complete triggers a rollout to your fleet.

After you’ve called the Image Version Create endpoint, you can call the Image Version Status endpoint to check the status of this packaging process. The following table describes the statuses (job states) of the Image Version Status endpoint.

Job State ID (jobstateid)

Description

1

Created (new job)

2

Pending (waiting to be queued)

3

Queued (waiting to be processed)

4

Running (processing)

5

Completed (successful and triggers the rollout process)

6

Failed (unsuccessful)

Step 4: Monitor rollout progress to machines

Upon successful completion of the image version, the platform starts rolling out the image to machines. Use the Image Rollout Status to observe its progress.

While the rollout is in progress, profiles using this image can still be used for allocations. However, it is the recommended best practice to avoid using those profiles. The machine might not have received the update yet and the underlying files may be changed while in use, which can lead to unexpected behavior.

Instead, zero downtime patching is recommended to ensure build has been fully rolled out before use.