Migration Guide: Hathora to AccelByte Multiplayer Servers (AMS)

This guide is specifically designed for technical teams migrating from Hathora Cloud to AccelByte Multiplayer Servers (AMS). It maps the core API concepts and outlines the code-level changes required for a successful transition. 

1. Architectural Concept Mapping

While both platforms are container-native orchestrators, they use different terminology for similar resources.

2. Step-by-Step Migration Workflow

Step 1: Integrating with the Watchdog

In AMS, the server communicates with a local agent called the Watchdog.

• The SDK: Use the AGS Game SDK (Unity or Unreal Engine plugins), which automatically takes care of connecting to the watchdog and periodic heartbeats

• The Ready Signal: signal the watchdog when the server is done with any initialization or preparation work and is ready to be allocated to a game session.

• Details: See the Code-Level Changes section for specific implementation examples and required launch arguments.

Step 2: Build & Upload

• Hathora: Uses hathora-cloud CLI to push Docker builds.
• AMS: Uses the AMS CLI which you can download from the Admin Portal (AMS → Download Resource). Upload your build folder directly from your local machine.
• No need to build or manage a container. Simply point the AMS CLI at your build directory, and it will package and upload your build for you.
• Reference: See the full guide on how to upload a dedicated server build

Step 3: Infrastructure Configuration

Create and configure your Fleets in the Admin Portal.

The primary difference in scaling logic is how the platforms handle capacity. Hathora relies on resource utilization (vCPU), whereas AMS uses a Buffer system for more predictable availability.

• Hathora (Resource-Based): Scaling is typically configured based on vCPU utilization thresholds. This can sometimes lead to "cold starts" if the CPU spikes faster than the orchestrator can provision new rooms.
• AMS (Availability-Based): You create Fleets using a Buffer system. AMS scales to maintain a specific number of "Ready" servers at all times, ensuring near-instant connections.
• Regional Granularity: The buffer setting is per region. This allows you to optimize costs by setting a smaller buffer (e.g., 5) in lower-population regions like us-west and a larger buffer (e.g., 20) in high-traffic regions like eu-central.

Reference: For a deep dive into regional settings and instance types, see Create fleets to deploy dedicated servers.

3) Code-Level Changes

A. Launch Arguments & Port Discovery

Hathora injects connection details via environment variables (e.g., HATHORA_DEFAULT_PORT) or their GetConnectionInfo API. In contrast, AMS uses argument substitution to pass data directly to your server executable at startup.

• AMS Launch Logic: In the Admin Portal, you configure the launch command using placeholders like ${default_port} and ${dsid}. AMS replaces these with actual values when the server instance spins up.

# ${dsid} and ${port} are placeholders which AMS will replace at runtime.
# Add engine-specific flags as needed (e.g., -log for Unreal Engine).
./MyServer.exe -dsid=${dsid} -port=${default_port}

• Key Requirement: Your server binary must be capable of parsing the Port from the command line.
• Flexibility: While we use -port in the example, you can use whatever flag your engine prefers as long as you map the AMS placeholders to them in your configuration.

B. Implementing the "Ready" Signal

Your server must notify the AMS Watchdog once it has finished loading assets and is ready to accept player connections.

Hathora (SDK):

import { HathoraCloud } from "@hathora/cloud-sdk-typescript";
// Hathora detects readiness via the container status or custom health checks

AMS (AGS Game SDK):

For AccelByte, you must explicitly call the "Ready" message. Below are the standard snippets for Unity and Unreal: 

AccelByteSDK.GetServerRegistry().GetAMS().SendReadyMessage();

AccelByteOnlineSubsystemPtr->GetServerApiClient()->ServerAMS.SendReadyMessage();

Full Integration Guide: For detailed setup instructions and additional engine-specific logic, refer to the Integrate Dedicated Servers with the SDK documentation.

C. The Claiming Flow (Backend Side)

The way you connect a player to a server changes.

• Hathora API Call: POST /rooms/v2/{appId}/create returns a roomId.
• AccelByte (Standard Flow): If you use the AGS Session Service, claiming is fully automatic. After matchmaking or creating a session, the Session Service claims a server from AMS and provides the connection info to the players.
• AccelByte (Custom Flow): You only need to call the Claim endpoint directly if you are using a custom matchmaking or session management solution.

Claim Endpoint (Custom Backends Only):

• Method: PUT /ams/v1/namespaces/{namespace}/fleets/{fleetID}/claim
• Response: You receive the ip and ports (a map of port name → port number) for the claimed server.

Integration Resources:

• Configure sessions to claim DSes from AMS
  

• Dedicated Server Claim Flow
  

• AMS Quickstart: Claiming Dedicated Servers

4) Lifecycle Comparison 

In AMS, the Watchdog manages the server lifecycle based on specific states. Unlike Hathora, which often relies on external health checks, AMS relies on messages from the game server to explicitly communicate its readiness status via the AGS Game SDK.

Drain Handling

When a fleet is updated or scaled in, AMS sends a Drain signal. To prevent players from being kicked mid-match, your server should listen for this signal, finish the current session, and then exit gracefully.

AccelByteSDK.GetServerRegistry().GetAMS().OnDrainReceived += () => {
	// finish current match, stop accepting new players, then exit
};

AccelByteInstance->GetServerApiClient()->ServerAMS
	.AddOnAMSDrainReceivedMulticastDelegate(
	ServerAMS::FOnAMSDrainReceived::CreateLambda([&]() {
	// if in session, finish the session and exit, else cleanup and exit right away
	}));

Integration Resources: 

• Standard Integration: For full step-by-step setup, see the Full SDK Integration Steps.
• Custom Engines: If your game engine does not have an official AccelByte SDK, you can still use AMS by implementing the AMS Watchdog Protocol.

5) Summary Checklist

1. Strip Hathora SDKs: Remove any Hathora-specific libraries.
2. Install AGS Game SDK: Download and integrate the Unity or Unreal plugin into your game server project.
3. Update CLI Arguments: Set up your server to parse -port, if it doesn’t already
4. Update Matchmaking: Change your backend flow from "Create Room" (Hathora) to "Claim Server" (AMS).

Validation Tip: Run your server locally with the AMS Local Watchdog simulator (available in the AccelByte docs) to test the heartbeat logic before uploading to the cloud.