Integration requirements

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

Your game must meet specific requirements to ensure that you can use the Game Server Hosting (GSH) service to host and scale your game. The following guidelines describe how to prepare your game for GSH.

Most of the requirements are about your build or, more specifically, your build executable. Your build encapsulates all the files necessary to run your game. Your build executable is the executable file within your build. You must specify the build executable when you create a build.

Note: There are special requirements for using container builds. See Container build requirements.

General requirements

This section covers the general requirements your build must meet to use GSH. See the following requirements to learn more:

Operating system

Your build executable must support running on Linux (Ubuntu 20.04). You can specify the operating system your build supports when you create a build.

GSH only supports 64-bit applications.

Note: GSH will support Windows-based operating systems in future releases.

Parameterized values

Your build must support using information from parameterized values. GSH manages parameterized values through configuration variables, the server.json file, and launch parameters.

You can manage the information a build tracks through its build configuration.

GSH uses a server.json file to keep track of session-specific information, such as the allocation ID, port number, and any other variables you want to keep track of as configuration variables. Your build process must support keeping track of the information in the server.json file, so it can know when a server becomes allocated and deallocated. If you’re using Unity or Unreal, you can do so with the Game Server SDK.

Builds can also read information from launch parameters. Launch parameters are a good way to set values the build executable needs, such as the game port, when it starts up.

Note: Although recommended, you don’t have to support launch parameters and build configuration variables. You can choose to support either option or a combination of both options.

Start-up conditions

Builds must support starting without an allocation ID populated in the server.json file. This is because you can't allocate a server until the server is online and ready to be allocated, which means the allocatedID field is an empty string ("") until you allocate the server.

Dynamic IP address

Buildsmust support binding to a dynamic IP address for game and query protocol data transmission. Ideally, the build should bind to IP address 0.0.0.0.

Note: Binding to 0.0.0.0 (instead of a specific network interface) ensures the game servers are always accessible using the public IP address of the machine, regardless of the network configuration or operating system.

Dynamic port number

Buildsmust support using a dynamic port number for game data transmission. GSH generates port numbers per server instance (with an offset to ensure there is no port conflict on server startup).

Note: You can use any ports in the range of 8100 to 65355.

Your build executable must use the $$port$$ variable to leverage this functionality. For example, you can pass the $$port$$ variable to your build at start-up by using the following launch parameter:

-port $$port$$

Warning: GSH doesn't support using static or hard-coded port numbers. Static port numbers might work initially but can lead to problems with collisions later.

Logs directory

Buildsshould support the ability to generate logs for each server instance. GSH displays server logs via the Unity Dashboard, where you can view, search, and download logs.

You can control where your build saves log files through a launch parameter and configuration variable. For example, you can use -logFile as the launch parameter and pass the $$log_dir$$ configuration variable.

-logFile $$log_dir$$/engine.log

The logs directory requirement is optional. However, if you don’t set up a log directory, you won’t have any way of accessing logs and crash dumps through the Unity Dashboard.

Tip: GSH recommends setting up a log rotation within the server code to ensure you have historical log data without continuously overwriting a single file. You use the $$timestamp$$ variable to set up automatic log rotation.

Note: If you’re using Unreal Engine, the log directory should be relative to the Saved directory. Games using the Unreal Engine also support -userdir as a launch parameter to re-route crashes and pattern files to a similar directory.

Query protocol

While it’s not a requirement, it’s best practice for builds to support responding to queries from a server query protocol, such as SQP.

A server query protocol is a protocol that facilitates querying information from a server instance, such as the server state and the number of allocated players. Typically, the response contains static variables with dynamic (continuously updated) values.

GSH relies on query protocol responses to determine server instances' health. If your build doesn’t support a query protocol or if you set up your query protocol incorrectly, GSH might determine your server instances are unresponsive.

Additionally, the query protocol lets GSH report and monitor real-time data about each server, such as concurrently connected players (CCU), active allocations, failed allocations, connected players per platform, and server events.

Tip: You can use the Game Server SDK to implement a server query protocol.

Post-allocation cleanup

Builds should support some form of post-allocation (post-session) cleanup to prepare the game server for the next allocation.

You have a couple of options:

  • You can return to a lobby or a ready state after a game session concludes.
  • You can exit the process gracefully (for example, exit code 0), then GSH restarts the process to a ready state.

Returning to the lobby (or a ready state) is preferable to restarting the game server process. Terminating the game server process at the end of a match is a less optimal use of resources because it’s typically more expensive to restart than clean up a process.

Tip: See the Game Server SDK to learn how to manage game server readiness.

Container build requirements

When you create a GSH build, you have several options for uploading your build file.

One option is to use Docker and the GSH container registry to upload a containerized version of your build. However, your build container must meet specific requirements (in addition to the General requirements) before you can use a container build.

Create a container build with the base image

The linux-build-image template container takes care of most of the additional requirements of using a container build. In most cases, you should use the base image. You can use it by adding the following line to the top of your Dockerfile:

FROM unitymultiplay/linux-base-image:<tag>

Replace <tag> with the version of the base image to use. You can check the linux-base-image tags for a list of available tags.

Create a container build from scratch

If you prefer to create your Dockerfile from scratch, it’s your responsibility to ensure your container meets the following requirements.

Warning: You should use the base image unless you have a very specific or advanced use case in which you must create the container from scratch.

RequirementDescription
USER mpukgameYour container must use mpukgame as the USER. This user must have a group identifier (GID) of 2000 and a user identifier (UID) of 2000.
ENTRYPOINTYour container must have an ENTRYPOINT, launched by the mpukgame user.

The following code block shows a simple Dockerfile that meets these requirements:

# ======================================================== #
#                  Unity base image stuff                  #
# ======================================================== #

FROM ubuntu:20.04 AS mpuk

RUN addgroup --gid 2000 mpukgame && \
    useradd -g 2000 -u 2000 -ms /bin/sh mpukgame && \
    apt upgrade && \
    apt update && \
    apt install -y ca-certificates
USER mpukgame

# ======================================================== #
#                    Custom game stuff                     #
# ======================================================== #

FROM mpuk AS game

# copy game files here
# for example:
WORKDIR /game
COPY --chown=mpukgame . .

# set your game binary as the entrypoint
ENTRYPOINT [ "./gamebinary" ]