Pragma Engine 0.5.x #

January 2025

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

Highlights #

Sell bundles, deluxe editions, and durable entitlements

Using the Orders Service you can now sell bundles, durable entitlements, and deluxe editions of your game on Steam, Epic, Xbox, Playstation, Twitch, in addition to the existing consumable and virtual currency capabilities.

Players may now join multiple game instances

The Game Instance Service now allows players to participate in multiple game instances at a time, enabling a wide range of new game flows. This ability is enabled by default. To limit this functionality, see the integration note.

Player Support can view and modify player’s data

We have added a detailed view of a player’s data in the game operator portal. You can also now call all player data operations that allow the OPERATOR session type. This lets you author operations for your customer support reps to fix and update player data as needed.

Additional features #

[Multiplayer] Handle parties immediately before they enter matchmaking #

The new Party Plugin handlePlayerEnterMatchmakingRequest() method allows developers to process matchmaking requests immediately prior to a party entering matchmaking. For example, you can use the new method to prevent matchmaking if the party is already in another game instance. The handlePlayerEnterMatchmakingRequest() method is processed before buildMakingKey(), buildExtMatchmakingParty(), and buildExtMatchmakingPlayer() methods.

[Multiplayer] Handle game instance removals and party expirations #

We added the following methods to the Game Instance Plugin to handle various game instance removal scenarios:

• onGameServerDisconnected() - Called when a game server disconnects. Use to handle game server disconnects.
• onGameServerFailedToConnectInitialPlayers() - Called when a game server fails to connect the initial players. Use to handle player connection timeouts.
• onGameServerFailedToConnectMorePlayers() - Called when a game server fails to connect more players. Use to handle player connection timeouts.
• onGameInstanceExpired() - Called when a game instance expires. Use to handle game instance expirations.

In addition, we added the onPartyExpired() method to the Party Plugin, which is called when a party expires.

[Monetization] Manage Xbox monetization with the Orders service #

We’ve added full support for Xbox entitlements including refunds and chargebacks. Contact your customer support representative for more information.

[Accounts] Allow players to gracefully leave login queue #

The new LeaveLoginQueue() method in the Unreal and Unity SDKs allows players to leave the login queue without shutting down their game client.

[Player Data] Build a more flexible player data model #

You can now define more flexible types in player data by defining nullable properties with: Component, PlayerDataRequest, and PlayerDataResponse. Note the nullable modifier is not supported with map or list types.

The following is an example of a Component that would store either: String, Int, Boolean, UUID, or Float data:

@SerializedName([epoch-seconds])
data class BasicValue(
    @FieldNumber(1) val type: String,
    @FieldNumber(2) var int: Int? = null,
    @FieldNumber(3) var string: String? = null,
    @FieldNumber(4) var boolean: Boolean? = null,
    @FieldNumber(5) var uuid: UUID? = null,
    @FieldNumber(6) var float: Float? = null
): Component {
    companion object {
        val stringType = String::class.simpleName!!
        val intType = Int::class.simpleName!!
        val boolType = Boolean::class.simpleName!!
        val uuidType = UUID::class.simpleName!!
        val floatType = Float::class.simpleName!!
        val validTypes = listOf(stringType, intType, boolType, uuidType, floatType)
    }
}

[Player Data] View and modify a player’s data through the Game Operator Portal #

The upgraded player data view in the Game Operator Portal allows you to modify a player’s data by calling player data operations. New capabilities include:

• Player Support can verify data and call custom operations. For example, you can implement an operation that grants 100 coins.
• Developers can verify player data is stored and updated as expected.

[Player Data] Easily reset player data dbs between playtests #

The following new operator RPCs allow you to clear player data dbs and reset the player data cache without restarting the environment:

• PlayerDataServiceRpc.ClearAllPlayerDataDbAndCacheOperatorV1Request
• PlayerDataServiceRpc.ClearAllPlayerDataCacheOperatorV1Request

These endpoints require you to opt in through the PlayerDataServiceConfig:

game:
  serviceConfigs:
    PlayerDataServiceConfig:
      enableDeleteAllPlayerData: true

Fixes & improvements #

• The backend Party.Party.sendInvite() method now returns a PartyInvite object for the newly created invite, so you no longer have to look at Party.invites to find it.

• The new MatchApi.SetRichPresence() method in the Unity SDK allows game servers to set a player’s rich presence.

• The Player Data Entity class includes new and updated methods:

  • Updated addComponent() method now returns the generated ComponentdId/UUID
  • New getComponentById() method accepts a componentId and returns the associated Component object.

• The Context interface’s new sessionType variable shows the session type for player data operations

• The GetOperationInfoOperatorV1() now throws NotFoundApplicationError when the given SKU ID is not found in the content mapping. If you are checking for FulfillmentService_SkuIdNotFound, you may need to update your code to check for NotFoundApplicationError instead.

• A new dependency supports parsing XML payloads:

  • group ID: com.fasterxml.jackson.dataformat
  • artifact ID: jackson-dataformat-xml

• The new GameInstance.DataStore createOrUpdate() method combines the functionality of the data store’s create(), updateData(), and updateSync() methods for more convenient access to data.

• The Presence cache in the Friend service has been changed to evict stale presence records. Use the new presenceCacheConfig value in the FriendServiceConfig to manage cache expiration values. The following example shows the default values:

  social:
      serviceConfigs:
          FriendServiceConfig:
              presenceCacheConfig:
                  maxTimeBetweenAccessMillis = 72000000
                  sizeBeforeExpirationEnforced = 50000
                  sweepIntervalMillis = 90000
  

Doc changes #

• [Xbox] New guide for implementing the Orders service. Please reach out to your customer support representative for more information.
• [Concept] Reorganized several accounts topics into a new Authentication section and added How-To guides and reference material.
• [Concept] Improved Player Data Overview topics now include a How-To Guide
• [Concept] Reorganized multiplayer topics including in-depth explanations and How-To guides
• [Tutorials] New Unity tutorials related to multiplayer services

SDK compatibility #

Patches #

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

0.5.1 #

Updated the XboxOrderProviderPlugin to properly track orders for revocation.

0.5.2 #

Fixed a bug where not all one time keys were loaded from the player data databases.

0.5.3 #

• Fixed a bug where players could be added multiple times to a Matchmaking Game Instance
• Restored the correct exported PragmaDev Postman collection

0.5.4 #

• Fixed a bug where the InviterInfo.displayName field was not populated in certain party client notifications.
• Fixed a bug where MatchmakingGameInstance would report incorrect values for secondsInQueue.