Pragma Engine 0.4.x #

November 2024

Updates to Pragma Engine upgrading process:

We’re rolling out an improved process for upgrading Pragma Engine projects. Reach out to your customer support representative for help upgrading to the latest Pragma version.

We have available patches for this release; the latest version with patches is 0.4.1. See the Patches section below for details.

Highlights #

Players can directly create, join, and leave game instances without going through matchmaking

Player clients can send direct requests to create, join, or leave a game instance. This provides a better flow in situations where matchmaking is not required, and makes custom game creation easy. You can also perform these tasks from backend methods or custom services.

Easily handle refunds and chargebacks on major gaming platforms

Using the Orders service you can now manage the entire monetization process from selling items to processing refunds. We’ve also added support for PlayStation and updated the Game Operator Portal to include detailed order and fulfillment history, such as refund timestamps. For more details, see Orders and Fulfillment.

New Pragma CLI

We are excited to announce the new Pragma CLI. This tool will replace the now deprecated Makefile and includes a simplified Maven project structure, friendlier build and run commands, and includes built-in help functionality.

Key features:

• Setting up Intellij is easier, and modifications to the project structure result in fewer sporadic Intellij errors.
• 5-ext is no longer the required project folder structure! Your project can be named anything you’d like, such as your game codename. The 5-ext structure will continue to be supported, and future updates will provide instructions on migrating to the new pattern if desired. New projects will start with the nicer structure by default.

New Load Simulator makes it easier to author load tests and simulations

Pragma’s Load Simulator enables you to author scenarios that simulate large numbers of player clients. The simulator can be used for a variety of cases, including blended load testing, isolated stress testing, matchmaking simulation and tuning, and more. The Load Simulator replaces the now deprecated Loadtest tools. See the Load Simulator concepts for more information.

Self-serve Grafana dashboards

Grafana templates are now located in Pragma Engine, allowing studios to author and deploy dashboards that match the current engine version from buildkite without managed infrastructure assistance. When you are ready to update your project, please reach out to your customer support representative.

Additional features #

[Multiplayer] Access and update parties from backend services and plugins #

The new PartyApi helper class allows custom services and plugins to invoke the Party service. For example, other services can request updates to party data.

[Multiplayer] Query matchmaking from backend services and plugins #

The new MatchmakingApi helper class allows custom services and plugins to invoke the Matchmaking service. For example, any Pragma backend service can now determine whether a player is in matchmaking.

[Multiplayer] Manage game instance data from backend services and plugins #

The GameInstanceApi helper class now allows custom services and plugins to add/remove players to/from a game instance, and update game instance data.

[Multiplayer] Handle game server allocation timeouts #

We made the following improvements to better configure and handle game server allocation timeout:

• The new GameInstancePlugin.onGameServerAllocationFailed() method will be called when the game server allocation timeout elapses or the GameServerProviderPlugin.startAllocationForGameInstance() method throws an exception. The default implementation of onGameServerAllocationFailed() will clean up the GameInstance.
• We renamed the GameInstanceServiceConfig.gameReadyTimeoutMillis property to gameServerAllocationTimeoutMillis to more clearly represent the configuration’s responsibility. The value determines the maximum allowed time between when allocation starts and when the game server links with a game instance.
• We added a GameInstanceServiceConfig.connectPlayersTimeoutMillis config value, which determines the maximum allowed time between successful game instance allocation (game server links with game instance) and when the game server sends a connectPlayers request.

[Social] Get player presence from any Social service #

Any Pragma backend Social service can now view a player’s presence values by providing a player’s social ID.

Fixes & improvements #

• Multiplayer:

  • The Matchmaking service more frequently processes player join/leave requests within matchmaking, improving performance.
  • Players who enter matchmaking and go directly to a game, such as in cases where matchmaking isn’t needed, now receive an OnEnteredMatchmakingEvent. Previously, players would only receive an OnLeftMatchmakingEvent. Ensure your code expects this scenario.
  • You can now configure the interval, in seconds, between checking for expiration of timeouts on the Party or Game Instance service using PartyConfig.assessTimeoutIntervalSeconds and GameInstanceServiceConfig.assessTimeoutIntervalSeconds, respectively. Previously, these values were hard-coded.
  • We removed the PartyApi.RespondToInvite() function in the SDK in favor of the AcceptPartyInvite() and DeclinePartyInvite() functions. See the deprecation note for integration instructions.
  • The Matchmaking.Party.secondsInQueue() method now returns a long type instead of an integer.

• Social:

  • The PresenceApi.setRichPresence() backend method now returns a PragmaFailure, which includes Application Errors as well as Service Errors. Update usage of setRichPresence() to handle the new return type.

• Metrics:

  • The MetricsManager.metricsTimer now allows you to provide min/max duration and custom buckets for use in Grafana histograms, allowing you to capture timer metrics beyond the default 1ms-30s range.

  • Grafana dashboards now live inside Pragma Engine, allowing you to deploy the dashboard version that matches your Pragma Engine version via the existing buildkite tools. Contact us when you take this release as there are infrastructure changes that need to be made to support the new dashboard system.

  • We updated the following graphs to display values greater than 30 seconds:

    • Median Seconds in Queue [log scale]
    • 99th Percentile Seconds in Queue [log scale]
    • Player session lifespan - median duration
    • Player session lifespan - 99th percentile duration

• Most instances of the AccountService.NotFound Service Error have been changed to an Application Error. Additionally, several instances of AccountService_Error have also been converted. If you are expecting to receive an AccountService_NotFound or AccountService_Error, you may need to modify your code to check for the new Application Errors instead. These can be found in accountRPC.proto with the following naming scheme: *NotFoundApplicationError.

• Previously, RPC failures in the Unreal SDK logs were logged at the Log verbosity level. They are now more accurately logged at the Error verbosity level. We also added the error source to assist with debugging.

• The fireAndForget(), runForever(), and fireAndForgetIO() functions on the Service or the Service’s BackgroundManager are no longer Unit functions. These functions now return the Job that they create, allowing the caller to retain a reference to the Job. Users writing tests of services that execute these functions might need to add additional test training.

• Build and deploy system improvements include a command to restart a shard, and Buildkite jobs that display a summary of the deployed artifacts and their versions.

Doc changes #

• [Playstation] New guide for implementing the Orders service. Please reach out to your customer support representative for more information.
• [Load Simulation] New Load Simulator concepts on how to use Pragma’s Load Simulator to author scenarios that simulate large numbers of player clients.
• [Game Data] Revamped Game Data concepts with a more cohesive Overview page and a How-To guide on Creating a Content Data Catalog.

SDK compatibility #

Patches #

For information on updating to the latest Pragma version see Update Pragma Engine.

0.4.1 #

Fixed a bug where players were only allowed to have one party invite out at a time. Now players can send out as many invites as they want, but cannot send more than one to the same player. In these situations, the older invite is replaced with the new one.