Match Capacity #

The Match Capacity service is responsible for processing game instance requests and coordinating with a game server management provider to allocate game servers. This includes configuration to support maintaining a headroom of available capacity to keep servers ready ahead of time, and configuring capacity limits.

All active game servers are expected to report their capacity to this service on a regular cadence. In response to these capacity reports, the game server may receive game instances to start. The service uses the CapacityProvider plugin to allow for support for a variety of hosting strategies.

Pragma Engine supports several game server hosting solutions, providing first-party support and integration across cloud providers and independent options.

Capacity Provider #

The CapacityProvider plugin interacts with the MatchCapacityService in defining how to add more capacity in order to fulfill a game instance request. Once the MatchCapacityService has determined that there is not currently enough capacity running to fulfill a game instance in a given gameServerVersion and gameServerZone, the CapacityProvider.add plugin method is called to generate additional capacity onto the service.

Capacity Provider Plugin Methods #

The CapacityProvider plugin provides an abstract interface for defining a game server capacity model. The table below contains a full list of all the CapacityProvider plugin methods.

Methoddescription
addGenerates and registers additional capacity onto the service
initProvides an HttpClient to communicate with external resources for capacity
shutdownExecutes during Pragma service shutdown. Use to perform any cleanup tasks.

Report Capacity #

All game servers must regularly call the reportCapacityV2 endpoint to report their current capacity status. The poll frequency is configurable via MatchCapacityConfig. After starting to poll, a game server may receive game instance ids to start in the GameStart payload. Once the game server starts the requested games, it should then call the connectPlayersV1 endpoint with the appropriate connection details.

Match Capacity Service

The Pragma SDK provides a MatchApi.StartReportCapacityPolling method that is the recommended way to have the game server report its capacity to the MatchCapacityService. It should be called as soon as possible when the game server is spun up, and it will trigger a OnGameStart event when a game allocation arrives or a OnGameStartFailed if any error occurs.

The MatchApi.StartReportCapacityPolling method takes in an optional timeout parameter for how long to wait for the first game allocation to the game server. If a game allocation does not arrive to the game server in the defined timeout, then a OnGameStartFailed event is triggered. If you do not want to use the timeout, provide a value of 0 for the timeout parameter.

Match Capacity SDK Methods #

The SDK includes methods for Match Capacity service implementation through the MatchApi class. The following table lists the methods in the MatchApi class relevant to the Match Capacity service.

MethodDescription
StartReportCapacityPollingLets the platform know that the game server exists and begins to reports its capacity in an interval waiting for a game allocation.
ReleaseCapacitySets the used capacity to 0 for the next report capacity call, allowing for a new game allocation.

Match Capacity RPCs #

The following list includes the MatchCapacityService RPCs.

  • reportCapacityV2
  • startMatchV1

Game Instance SDK and Events
Error Handling