Components:

• Pragma Engine
• Hathora Cloud API
  • Core API docs: https://hathora.dev/api
  • Java SDK: dev.hathora.cloud-sdk
  • Unreal/C++ SDK: hathora-unreal-sdk
• HathoraGameServerProviderPlugin
  • This is the plugin to integrate Hathora with Pragma

Steps:

1. Initial Pragma 0.2.0 (or later) setup
2. Add custom parameters for ExtAllocateGameServer

   • File to update:/platform/5-ext/ext-protos/src/main/proto/shared/gameInstanceExt.proto

   • Required parameter: desiredRegion

     • Should map to valid Hathora region (e.g. “Seattle”, “Washington_DC”, “Frankfurt”)
       • List of Hathora Regions

     /**
      * Allocation payload for a game server. Populated in any method of the [GameInstancePlugin] and used in the
      * [GameServerProviderPlugin.startAllocationForGameInstance].
      */
     message ExtAllocateGameServer {
         string desired_region = 1;
     }
     

   • Can also easily extend ExtAllocateGameServer to include any other custom fields

     • 💡Tip: Works great with Hathora’s flexible roomConfig object to pass customer metadata to your game servers.

   • Relevant Pragma docs: https://pragma.gg/docs/0.2.0/concepts/multiplayer/gameinstance/game-instance-tasks#allocate-a-dedicated-game-server

   • Alternatively, you can also use gameServerZone instead of ExtAllocateGameServer

3. Add HathoraGameServerProviderPlugin plugin

   • Download Plugin code here

   • Add plugin file to project

   • Add maven dependency for Hathora Java SDK to 5-ext/ext/pom.xml

     <dependency>
     	  <groupId>dev.hathora</groupId>
         <artifactId>cloud-sdk</artifactId>
         <version>2.11.3</version>
     </dependency>
     

   • Setup config values for Hathora AppId and DevToken

     • hathoraAppId
     • hathoraDevToken (encrypted) - this should be your Hathora API token
       • Hathora API token generation: https://hathora.dev/docs/guides/generate-developer-token
       • Pragma encryption docs: https://pragma.gg/docs/0.2.0/concepts/customization/configuration/#secret-encryption

       pluginConfigs:
         GameInstanceService.gameServerProviderPlugin:
           class: "demo.gameinstance.HathoraGameServerProviderPlugin"
           config:
             hathoraAppId: ""
             hathoraDevToken: ""
     

   • With this step, servers should be spun up for matches

4. Using the HathoraGameServerProviderPlugin
   • If you are migrating from an older version of Pragma, you can read these release notes to learn more about the differences from the old plugin: https://pragma.gg/docs/0.2.0/updates-release-notes/0.2.0/integrations-0.2.0#game-server-provider-plugin-formerly-game-instance-host-plugin-changes

Integrating your server with Hathora APIs

There are multiple ways to integrate with Hathora APIs:

1. Using Hathora's default environment variables
2. Make API calls from your init script (.sh)
3. Hathora's Unreal SDK

Add init script or game server logic to request info from Hathora API and callback to Pragma

1. Get the server connection info (i.e. host:port) for your server process
   • [Recommended] Via default environment variables HATHORA_HOSTNAME and HATHORA_DEFAULT_PORT.
     • These environment variables will be immediately available upon process startup, so you can access them in your init script or game server.
   • Call ProcessesV3.GetProcess
     • May need a retry or short poll on this endpoint if calling right at server startup (brief window where host/port may be undefined)
     • This will provide server connection info (i.e. host:port) as well as other server details
2. Get the relevant room data for the match (i.e. roomId and roomConfig)
   • [Recommended] Via default environment variable HATHORA_INITIAL_ROOM_CONFIG.
     • This path works for most use cases, but there are some cases where this won't work (if multiple rooms per process or if needed to spin up processes without rooms)
   • Call RoomV2.GetActiveRoomsForProcess
     • This will return all active rooms (will include roomId and roomConfig)
     • Can be called via init script, as well
   • Use roomConfig data to callback to Pragma

Detailed Hathora pragma plugin steps:

1. Add Hathora plugin to project
   • HathoraGameServerProviderPlugin.kt added to path: platform/5-ext/ext/src/main/kotlin/demo/gameinstance/
   • Add Hathora Java SDK dependencies to platform/5-ext/ext/pom.xml
     • Hathora Java SDK dependency:
   • Add plugin config to /5-ext/config/local-dev.yml
     • Config changes: