Fleet Service Tasks #
Using the Fleet Plugin and the Fleet service section of your YAML configuration file, you can define and customize game server capacity features.
Using the Fleet service, you can:
- Initialize Fleet service
- Enable the use of server pools
- Configure server pool management policies
- Map server pool management policies to one or more server pools
- Define custom server pool data to inform server pool selection
- Build logic to select server pools for game instance allocation requests
- Assign server pool for unrecognized game servers
- Start capacity polling
- Set or update the number of game instances that can run on a server
- Report when capacity is freed from a game server
- Retrieve game instance IDs that have been allocated by Pragma
- Allocate additional game servers
- Bypass the Fleet service
Initialize Fleet service #
When the platform starts, the Fleet service calls the Fleet Plugin init
method to provide an HTTP client through which it can communicate with external resources for capacity.
fun init(
client: TimedHttpClient
)
Consider inheriting DefaultFleetPlugin
for an implementation of this.
Enable use of server pools #
For Pragma Engine version 0.0.97, you must explicitly enable the use of server pools to take advantage of the Fleet service features. If you leave useFleetService
set to false (default), the legacy Match Capacity service will be used instead.
The Match Capacity service is deprecated in Pragma Engine version 0.0.97. Fleet service will be required starting with version 0.0.98.
To enable server pools in your environment, set the useFleetService
value in the GameInstanceServiceConfig
block in your configuration YAML file to true
. You must supply at least one serverPoolManagementPolicyConfig
block to the FleetServiceConfig
section (see the next task in this topic).
game:
serviceConfigs:
GameInstanceServiceConfig:
useFleetService: true
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 a description of each field, see the Fleet Service Components topic’s Server Pool Management Policy Configuration table.
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: 300_000
serverHeartbeatPeriodMillis: 1000
serverHeartbeatExpiryFactor: 5.0
gameCapacityResolvedTimeoutMillis: 60_000
2:
id: "LOW_POPULATION"
gameCapacityPerServer: 5
capacityFloor: 0
capacityCeiling: 25
capacityBuffer: 10
serverMaxStartDurationMillis: 300_000
serverHeartbeatPeriodMillis: 1000
serverHeartbeatExpiryFactor: 5.0
gameCapacityResolvedTimeoutMillis: 60_000
3:
id: "NORTH_AMERICA_REGION"
gameCapacityPerServer: 2
capacityFloor: 75
capacityCeiling: 400
capacityBuffer: 25
serverMaxStartDurationMillis: 300_000
serverHeartbeatPeriodMillis: 1000
serverHeartbeatExpiryFactor: 5.0
gameCapacityResolvedTimeoutMillis: 60_000
Consider whatcapacityFloor
andcapacityCeiling
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,
extHostRequest: ExtHostRequest
): ServerPool
The method returns a new or existing ServerPool
object to the allocation request.
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
Start capacity polling #
All game servers must regularly report their available capacity to the Fleet service. To begin this process, call the MatchApi.StartReportCapacityPolling
SDK 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 Pluginadd
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 of0
for thetimeout
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 is allocated to this game server, its game data will be passed to the OnGameStart
event. 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.
Set or update game instance count per server #
By default, Pragma allows one game instance per server. To increase this number and host multiple game instances on a single server, set the gameCapacityPerServer
value in the server pool management policies. When the server starts reporting capacity, pass the same value as the MaxGameInstanceCount
parameter in the MatchApi.startReportCapacityPolling
method.
A game server can reconfigure its max game instance count after capacity polling has started by calling MatchApi.UpdateMaxGameInstanceCount
with a new maxGameInstanceCount
value.
Report freed server capacity #
When a game instance ends, if the game server expects to receive subsequent game instances, the host game server should tell the engine that its used capacity has decreased. To do so, the game server should call MatchApi.ReportFreedCapacity
when a game instance ends. This method tells the Pragma capacity tracker that more room is available for additional game instances.
At this point, the game server can call GameInstance.GetGameStartDataV1
to retrieve information about the game instance it is hosting . See Game Instance Tasks for more information on sending game instance data to game servers.
Retrieve game instance IDs allocated by Pragma #
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 Game Instance Tasks for more information on sending game instance data to game servers.
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 to generate additional capacity onto the service.
interface FleetPlugin {
suspend fun add(
serverPool: ServerPool,
allocations: List<UUID>
)
}
The serverPool
object passed to the add
method includes the server pool ID, the management policy ID, and the ExtServerPool
payload, all of which can be used when allocating game servers.
The add
method uses a list of Pragma-generated game server IDs (allocations: List<UUID>
) to prepare to track additional game servers for a specific server pool. The add
method allocates additional capacity on the Pragma side; you then provide the game server IDs provided in the allocations parameter to your game server provider when spinning up the servers.
The number of game servers to allocate is calculated using the values configured in the ServerPoolManagementPolicyConfig
configuration block associated with the server pool.
Bypass the Fleet service #
If you choose to not use Pragma’s Fleet service or Match Capacity service (deprecated as of version 0.0.97) and instead want to manually manage your game server capacity, implement the following:
Have the Game Instance Host Plugin’s
findHostForGameInstance
method returnnull
instead of aExtHostRequest
payload. Use thefindHostForGameInstance
method to integrate with your game server provider in order to allocate a game server for this game instance.Do not allow game servers to poll to report their capacity. To request game start data for a known game instance, use the
MatchApi.RequestStartGame
SDK methodAdd the following to your configuration file to prevent Pragma from spinning up Fleet/Match Capacity nodes:
- If currently using the Fleet service:
game: core: distributedServices: FleetService: nodeByInstanceId: 0: ~
- If currently using the Match Capacity service:
game: core: distributedServices: MatchCapacityService: nodeByInstanceId: 0: ~