Fleet Management Overview #

Fleet management refers to the process of managing a fleet of game servers. Because individual game server needs differ in configuration and scale, Pragma provides flexibility for game server allocation and orchestration. Developers can choose between using the Pragma Fleet service, or bypassing the service to use a third-party fleet management system, such as one included with their third-party game server provider.

Most studios will choose to use the Pragma Fleet service for development purposes, and switch to their third-party provider’s game server orchestration solution for production.

For studios using Hathora, GameLift, or Multiplay Managed Game Server Hosting (Clanforge), use Option 1 for production environments.

Option 1: Bypass the Pragma Fleet service #

If you choose to manage your game server capacity outside of Pragma, whether in development or production, implement the following:

  • Edit the findHostForGameInstance method. Have the Game Instance Host Plugin’s findHostForGameInstance method return null. Use the findHostForGameInstance method to generate partner tokens and integrate with your game server fleet manager 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 method

  • Prevent Pragma from spinning up Fleet service nodes. Add the following to your configuration files:

              0: ~

Option 2: Use the Pragma Fleet service #

The Pragma Fleet service is responsible for processing game instance requests and coordinating with the game server provider to allocate game servers. Within this service, you can customize the Fleet Plugin, or use one of the pre-built plugins listed in the table below. The customizable Fleet Plugin provides an abstract interface for defining a game server fleet management model, and allows developers to manage game server capacity for fulfilling game instance requests.

The following pre-built Fleet service plugins are ready to use out-of-the-box:

DefaultFleetPluginThis implementation does not allocate game servers. Includes one server pool with the default server management policy.Use as a placeholder while setting up your Pragma Engine
LocalProcessFleetPluginSelects server pools based on game server version.Use when running servers on a local development machine.
PragmaNomadFleetPluginSelects server pools based on game server version. All server pools map to the default server management policy.Use when running servers on Nomad in a development environment.
MultiplayFleetPluginThe Multiplay Fleet Plugin’s selectServerPool method uses a Multiplay regionId to determine a server pool. You map regionIds to Pragma gameServerZone values in the gameServerZoneToMultiplyRegionId block of your YAML configuration file.Use when running servers using Unity’s Game Server Hosting (Multiplay), but NOT using their fleet management services.

See Fleet Service Tasks for instructions on how to implement the various Fleet service methods.

You can view more details about the Fleet Plugin methods and their properties in the reference section of the documentation.

For development environments:

Regardless of your server orchestration choice for production, the Pragma Fleet service offers a Nomad game server environment to use during development. This environment uses the the PragmaNomadFleetPlugin to manage the game server allocation process, and closely reflects what you would use in a production environment. However, this method is not suitable for production.

Alternatively, you can choose to use use your third-party solution in development. To bypass the Pragma Fleet service, see Manage game server fleet capabilities outside Pragma.

Example fleet management flow #

Fleet service graph

When the Matchmaking service finds a match, the service generates a NewGameInstance to send to the Game Instance service. The Game Instance service executes the findHostForGameInstance method, which can return null or an ExtHostRequest payload, depending on whether or not you are using the Pragma Fleet service.

In environments not using the Pragma Fleet service:

The findHostForGameInstance method will return null. Further fleet management tasks will be handled by the third-party fleet management provider.

In environments using the Pragma Fleet service:

The findHostForGameInstance is used to generate an ExtHostRequest containing relevant NewGameInstance information to send to the Fleet service. With this information, the Fleet service puts in an allocation request as well as selects an appropriate server pool for this new game instance. The allocation request is placed in a queue to wait for a game server it can be allocated to.

Meanwhile, the Pragma Engine internal capacity manager automatically reviews the allocation request queue to determine whether or not a game server’s reported capacity can accommodate the request. If there is insufficient capacity, the Fleet service allocates additional capacity on the Pragma side and returns a list of game server IDs for you to use when spinning up additional game servers to support the pending allocation requests.

Every time a game server reports its available capacity, the Fleet service finds queued allocation requests assigned to the game server’s server pool. Based on the server’s reported available capacity, the Fleet service provides the game server with a list of game instance IDs ready to run.