Pragma Engine 0.0.96 #

October 2023

Contents #

Summaries | Summarized release notes.

Full Notes | Full notes including descriptions and additional details.

Summaries #

Features #

• [Multiplayer] New Party Plugin protos and methods make it easier to control what party and party player data is broadcast to players. | full note
• [Multiplayer] You can now update data for an active game instance. | full note
• [Multiplayer] Added ability to define default game server versions and use wildcards in compatibility maps. | full note
• [Multiplayer] Player client and game server incompatibility does not disband parties. | full note
• [Player Data] Added new Inventory service endpoints for deleting player inventory and inventory cache that are expanded to all trusted gateways. | full note
• [Accounts] The identity providers Okta, Auth0, and Google Workspace have been added. | full note
• [Accounts] You can now configure all identity providers to control login, linking, and Portal display. | full note
• [Accounts] Identity provider type used to authenticate is now available on login token. | full note
• [Accounts] You can now unlink an identity provider from an account. | full note
• [Accounts] New endpoints for adding and removing accounts from groups. | full note
• [Infra & Tooling] New notifications for handling unintentional network disconnects. | full note
• [Portal] Operators can now permanently delete accounts in Portal. | full note
• [Portal] Operators can now update ext data of a player’s instance item. | full note

Deprecations #

• [Multiplayer] sdk | GameLoopApi SDK methods and events related to parties and party players have been renamed and require integration before upgrading to the next release (0.0.97). | full note

Integrations #

• [Multiplayer] platform | Update code interacting with the Party service to utilize the new interfaces.| full note
• [Multiplayer] platform, sdk | Implement the new buildExtBroadcastParty, buildExtBroadcastPlayer, and buildExtPrivatePlayer methods to populate and return the new Party and PartyPlayer protos. | full note
• [Multiplayer] sdk | Update references to multiplayer SDK methods and events. | full note
• [Multiplayer] platform | Rename Party Plugin returnFromMatch method to returnFromGameInstance. | full note
• [Multiplayer] config | Modify configuration file to account for removal of the Game Server Compatibility Plugin. | full note
• [Multiplayer] platform | Update references to the MatchmakingProtoTestFactory enterMatchmakingWithMatchV1Request function with enterMatchmakingWithGameInstanceV1Request. | full note
• [Player Data] config | Add new game node configurations for the Player Data Dao Node service to all game node’s shards. | full note
• [Accounts] config | Update usages of portalLoginEnabled to showPortalLoginButton. | full note
• [Accounts] config | Remove references to the canFederate config value. | full note
• [SDKs] sdk | If you’re using Unreal, rename RegisterService and GetService to RegisterApi and Api. | full note

Bugs and Fixes #

• Several Portal fixes and improvements including:
  • fixed Export Content button and source dropdown selection in the Portal Content Catalogs Editor
  • fixed authentication bug when using subdomains for multiple Portals
  • fixed display name of hovered items in Stores and Crafting tables
  • improved Portal navigation
  • improved readability of Account Info panel
  • improved Portal responsiveness for ultra-wide screens
• If a player rejoins a game instance, they will not be in both the active and removed player lists. Previously, if a player previously removed from a game instance was added back into the game instance, the removed player record was not properly updated.
• The EnterMatchmakingV1 endpoint now throws PartyService_InvalidSession instead of PartyService_PlayerAlreadyInGameLoop when any player in the party is already in matchmaking or in a game instance.
• Prevent memory access issues when a player has multiple pending party invites.
  • Unreal SDK GetInviteByInviteId (now GetPartyInviteByInviteId) and GetInviteByInviterId (now GetPartyInviteByInviterId) methods now return TOptional<FPragmaPartyInvite>, which can be checked for validity before using with the isSet() method. Previously, functions were returning raw pointers into a TArray, which can be dangerous if the PendingInvites array changes while those pointers are being handled.
• ViewSocialIdentityV1Request now returns a social identity for a user even if they do not have at least one game identity. A SQL query JOIN was changed to LEFT JOIN so that social records would be returned even when there are no game identities associated with it.
• The JWT token displayName field now reflects changes made to the display name made in the Account Plugin. Previously, updates made in onAccountLogin or onAccountCreated functions were not immediately reflected in the JWT token displayName field which the SDK uses for the player’s display name.
• Added the error type AccountService_IdProviderUnexpectedResponse to make it clearer when a login error is coming from a third party authentication service.
• Improved performance for the AccountRpc.GetPragmaPlayerIdsForProviderIdsV2 endpoint by updating the logic and SQL to scale more efficiently.
• Fixed a bug that prevented entitlements syncing for identity providers defined in ExtIdProvider enum. Previously, syncing entitlements with identity providers in ExtIdProvider did not work due to a bug in the conversion of identity provider integer value into identity provider name.
• The login buttons on the portal now show the correct icon for the identity providers.
• BackgroundManager::serialActor now logs unhandled exceptions without terminating the actor. Previously it would stop executing items from the channel, but now logs the exception and continues on to the next item.

Docs #

• [New Concepts] Added a new concepts page on Custom Identity Providers.
• [New Tutorials] Replaced the old Items tutorials with new tutorials for creating Stackable Items and custom Instanced Items along with their respective plugins.
• [Updated Concepts] Included content to explain how to Authenticate with RPC.
• [Updated Concepts] Updated the Identity Provider page to add in information about new supported identity providers and their configurations.
• [Updated Concepts] Added a new section on the Account Data page detailing how to delete an account in Portal.
• [Updated Concepts] Added a new section called Flow Overview on the Account Plugin page.
• [Updated Concepts] Updated Portal Key Concepts page with file location information and details on how to login into Portal with authenticated identity providers and.
• [Updated Concepts] Updated Game Portal page with more information about Rewards and Limited Grants.
• [New Updates Page] An Infrastructure Updates page has been added to the Release Notes section.
• [Updated Concepts] Updated Multiplayer section to make subsections consistent.

Full Notes #

Features #

[Multiplayer] New Party Plugin protos and methods make it easier to control what party and party player data is broadcast to players. #

Description: We reconfigured Party Plugin protos and added three Party Plugin build methods so developers can easily specify what Party and PartyPlayer data is broadcast to the player clients and what data is used exclusively by the platform.

Details: When a party is initialized (PartyPlugin.initializeParty), all party and player data on the ExtCreateRequest can be transferred to the new ExtParty and ExtPartyPlayer payloads, where it is hidden from player clients. When you want to broadcast data to the player client, you can specify what data goes out by adding the data to the ExtBroadcastParty, ExtBroadcastPlayer, and ExtPrivatePlayer payloads using the new build methods.

Related notes: See integration note on implementing the new Party build payloads.

[Multiplayer] You can now update data for an active game instance. #

Description: You can now use the new MatchApi.updateGameInstance SDK function and GameInstancePlugin.updateGameInstance method with the ExtUpdateGameInstanceRequest payload to trigger an update of the ext data within a game instance.

Details: The updateGameInstance SDK function will trigger the new Game Instance Plugin updateGameInstance method, which accepts the new ExtUpdateGameInstanceRequest payload, a custom payload defining what updates to perform to the game instance.

Related notes: See integration note on implementing the new ExtUpdateGameInstanceRequest payload.

[Multiplayer] Added ability to define default game server versions and use wildcards in compatibility maps. #

Description: You can now define a default gameServerVersion within the party configuration for any game clients that are not specifically mapped to a version in the gameServerCompatibility map. In addition, compatibility maps now support trailing wildcard characters (*), allowing many client versions to be represented with fewer entries in the compatibility map.

Details: We added the following configuration keys to the PartyConfig block in the Party configuration file: * enableGameServerVersionDefault: if true, use gameServerVersionDefault for clients not handled by the version compatibility map. * gameServerVersionDefault: default gameServerVersion to use for clients not handled by the version compatibility map. * gameServerVersionCompatability: map of server/client compatibility, migrated from the OrderedGameServerCompatabilityPlugin. Now supports trailing wildcard characters (*) in the client versions.

Related notes: See integration note on modifying the PartyConfig block of the configuration file.

[Multiplayer] Player client and game server incompatibility does not disband parties. #

