Integration guide

This guide will help you integrate and deploy your multiplayer game on Hathora Cloud. Your game server must be built to run with a dedicated Linux server.

1. Preparing your server build

Your server will need to be able to be built as a dedicated Linux server build. For more info, check out Unity's guide.

If you use our Unity Plugin, you will be able to build your server build directly from the Unity Editor.

2. Generating a Dockerfile

By providing a Dockerfile with your server build, we will be able to scale your server across the globe.

If you don't already have a Dockerfile for your game, we recommend using our Unity Plugin, because it will generate an initial Dockerfile for you and it also has demos showing working integrations.

If you'd like to see an example of a Unity server Dockerfile, check out our sample game's dockerfile here:

• Photon Fusion sample game Dockerfile
• Unity NGO sample game Dockerfile

3. Deploy server to Hathora Cloud

If this is your first time deploying on Hathora Cloud, we recommend starting with our Deploying on Hathora Cloud guide.

There are 3 ways to deploy your server on Hathora Cloud:

1. Directly from the Unity Editor, with our Unity Plugin
2. With command line or CI/CD pipeline
3. Drag and drop upload via Hathora Console

Unity Plugin

CLI

hathora deploy \
        --file $FILE_OR_DIRECTORY \
        --build-tag $BUILD_TAG \
        --rooms-per-process $ROOMS_PER_PROCESS \
        --container-port $CONTAINER_PORT \
        --transport-type $TRANSPORT_TYPE \
        --requested-memory-mb $MEMORY_MB \
        --requested-cpu $CPU \
        --env ENV1=$ENV1_VALUE \
        --env ENV2=$ENV2_VALUE \
        --idle-timeout-enabled \
        --app-id $APP_ID \
        --token $HATHORA_TOKEN 

Console

Your server file needs to be a compressed tar file (e.g. .tgz, tar.gz).

The zipped bundle should include your server build (.x86_64), along with your Dockerfile at the root.

tip

Zero-downtime deployments: New deployments will not impact any existing games, your newly deployed version will only be used for subsequent games created after.

4. Creating rooms/processes

There are 3 ways to create rooms on Hathora Cloud:

1. Via API call using our Unity SDK
2. Directly from the Unity Editor, with our Unity Plugin
3. Directly with Hathora Console (great for debugging)

SDK

First step, install the Unity Plugin which includes our Hathora Cloud Unity SDK

using Hathora.Cloud.Sdk.Api; using Hathora.Cloud.Sdk.Client; using Hathora.Cloud.Sdk.Model;

private readonly RoomV2Api roomApi; this.roomApi = new RoomV2Api(base.HathoraSdkConfig);

createRoomResult = await roomApi.CreateRoomAsync( AppId, createRoomReq, _customCreateRoomId, _cancelToken);

Unity Plugin

Console

tip

To learn more about room creation and lifecycle, check out our Room Lifecycle docs

5. Connecting to a room

Once you have created a room, it will take Hathora Cloud a few seconds to spin up your server instance and expose a port for your client to connect to.

From your client, we recommend polling RoomApi.GetConnectionInfo(appId, roomId) until status is "active" and ExposedPort is not null.

note

We will automatically terminate a process if there are no active connections for 5 minutes (i.e. the process is in an idle state for 5 minutes).

To see a working example, check out our example usage.

tip

With our Unity Plugin and our Hathora Console, you can get connection info (host:port) directly, which is useful for testing and debugging.

6. Lobby Service and integration with matchmakers

Check our Lobby Service for a lightweight way to build a lobby system for your game.

Join our developer community!

Discord