Server Pool Management #

Configure server pool management policies #

Using the Fleet service section of your YAML configuration file, you can define how much capacity the service should maintain. Additionally, you can configure how many game instances a server can run, how long your game servers have to allocate a game, how often they should report their capacity to the Fleet service, and how long the service should wait for a report to arrive before considering a game server timed out.

You set the server pool management policies values in the configuration file ServerPoolManagementPolicyConfig block.

For example, the following configuration file defines three server pools, each with different default values. The 3v3_MODE is intended for game servers hosting games with this mode. The LOW_POPULATION pool is intended for game servers that host games infrequently, for example, a tutorial game mode. The NORTH_AMERICA_REGION pool is intended for servers in a specific region, which allows for customization based on the geographical distribution of your players.

game:
  serviceConfigs:
    FleetServiceConfig:
      serverPoolManagementPolicies:
        1:
          id: "3v3_MODE"
          gameCapacityPerServer: 1
          capacityFloor: 200
          capacityCeiling: 10000
          capacityBuffer: 40
          serverMaxStartDurationMillis: 300000
          serverHeartbeatPeriodMillis: 1000
          serverHeartbeatExpiryFactor: 5.0
          gameCapacityResolvedTimeoutMillis: 60000
        2:
          id: "LOW_POPULATION"
          gameCapacityPerServer: 5
          capacityFloor: 0
          capacityCeiling: 25
          capacityBuffer: 10
          serverMaxStartDurationMillis: 300000
          serverHeartbeatPeriodMillis: 1000
          serverHeartbeatExpiryFactor: 5.0
          gameCapacityResolvedTimeoutMillis: 60000
        3:
          id: "NORTH_AMERICA_REGION"
          gameCapacityPerServer: 2 
          capacityFloor: 75 
          capacityCeiling: 400 
          capacityBuffer: 25
          serverMaxStartDurationMillis: 300000
          serverHeartbeatPeriodMillis: 1000
          serverHeartbeatExpiryFactor: 5.0
          gameCapacityResolvedTimeoutMillis: 60000

If setting gameCapacityPerServer to a value other than 1, see Run multiple game instances per server.

Consider what capacityFloor and capacityCeiling values are appropriate for your environment. Setting these values too low or too high can lead to undesirable game instance load.

Map server pools to server pool management policies #

To associate one or more server pool management policies with a server pool, set the server pool’s managementPolicyId value to the desired server pool management policy ID. In this example, we’ve defined the mapping in the plugin configuration section of the configuration file. We’ll fill in the additional custom data in the next step.

//Server Pools
{
    "serverPoolId": "pool1"
    "managementPolicyId": "3v3_MODE"
}
{
    "serverPoolId": "pool2"
    "managementPolicyId": "LOW_POPULATION"
}

{
    "serverPoolId": "pool3"
    "managementPolicyId": "NORTH_AMERICA_REGION"
}

Define custom server pool data #

You can define custom data to send to your game server hosting platform to help determine what server to spin up when capacity is added. This information is defined in the ExtServerPool payload. The ExtServerPool payload is populated by the Fleet Plugin selectServerPool method and returned on the ServerPool object, which, in turn, is used when adding capacity.

message ExtServerPool{
    String region;
    Int profileId;
}

In the following example, we put the custom server pool data in the plugin configuration section of the configuration file:

//Server Pools
{
    "serverPoolId": "pool1"
    "managementPolicyId": "3v3_MODE"
    "regionIds": ["us", "eu", "br"]
    "profileId": 1
    "supportedVersion": "0.48.3"
    "supportedModes": ["3v3_Ranked", "3v3_Casual"]
},
{
    "serverPoolId": "pool2"
    "managementPolicyId": "LOW_POPULATION"
    "regionIds": ["us", "eu", "br"]
    "profileId": 2
    "supportedVersion": "0.48.3"
    "supportedModes": ["tutorial"]
},
{
    "serverPoolId": "pool3"
    "managementPolicyId": "NORTH_AMERICA_REGION"
    "regionIds": ["us"]
    "profileId": 3
    "supportedVersion": "0.48.3"
    "supportedModes": ["3v3_Ranked", "3v3_Casual"]
}

Build server pool selection logic #

The Fleet Plugin’s selectServerPool method is where you define logic that determines what server pool should be used when allocating game servers for the given game allocation request.

You can use the game server version, game server zone, or custom-defined data to inform this logic.

fun selectServerPool(
  gameServerVersion: GameServerVersion,
  gameServerZone: GameServerZone,
  ext: ExtAllocateGameServer
): ServerPool

The method returns a new or existing ServerPool object to the allocation request. The ServerPool object includes the server pool ID, the management policy ID, and the ExtServerPool payload, all of which can be used when allocating game servers.

Assign server pool for unrecognized game servers #

The Fleet service executes the Fleet Plugin getServerPoolById method when Pragma does not recognize the game server reporting its capacity. This situation can occur when the Pragma platform restarts while game servers are still running or if you are developing on a local game server not allocated via the Fleet service. The getServerPoolById method will associate the provided server pool ID with a new or existing server pool, according to the logic you define in the method.

fun getServerPoolById(
  serverPoolId: String
): ServerPool