Report and Allocate Capacity #

Start capacity polling #

All game servers must regularly report their available capacity to the Fleet service. To begin this process, call the MatchApi.StartReportCapacityPolling() API method as soon as the game server is spun up so that the game server can report its capacity to the Fleet service as soon as possible.

The StartReportCapacityPolling() method accepts the following parameters:

• ServerId - ID for the server that should start reporting its capacity. This value will be provided by the Fleet Plugin add function, and should be passed to the game server provider as it spins up the server. If you provide an unrecognized server ID, Pragma will start tracking the server and log an unrecognized server message.
• ServerPoolId - Server Pool ID for the server that should start reporting its capacity. This value will be provided by the Fleet Plugin add function, and should be passed to the game server provider as it spins up the server.
• Timeout - Defines how long to wait for the first game allocation to the game server. If you do not want to use the timeout, provide a value of 0 for the timeout parameter.
• MaxGameInstanceCount - Number of game instances that can run on this server. Default is 1.

You can specify the expected poll frequency using serverHeartbeatPeriodMillis in the ServerPoolManagementPolicyConfig configuration block.

Consider what timeout value is appropriate for your environment in case the server fails to start.

Server->MatchApi()->StartReportCapacityPolling(
  FString ServerId,
  FString ServerPoolId, 
  float Timeout, 
  int32 MaxGameInstanceCount = 1
);

Server.MatchApi.StartReportCapacityPolling(
  string serverId, 
  string serverPoolId,
  float timeout, 
  int maxGameInstanceCount = 1
);

When a game server reports its available capacity to the Fleet service, the Fleet service reviews the allocation request queue for allocation requests that contain game instances assigned to the server pool the reporting game server belongs to. Depending on the reported available capacity, the Fleet service will send the game server a list of game instance IDs for the server to host.

At this point, the game server will receive the OnGameStart event with information about the game instances it is hosting. See Connect Game Servers to Pragma Backend for more information on sending game instance data to game servers.

If an error occurs while attempting to start a game instance, you will receive an OnGameStartFailed event and the game server will not continue reporting capacity or receiving new game instances until StartReportCapacityPolling() is called again.

Related events:

• OnGameStart
• OnGameStartFailed

Allocate additional game servers #

If the Fleet service determines that the current available capacity cannot fulfill a request to create a game instance in a given server pool, the Fleet Plugin’s add method is called.

interface FleetPlugin {
  suspend fun add(
    serverPool: ServerPool,
    allocations: List<GameServerAllocation>
  )
}

The add method accepts a specific ServerPool and a list of GameServerAllocation objects, which map game servers IDs with the PartnerGameAuthTokens they should use when authenticating to Pragma. You can use the add method to provide the game server with these partner tokens, as shown in the following example:

suspend fun add(serverPool: ServerPool, allocations: List<GameServerAllocation>) {
  for (allocation in allocations) {
    ...
    val dispatchRequest = mapOf(
      META to mapOf(
        ...
        PARTNER_GAME_AUTH_TOKEN to allocation.pragmaTokens.gameToken,
        PARTNER_SOCIAL_AUTH_TOKEN to allocation.pragmaTokens.socialToken,
      )
    )
	 ...
  }
}

Each game server requires a set of partner tokens, regardless of how many game instances that game server can run at once.