Description: When a party’s membership status changes or its matchmaking state changes, Pragma Engine recalculates the gameServerVersion based on the gameServerCompatibility map. If unsupported player client versions are detected, party members are notified. Parties will no longer be disbanded if a compatible game server version cannot be found.

Details: If one or more player clients are not supported, a warning is logged. Any player that does not have a supported game server version will receive a OnGameClientVersionUpdateRequired notification, and all players in the party will receive a OnPartyClientVersionMismatch notification. If all players are on a supported version, but cannot match to a single game server version, all players will receive a OnPartyClientVersionMismatch notification.

[Player Data] Added new Inventory service endpoints for deleting player inventory and inventory cache that are expanded to all trusted gateways. #

Description: The Inventory service has now expanded three new RPCs for deleting player inventories and clearing inventory cache to all trusted gateways. All clear cache endpoints completely clear a player’s cache data in the inventory database, while delete endpoints will remove all player data including cache stored in the configured inventory database.

Details: We added following three Inventory service endpoints that are expanded to all trusted gateways:

• DeletePlayerInventoryOperatorV1Request
• DeletePlayerInventoryPartnerV1Request
• ClearPlayerInventoryCacheOperatorV1Request

Any time a player’s cached inventory data is cleared, an InventoryRpc.ResetClientInventoryCacheVersionV1Notification is sent to the game client to reset the cache on the client side. These endpoints are disabled by default and must be enabled through the InventoryServiceConfig:

InventoryServiceConfig:
    enableDeleteAllInventory: true | false
    enableDeletePlayerInventory: true | false

[Accounts] The identity providers Okta, Auth0, and Google Workspace have been added. #

Description: There are three new identity providers available to enable and configure within Pragma Engine: Okta, Auth0, and Google Workspace. For more details, see the Identity Providers concepts page.

Google Workspace has been added as an identity provider to support the difference between a public google authentication and an internal one.

[Accounts] You can now configure all identity providers to control login, linking, and Portal display. #

Description: Four new boolean config fields are available to control additional identity provider features. For more details, see the Identity Providers concepts page.

Details: The following are the new config fields available on all identity providers:

• playerLoginEnabled: Determines whether the identity provider is enabled for player login.
• operatorLoginEnabled: Determines whether the identity provider is enabled for operator login.
• accountLinkingEnabled: Determines whether the identity provider is enabled for account linking.
• showPortalLoginButton: Determines whether the identity provider is shown in the portal login options.

[Accounts] Identity provider type used to authenticate is now available on login token. #

Description: The Pragma Engine authentication token JWT now contains additional information on the identity provider that was used to authenticate.

Details: The JWT payload now provides the idProvider string that was used to log in. This can be accessed by decoding the generated JWT and looking at the idProvider key. The value is the string representation of the identity provider (UNSAFE, STEAM) used to authenticate that specific token. Partner tokens do not use the idProvider field so the value will be defaulted to UNUSED.

[Accounts] You can now unlink an identity provider from an account. #

Description: New endpoints have been added to allow service, partner, and operator requests to unlink an identity provider from an account. For more details, see the Identity Provider concepts page. Details: The following endpoints can be used to unlink an identity provider:

• AccountRpc.UnlinkIdentityProviderAccountPartnerV1Request
• AccountRpc.UnlinkIdentityProviderAccountServiceV1Request
• AccountRpc.UnlinkIdentityProviderAccountOperatorV1Request

[Accounts] New endpoints for adding and removing accounts from groups. #

Description: New endpoints were added to allow Partner and Service requests to add and remove accounts from groups. For more details, see the Player Groups concepts page.

The following RPCs can be used to add and remove accounts from groups:

• AccountRpc.AddAccountToPlayerGroupPartnerV1Request
• AccountRpc.AddAccountToPlayerGroupServiceV1Request
• AccountRpc.RemoveAccountFromPlayerGroupPartnerV1Request
• AccountRpc.RemoveAccountFromPlayerGroupServiceV1Request

Details: Below are the new SDK endpoints:

• Unreal
  • UPragmaAccountPartnerService::AddAccountToPlayerGroup
  • UPragmaAccountPartnerService::RemoveAccountFromPlayerGroup
• Unity
  • AccountService.AddAccountToPlayerGroup
  • AccountService.RemoveAccountFromPlayerGroup

[Infra & Tooling] New notifications for handling unintentional network disconnects. #

Description: Two new notifications have been added to improve the handling of unintentional network disconnects of our persistent WebSocket between client SDK and Game/Social gateways.

• SessionSoftDisconnectedV1Notification: When a player’s WebSocket unintentionally disconnects
• SessionSoftReconnectedV1Notification: When a client unintentionally disconnects and the SDK attempts a soft reconnect Details: To receive these notifications for custom services, implement these handlers and the logic necessary to reconcile and restore any state with the clients.

@PragmaNotification(routingMethod = NotificationRoutingMethod.ALL_DISTRIBUTED)
suspend fun onSessionSoftDisconnected(notification: SessionSoftDisconnectedV1Notification) {
// do the things here...
}
@PragmaNotification(routingMethod = NotificationRoutingMethod.ALL_DISTRIBUTED)
suspend fun onSessionSoftReconnected(notification: SessionSoftReconnectedV1Notification) {
// do the things here...
}

[Portal] Operators can now permanently delete accounts in Portal. #

Description: A new Delete Account section has been added. This section can be found at the bottom of the account details page. For more information on deleting an account, see the Account Deletion section in the docs.

[Portal] Operators can now update ext data of a player’s instance item. #

Description: From a player’s inventory page, click on an instanced item and a menu will open with details. Click Update Item and add server item update data. Note that server item updates or an update entry ID will also need to be sent to the server.

Deprecations #

[Multiplayer] sdk | GameLoopApi SDK methods and events related to parties and party players have been renamed and require integration before upgrading to the next release (0.0.97). #

Description: The following GameLoopApi SDK methods and events have been updated for clarity around parties and party members now that the client interface has been aggregated to a single interaction point (GameLoopApi). These methods and events have been deprecated in Pragma Engine version 0.0.96 and should be migrated before updating to version 0.0.97.

Integrations #

[Multiplayer] platform | Update code interacting with the Party service to utilize the new interfaces. #

Description: We’ve updated the Party service interfaces to improve developer experience, as well as to better align with the interface patterns of the Matchmaking service and Game Instance service. The new interfaces are published in the PartyInterfaces file within the game-common module.

Integration steps: platform | Within implementations of the Party Plugin:

• Update the file to import pragma.party.Party.

• Update all function parameters references as follows:

  Original	Replacement
  Party	Party.Party
  PartyPlayer	Party.PartyPlayer

• Update any code that references the changed interface variables:

  Party.Party

  Original	Replacement
  partyId	id
  partyMembersByPlayerId	players
  invitedByInviteId	Removed
  disableMaxPlayerCount	Removed. Use disableMaxPlayerCount value in PartyConfig.
  extPartySelections extHiddenPartyData	ExtParty. See renamed exts integration note

  Party.PartyPlayer

  Original	Replacement
  sessionKey	Removed. Player ID and social ID are now directly accessible on the partyPlayer.
  displayName	Now wrapped in data class PragmaDisplayName.
  leader	isLeader
  ready	isReady
  extPlayerSelections	extPrivatePlayerSelections
  extHiddenPlayerData	ExtPartyPlayer. See renamed exts integration note

[Multiplayer] platform, sdk | Implement the new buildExtBroadcastParty, buildExtBroadcastPlayer, and buildExtPrivatePlayer methods to populate and return the new Party and PartyPlayer protos. #

Description: When a party is initialized (PartyPlugin.initializeParty), all party and player data on the ExtCreateRequest can be transferred to the new ExtParty and ExtPartyPlayer payloads, where it is hidden from player clients. When you want to broadcast data to the player client, you can implement the buildExtBroadcastParty, buildExtBroadcastPlayer, and buildExtPrivatePlayer methods to specify what data ( contained in ExtBroadcastParty, ExtBroadcastPlayer, and ExtPrivatePlayer) is broadcast to the player client.

Integration steps:

