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
• HathoraGameInstanceHostPlugin
  • This is the plugin to integrate Hathora with Pragma

Steps:

1. Initial Pragma 0.0.97 setup
   • For Pragma v0.2.0 and later, check out this updated guide
2. Logic to set gameServerZone to desired region
   • Should map to valid Hathora region (e.g. “Seattle”, “Washington_DC”, “Frankfurt”)
     • List of Hathora Regions
3. Add HathoraGameInstanceHostPlugin 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.gameInstanceHostPlugin:
           class: "demo.gameinstance.HathoraGameInstanceHostPlugin"
           config:
             hathoraAppId: ""
             hathoraDevToken: ""
     

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

4. Using the HathoraGameInstanceHostPlugin
   • If you were already using the Fleet Management (Nomad), you can now bypass it: https://pragma.gg/docs/0.0.100/concepts/multiplayer/fleetmanagement/fleet-management-overview

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
   • HathoraGameInstanceHostPlugin.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: