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.

Call	description
`ReportFreedCapacity`	Reports to Pragma Engine that the game server has freed up a unit of game instance capacity
`StartReportCapacityPolling`	Lets the platform know that the game server exists and begins to reports its capacity for hosting game instances
`UpdateMaxGameInstanceCount`	Allows a game server to reconfigure its max game instance count after report capacity polling has started

Data classes #

ServerPool #

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

property	description
`serverPoolId`	Unique ID for the server pool
`managementPolicyId`	Unique ID for the server pool management policy associated with this server pool
`ext`	The `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.

property	description
`serverId`	Unique server ID
`pragmaTokens`	`PartnerClientTokens` 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.

property	description
`gameToken`	Partner client token to use when authenticating to Pragma game backend
`socialToken`	Partner 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

config	description
`id`	Unique ID for this server capacity pool management policy
`gameCapacityPerServer`	Maximum number of game instances that can run on a single game server. Value must be at least 1.
`capacityFloor`	Minimum game capacity allocated at all times
`capacityCeiling`	Maximum game capacity allocated at all times
`capacityBuffer`	Preferred available game capacity defined as a percentage of used game capacity
`serverMaxStartDurationMillis`	Maximum duration, in milliseconds, a game server can take to start before the allocation is declared failed
`serverHeartbeatPeriodMillis`	Millisecond interval at which a game server should report its capacity
`serverHeartbeatExpiryFactor`	Number of heartbeats that can be missed before a game server is considered unresponsive
`gameCapacityResolvedTimeoutMillis`	Maximum 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 #

`ext`	description
`ExtHostRequest`	Data to assist in game server allocation. Populated by `GameInstanceHostPlugin.findHostForGameInstance` and used in the Fleet service to determine which server pool to assign for the game instance. Example value: game mode (3v3, 1v1, etc.) or game version (beta, trial, etc.)
`ExtServerPool`	Populated by the Fleet Plugin `selectServerPool` method and used when allocating game servers. Example value: game 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.

Event	Trigger	Data returned
`OnGameStart`	A game instance is started. The game server receives game instance data on this event.	GameStart
`OnGameStartFailed`	An 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
`OnKeepAliveFailed`	The platform fails to process a keep alive request	game instance ID, Pragma error
`OnGameInstanceTerminated`	The 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