• platform | Replace the following exts in your partyRpcExt.proto file, migrating any custom data to the new exts.

  Original	Replacement
  ExtPartySelections ExtHiddenPartyData	Migrate any custom party data that should be used by the platform to ExtParty. This is not broadcast to the player. Migrate any custom party data that should be broadcast to all player clients when the party is updated to ExtBroadcastParty ExtPlayerSelections
  ExtPrivatePlayerSelections ExtHiddenPlayerData	Migrate any custom player data that should be used by the platform to ExtPartyPlayer. This is not broadcast to the player. Migrate any custom player data that should be broadcast to all player clients when the party is updated to ExtBroadcastPlayer. Migrate any custom player data that should be broadcast to a specific player client when the party is updated to ExtPrivatePlayer.
  ExtUpdatePartySelectionsRequest	ExtUpdatePartyRequest
  ExtUpdatePlayerSelectionsRequest	ExtUpdatePartyPlayerRequest

• platform | Implement the following new Party Plugin build methods to populate and return the new exts:

    buildExtBroadcastParty(
     party: Party
    ): ExtBroadcastParty

   buildExtBroadcastPlayer(
    party: Party, 
    player: PartyPlayer
   ): ExtBroadcastPlayer

   buildExtPrivatePlayer(
    party: Party, 
    player: PartyPlayer
   ): ExtPrivatePlayer

• sdk | Update how you handle the following values returned from the GameLoopApi party and party player in the SDKs:

  SDK method	Return value
  Unreal: GameLoopApi->GetParty()->GetExt() Unity: GameLoopApi.Party.Ext	Returns ExtBroadcastParty instead of ExtPartySelections
  Unreal: GameLoopApi->GetParty()->GetExtPrivatePlayer() Unity: GameLoopApi.Party.ExtPrivatePlayer	Returns ExtPrivatePlayer instead of ExtPrivatePlayerSelections
  Unreal: GameLoopApi->GetLocalPartyPlayer()->GetExt() Unity: GameLoopApi.GetLocalPartyPlayer.Ext	Returns ExtBroadcastPlayer instead of ExtPlayerSelections

[Multiplayer] platform | Implement the new ExtUpdateGameInstanceRequest proto. #

Description: You can use the new ExtUpdateGameInstanceRequest payload with the MatchApi.updateGameInstance SDK function and GameInstancePlugin.updateGameInstance to trigger an update of the ext data within a game instance.

Integration step:

• platform | Navigate to the pragma-engine/platform/5-ext/ext-protos/src/main/protos/shared/gameInstanceExt.proto file and add a message for the new ExtUpdateGameInstanceRequest payload.

  Ext	Description
  message ExtUpdateGameInstanceRequest	Define what modifications to make to a game instance.

[Multiplayer] sdk | Update references to multiplayer SDK methods and events. #

Description: We’ve updated SDK terminology to be more consistent with recent platform changes and to decrease confusion. We renamed several methods and events and updated several event payloads to include relevant data without including the protobuf objects that drive the events.

Integration step: sdk | Update references to listed methods, and rename any of the listed events to which you are currently subscribed. If the event payload has changed, use the newly provided parameters instead of pulling them from the raw notification.

Unreal and Unity changes:

Unreal only changes

Unity only changes

[Multiplayer] platform | Rename Party Plugin returnFromMatch method to returnFromGameInstance. #

Description: We renamed the Party Plugin’s returnFromMatch method to returnFromGameInstance to represent support for more general game instances.

Integration step: platform | If you’ve implemented a custom Party Plugin, rename the returnFromMatch override method to returnFromGameInstance. The signature of the new function uses Party.Party and Party.PartyPlayer as explained in the integration note.

[Multiplayer] config | Modify configuration file to account for removal of the Game Server Compatibility Plugin. #

Description: We’ve removed the Game Server Compatibility Plugin. Game server versions are now defined in the Party configuration.

Integration steps: config

• Locate any configuration related to PartyService.gameServerCompatibilityPlugin.
• If your configured plugin is a custom Game Server Compatibility Plugin:
  • If your plugin produces a default string in certain use cases, migrate that string to the new serviceConfigs/PartyConfig gameServerVersionDefault configuration option.
  • Migrate any custom game server or game client validation logic into the Party Plugin.
  • To implement custom logic that determines which game server version a party will play on, set overrideGameServerVersion to true for the party within the Party Plugin. Once this field is set, the Party Plugin is expected to directly set the party’s gameServerVersion.
