Allocate Game Servers #

This topic provides instructions on initiating game server allocation for various scenarios.

Initiate server allocation #

If you are using the Pragma Fleet service for game server management, see Pragma Fleet Service.

Game server allocation is initiated by the Game Instance interface allocateGameServer() method.

interface GameInstance {
    fun allocateGameServer(ext: ExtAllocateGameServer)
}

GameInstance.allocateGameServer() can be called from any Game Instance Plugin method. When allocateGameServer() is called, your Game Server Provider Plugin implementation’s startAllocationForGameInstance() method is invoked.

suspend fun startAllocationForGameInstance(
    gameInstanceId: GameInstanceId,
    ext: ExtAllocateGameServer,
    clientTokenFunction: () -> PartnerClientTokens,
    gameServerVersion: GameServerVersion,
    gameServerZone: GameServerZone
)

The plugin implementation and method functionality is determined by your fleet management solution.

Allocate using third-party solution #

If you are using a third-party fleet management solution (such as GameLift, Hathora, or Multiplay), implement the startAllocationForGameInstance method as follows:

• Send the game instance ID to the game server so the game server can link back to the correct game instance
• Send data from the ExtAllocateGameServer payload to the game server. This should be information that the game server needs to allocate the correct server. For example, data may include preferred region or version, or data the game server needs on start, such as a map or game mode.
• Send partner session tokens to the game server using the clientTokenFunction parameter, as shown in the following example. Each game server requires a set of partner session tokens, regardless of how many game instances that game server can run at once.

For example:

suspend fun startAllocationForGameInstance(
    gameInstanceId: GameInstanceId,
    ext: ExtAllocateGameServer,
    clientTokenFunction: () -> PartnerClientTokens
) {
    val tokens = clientTokenFunction()
    val dispatchRequest = mapOf(
        META to mapOf(
            PARTNER_GAME_AUTH_TOKEN to tokens.gameToken,
            PARTNER_SOCIAL_AUTH_TOKEN to tokens.socialToken,
        )
    )
}

When you initiate the game server allocation process, Pragma generates a unique set of partner session tokens and passes them to the Game Server Provider plugin’s startAllocationForGameInstance() method.

Allocate for local development #

If you are running both Pragma Engine and a game server on a local machine, use the LocalProcessGameServerProviderPlugin, which is an implementation that will run a game server executable on the local machine. To do so, edit the GameInstanceService.gameServerProviderPlugin block of your local-dev.yml file. Include a path to your locally built game server.

game:
  pluginConfigs:
    GameInstanceService.gameServerProviderPlugin:
      class: "pragma.gameinstance.LocalProcessGameServerProviderPlugin"
      config:
        serverExecutablePath: "C:/path/to/game/server/executable.exe"
        serverLogDirectory: "."

Configure allocation timeout #

When a game server is allocated for a game instance, the game server needs to link with the game instance by calling getGameStartDataV1(). By default, the game server must link with the game instance within 3 minutes of allocation. To alter this value, set the gameServerAllocationTimeoutMillis config value.

game:
  serviceConfigs:
    GameInstanceServiceConfig:
      gameServerAllocationTimeoutMillis: 180000

If the game server does not call getGameStartDataV1() within the time frame defined by gameServerAllocationTimeoutMillis, allocation is marked as failed.

If using the Pragma Fleet Service, this configuration value should match the Fleet Service serverMaxStartDurationMillis config.

Handle allocation failures #

Game server allocation can fail if the Game Server Provider Plugin’s startAllocationForGameInstance() throws an exception, or if a game server doesn’t link to the game instance within the configured time frame (GameInstanceConfig.gameServerAllocationTimeoutMillis). To handle these situations, use the Game Instance Plugin’s onGameServerAllocationFailed() method. By default, this method ends the game instance.

interface GameInstancePlugin {
    suspend fun onGameServerAllocationFailed(
        gameInstance: GameInstance.GameInstance
    ) {
        gameInstance.end(mapOf())
    }
}

Related events and errors #

Related events:

• OnHostConnectionDetailsReceived
• OnFailedToAllocateGameInstance
• OnGameStart
• OnGameStartFailed

Related errors:

• GameInstanceService_GameServerAlreadyAllocated
• GameInstanceService_UnknownGameInstanceId
• GameInstanceService_CapacityRequestFailed