Fleet Service Reference #

Fleet service SDK #

The table below contains a list of the SDK methods related to capacity management and game server reporting. These methods are available via the MatchApi.

Calldescription
ReportFreedCapacityReports to Pragma Engine that the game server has freed up a unit of game instance capacity
StartReportCapacityPollingLets the platform know that the game server exists and begins to reports its capacity for hosting game instances
UpdateMaxGameInstanceCountAllows a game server to reconfigure its max game instance count after report capacity polling has started

Fleet service plugins #

FleetPlugin #

FleetPlugin provides an abstract interface for defining a game server fleet management model.

FleetGameServerProviderPlugin #

Data classes #

ServerPool #

The ServerPool class contains data for the server pools in your environment.

propertydescription
serverPoolIdUnique ID for the server pool
managementPolicyIdUnique ID for the server pool management policy associated with this server pool
extThe ExtServerPool payload containing extra information that can be used when allocating game servers

GameServerAllocation #

The GameServerAllocation class maps game servers with the PartnerClientTokens it should use when authenticating to Pragma.

propertydescription
serverIdUnique server ID
pragmaTokensPartnerClientTokens to use when authenticating to Pragma

PartnerClientTokens #

The PartnerClientTokens class contains data for partner client tokens that the game server should use when authenticating to Pragma.

propertydescription
gameTokenPartner client token to use when authenticating to Pragma game backend
socialTokenPartner client token to use when authenticating to Pragma social backend

Configuration #

Server pool management policy configuration #

The ServerPoolManagementPolicyConfig configuration block provides a place to define values for server pool management policies. The following configuration values are available in the game: serviceConfigs: FleetServiceConfig: serverPoolManagementPolicies: block

configdescription
idUnique ID for this server capacity pool management policy
gameCapacityPerServerMaximum number of game instances that can run on a single game server. Value must be at least 1.
capacityFloorMinimum game capacity allocated at all times
capacityCeilingMaximum game capacity allocated at all times
capacityBufferPreferred available game capacity defined as a percentage of used game capacity
serverMaxStartDurationMillisMaximum duration, in milliseconds, a game server can take to start before the allocation is declared failed
serverHeartbeatPeriodMillisMillisecond interval at which a game server should report its capacity
serverHeartbeatExpiryFactorNumber of heartbeats that can be missed before a game server is considered unresponsive
gameCapacityResolvedTimeoutMillisMaximum duration, in milliseconds, the platform will wait for capacity to resolve for a game instance before ejecting it
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.

Extension data #

extdescriptionexample data
ExtAllocateGameServerData to assist in game server allocation. Defined in the gameInstanceExt proto file and used in the Fleet service to determine which server pool to assign for the game instance.game mode (3v3, 1v1, etc.) or game version (beta, trial, etc.)
ExtServerPoolPopulated by the Fleet Plugin selectServerPool method and used when allocating game serversgame mode (3v3, tutorial, etc.) or game version (0.4, 0.5, etc.)

Events #

The following events are related to capacity management and game server reporting.

EventTriggerData returned
OnGameStartA game instance is started. The game server receives game instance data on this event.GameStart
OnGameStartFailedAn error occurs while attempting to start a game instance. The game server will not continue reporting capacity or receiving new game instances until StartReportCapacityPolling is called again.Pragma error
OnKeepAliveFailedThe platform fails to process a keep alive requestgame instance ID, Pragma error
OnGameInstanceTerminatedThe platform decides to terminate an in progress game instance. An example of this firing is when a game instance has failed to heartbeat due to connection issues to the platform. Calling EndGame will not cause this event to fire.game instance ID, termination reason

Errors #

  • FleetService_GameServerVersionMismatch
  • FleetService_ServerPoolNotFound
  • FleetService_ServerPoolManagementPolicyConfigNotFound
  • FleetService_AllocationError
  • FleetService_InvalidLauncher
  • FleetService_MultiplayRegionIdNotDefined
  • FleetService_MultiplayAllocateForError
  • FleetService_UnexpectedResponse
  • FleetService_UnparseableResponse
  • FleetService_UnsuccessfulResponse