Skip to main content

Integration guide

This guide will help walk you through the steps required to integrate and deploy your multiplayer game on Hathora Cloud.

1. Preparing your server​

Hathora Cloud is engine agnostic, allowing you to deploy multiplayer games built using any engine, framework, or library. Node.js is the most common server stack, but any server that can be containerized will work with Hathora Cloud.

For web games, you need to handle WebSocket or WebTransport client connections to your server.

Some popular JS libraries/frameworks that help with this are:

  1. socket.io
  2. ws
  3. uWebSocket
  4. Colyseus

2. Generating a Dockerfile​

By providing a Dockerfile at the root of your server project, we will be able to scale your server across the globe.

Sample Node.js Dockerfile:

FROM node:18-alpine # node version

COPY . .            # copy project files

RUN npm install     # install dependencies
RUN npm run build   # build project

# Add these dependencies to enable your server to make outbound TLS requests
RUN apk update && apk upgrade && \
  apk add ca-certificates && \
  update-ca-certificates

CMD npm start       # start server

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 2 ways to deploy your server on Hathora Cloud:

  1. With command line or CI/CD pipeline
  2. Drag and drop upload via Hathora Console
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
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 2 ways to create rooms on Hathora Cloud:

  1. Via API call
  2. Directly with Hathora Console (great for debugging)

A simple API call: RoomApi.CreateRoom(appId).

You can use the Hathora Cloud TypeScript SDK to easily integrate your game with our APIs. Note, for some API calls you will need your Hathora developer token to authenticate your requests.

import { RoomV2Api } from "@hathora/hathora-cloud-sdk";

const developerToken = env_variable.DEVELOPER_TOKEN;

const roomClient = new RoomV2Api();

const room = await roomClient.createRoom(
    appId, // your Hathora application id
    {
        region: "Seattle",
    },
    roomId, // (optional) use to set custom roomIds
    { headers: { Authorization: `Bearer ${developerToken}`, "Content-Type": "application/json" } }
)
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.

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).

tip

With 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.

tip

Check out our Bullet Mania guide, for an open-source sample game showcasing working client integration.

Join our developer community!
Discord