Running your first game server

Running a game server on IMS zeuz is simple, it takes just a few steps to get started. In this guide we'll show you how to create your first payload and how you can run your own game server on IMS zeuz.

Requirements

In order to run through the following steps, you must have:

• An IMS project
• An account linked to IMS (via Google, GitHub...)
• The IMS CLI
• An IMS zeuz cluster

If you're missing any of the above, please get in touch with your Account Manager.

Payload

A payload is the unit running a game server. See the Payload documentation for more details. For the purpose of this walkthrough, we'll run a simple bash script as opposed to a game.

IMS Image Manager

On IMS zeuz, every game server is run inside a Docker Container. We'll use the Image Manager to package and publish our "game server" assets as a Docker Image. Check out how to publish a game server for the different ways you can publish your game server.

The game server

First create and enter a game-server directory:

mkdir game-server
cd game-server

For this test, the game server will be a simple shell script run.sh:

#!/bin/sh

# Try to make the payload ready
while ! curl --request POST http://${ORCHESTRATION_PAYLOAD_API}/api/v0/ready ;do
  sleep 1
done

# Tick every second
c=0
while true;do
  echo $c; c=$((c=c+1))
  sleep 1
done

This script calls the Payload Local API - ready endpoint in order to indicate that the payload is ready for reservation. It then simply prints a counter every second in the logs to simulate a server doing something. The Payload Local API - ready call is required in order to tell the orchestration system that your game server is ready to be reserved. This means your game server should only make that call whenever your game server is done initializing and is ready to start accepting players.

caution

The Payload Local API is starting up at the same time as your game server, and may not be initially available. Use a retry mechanism to ensure the request is successful.

caution

Ensure your game server exits if it encounters an error before successfully calling the Ready API. Otherwise, it could end up staying in a Starting state indefinitely, filling up the allocation buffer with non-reservable payloads.

info

We use curl in this example, but your game server should use a generated OpenAPI client. See the best practices.

Publish the image to IMS Image Manager (this should take a minute or so):

ims image publish --project-id [YOUR_PROJECT_ID] --description "Test IMS zeuz image" --version "0.0.1" --directory game-server

Outputs:

2022-03-08T16:49:30.678Z        info    Preparing the directory to upload       {"directory": "/path/to/game-server"}
2022-03-08T16:49:31.137Z        info    Files to upload {"size": "432B"}
2022-03-08T16:49:33.632Z        info    Uploading
2022-03-08T16:49:37.114Z        info    Uploaded
2022-03-08T16:49:37.513Z        info    Build triggered {"image_id": "0611527e-fe76-4ae7-9c00-d6966b24a135"}
2022-03-08T16:49:37.513Z        info    Waiting for build to finish     {"image_id": "0611527e-fe76-4ae7-9c00-d6966b24a135"}
2022-03-08T16:50:27.591Z        info    Build complete and image ready to use   {"image_id": "0611527e-fe76-4ae7-9c00-d6966b24a135", "image_url": "gir.improbable.io/[YOUR_PROJECT_ID]:0.1"}

Now the image is available in the IMS Image Manager Console:

Create an allocation

In IMS zeuz, an allocation defines where and how the payloads run and scale. Check out the Allocation documentation for more details.

Go to the IMS zeuz service in the IMS Console and create the allocation. Insert a name and the Cluster ID we provided you with:

Set the server specification.

info

CPU and Memory use Kubernetes resource units. For example CPU is counted in cores, 0.1 is equivalent to 10% of a core. Other units are also allowed, see resource units in Kubernetes.

note

The "game server" does not currently make use of any ports, the port defined as "GamePort" would be the port your game server listens on for player connections.

Select the image you created just before in the image dropdown.

Finally, set the command to ./run.sh and create the allocation, you can add parameters if you wish such as startup arguments and environment variables.

After a few seconds, the allocation should be running. The number of active payloads should say 1, click this to view the active payloads:

The payload page should show one payload in a ready state:

You can inspect the logs generated by the payload using the direct link to the logs in Grafana:

Reserve a payload

The payload is now ready, this means that it is available to be reserved for a game session.

While in a ready state, IMS zeuz is free to remove the payload at any time (for scaling operations), therefore players shouldn't be connected to these.

To reserve a payload, from the allocation page select the allocation and click the Reserve button, this will make a reservation request to the system and will reserve a payload for you.

info

The reservation process is intended to be made via a MatchMaker or other backend system. IMS zeuz is fully integrated with IMS Matchmaker, we also provide the IMS zeuz API to integrate with your backend or third party matchmakers.

You can see now that the payload is reserved. A reserved payload is an active game, most likely with players connected to it. The system will not be able to remove the payload until it shuts down or gets unreserved. Note that another payload has spun up in order to satisfy the buffer size of 1 that we previously set in the allocation settings.

Going further