• If your configured plugin is the Ordered Game Server Compatibility Plugin:
  • Migrate the versionCompatibility section and any subsequently nested YML into serviceConfigs/PartyConfig.
  • Rename versionCompatibility to gameServerVersionCompatibility.
• If your configured plugin is the Default Game Server Compatibility Plugin:
  • Migrate the value of the gameServerVersion key to serviceConfigs/PartyConfig.
  • Rename gameServerVersion to gameServerVersionDefault.
  • Add the key enableGameServerVersionDefault with the value true.

Sample original configuration file serviceConfig section:

pluginConfigs:
   PartyService.gameServerCompatibilityPlugin:
   class: "pragma.party.OrderedGameServerCompatibilityPlugin"
     config:
        versionCompatibility:
        1:
        serverVersion: "gameServerVersion1"
        clientVersions:
             1: "gameClientVersion0"
             2: "gameClientVersion1"
        2:
        serverVersion: "gameServerVersion2"
        clientVersions:
            1: "gameClientVersion1"
            2: "gameClientVersion2"

Sample replacement configuration file serviceConfig section:

serviceConfigs:
   PartyConfig:
   enableGameServerVersionDefault: true
   gameServerVersionDefault: "gameServerVersionDefault"
   gameServerVersionCompatibility:
        1:
        serverVersion: "gameServerVersion1"
        clientVersions:
            1: "gameClientVersion0"
            2: "gameClientVersion1"
        2:
        serverVersion: "gameServerVersion2"
        clientVersions:
            1: "gameClientVersion1"
            2: "gameClientVersion2"

[Multiplayer] platform | Update references to the MatchmakingProtoTestFactory enterMatchmakingWithMatchV1Request function with enterMatchmakingWithGameInstanceV1Request. #

Description: We renamed the MatchmakingProtoTestFactory.enterMatchmakingWithMatchV1Request Test Factory helper function to correctly match the name of the object the helper is producing.

Integration step: platform | Find any usages of MatchmakingProtoTestFactory.enterMatchmakingWithMatchV1Request and rename those usages to MatchmakingProtoTestFactory.enterMatchmakingWithGameInstanceV1Request

[Player Data] config | Add new game node configurations for the Player Data Dao Node service to all game node’s shards. #

Description: This integration is required to enable an upcoming Player Data feature.

Integration step: config | Add the following configuration to all game node configurations as appropriate for the node’s shard:

serviceConfigs:
    PlayerDataDaoConfig:
        databaseConfig:
            identifierSchemas:
                1:
                identifier: "defaultIdentifier"
                schema: "<shard>_game_player_data1"

[Accounts] config | Update usages of portalLoginEnabled to showPortalLoginButton. #

Description: The portalLoginEnabled field has been renamed to showPortalLoginButton for clarity. The previous flag did not disable Portal login, but was used to disable the button on the login screen.

Integration step: config | Update usages of portalLoginEnabled with showPortalLoginButton:

[Accounts] config | Remove references to the canFederate config value. #

Description: The config field canFederate is no longer used. This functionality is now supported by the new config field accountLinkingEnabled.

Integration step: config | Update usages of canFederate with accountLinkingEnabled:

[SDKs] sdk | If you’re using Unreal, rename RegisterService and GetService to RegisterApi and Api. #

Description: These methods were deprecated in 0.0.94 and have been fully removed with this release. They have been renamed as part of renaming “Service” to “Api” within the SDKs.

Integration steps:

• sdk | Update all uses of the following method in Pragma::FRuntime, Pragma::FPlayer, and Pragma::FServer:

  Original	Replacement
  Session->RegisterService<UMyService>()	Session->RegisterApi<UMyService>()

• sdk | Update all uses of the following method in Pragma::FPlayer and Pragma::FServer:

  Original	Replacement
  Session->GetService<UMyService>()	Session->Api<UMyService>()