November 8th, 2022

Features #

You can now force your inventory cache to update in the SDKs. #

Description: If your inventory is stale, you can force the cache to update with ForceGetInventory.

PragmaSession->InventoryService->ForceGetInventory(FOnCompleteInventoryCacheCallDelegate::CreateLambda([this](FInventoryFull Full) {
 // use the Full.LastRefreshSuccess to assess that the cache sas successfully refreshed.
 // The inventory is within Full.Stackable and Full.Instanced
});

PragmaSession.InventoryService.ForceGetInventory(r =>{
 // use the r.Payload.lastRefreshSuccess to assess that the cache was successfully refreshed.
 // The inventory is within r.Payload.instancedItems and r.Payload.stackableItems
});

Players that create a party while in an active party will automatically leave and move to the new party. #

Description: If a player tries to create a new party while in an active party, they will automatically leave the party they already were in and join the newly created one. This means a player can create a new party at any time. To check if a player is in a party, you can use the HasParty() helper method in the Party service.

New version properties have been added to /v1/info for different artifacts. #

Description: We’ve added version properties to /v1/info for each artifact type (platformVersion, portalVersion, contentVersion, and configVersion).

Related note: See Integrations note about /v1/info.

Purchasing and entitlement catalogs are now retrieved by GetLoginData. #

Description: GetLoginData now includes the catalogs for ItemBundles and ProviderEntitlementMappings. Hidden item filtering is also supported for ItemBundles.

You can now call GetLoginData through the SDK Rich GameDataService. #

Description: GameDataService in the SDKs now propagates the GetLoginDataV2Response. The client-side inventory cache of the Rich InventoryService will be updated through a new event called OnGetLoginData. We strongly recommend you use this new feature.

To use this new endpoint, replace any uses of GameDataServiceRaw’s GetLoginData with the new call:

UPragmaGameDataService::GetLoginData()

GameDataService.GetLoginData()

SDK Raw Partner RPCs have been added to the Inventory service. #

Description: The following Raw Partner RPCs have been added to the Inventory service.

Added an SDK event that notifies players to update their game client if it doesn’t match the configured GameServerVersions. #

Description: The new SDK event OnGameClientVersionUpdateRequired notifies players if their client version does not match the currently configured GameServerVersions.

Related note: See integration note about game client update notifications.

Unreal SDK: Messages can now be excluded from SDK code generation. #

Description: A new option has been added to support hiding certain messages from the Unreal code generation phase of the processing of proto files. This means you can hide messages that aren’t relevant to players or game servers–for example, in a situation where your custom services uses a custom Partner request internally.

Add the following line within the body of any message to prevent the message from being provided to the protoc compiler used in the code generation phase:

option (external_visibility) = HIDE;

Example: In paymentRpc.proto, there are some internal Partner requests and responses that the engine uses. By using this new feature, we prevent exporting this information because game servers can’t use it:

message InitializeOrderPartnerV1Response {
  option (pragma_session_type) = PARTNER;
  option (pragma_message_type) = RESPONSE;
  option (external_visibility) = HIDE;
}

Unreal SDK: You can now use the PreDisconnect event to make sure cleanup happens inline with disconnection. #

Description: We’ve added a PreDisconnect event to the Unreal SDK to make sure handlers are fired before UPragmaConnection::OnDisconnectedV2. You can use this to make sure cleanup happens inline with disconnection.

Portal: You can now edit content catalogs in Portal. #

Description: A new portlet called Content Catalogs Editor has been added to allow Operators to create, update, and delete content entries. Changes can be previewed on the Content Changes page before they’re applied. You can also import and export source files for tasks like moving content between game servers or making a backup before altering data.

This portlet is disabled by default to prevent use in production. Changes can be applied directly in the environment where the Portal is running, or exported in a zip file.

Deprecations #

If you’re using the version properties endpoint in /v1/info, you’ll need to update it to platformVersion. #

Description: We’re adding version properties to /v1/info for each artifact type (platformVersion, portalVersion, contentVersion, and configVersion). You’ll need to use platformVersion instead of version.

Related note: See feature note about /v1/info.

Unreal SDK: Some Inventory service calls have been renamed for clarity. See included table for details. #

Description: We’ve renamed/removed several Inventory service calls for clarity.

• UPragmaInventoryService::GetInstancedItemsV1 and UPragmaInventoryService::GetStackableItemsV1 will be removed. Use UPragmaInventoryService::GetInventory and you can see the instanced and stackable items within the response of this call.
• UPragmaInventoryService::GetInventoryV1 will be replaced with UPragmaInventoryService::GetInventory.
• UPragmaInventoryService::DeletePlayerInventoryV2 will be replaced with UPragmaInventoryService::DeletePlayerInventory.

Integrations #

To update Pragma Engine’s build tools, install or update your Corretto JDK to JDK 17. #

Description: The tools used to build Pragma Engine have been updated and require the newer Corretto JDK 17 version.

Integration steps: Follow steps in the provided doc on Dev Environment Changes to get your JDK running with Pragma Engine. If you’re having trouble with a new make build, try clearing your .m2 Maven cache to start with a clean build.

Consolidate development defaults in a single location (./platform/config/dev-defaults.yml) by following the listed integration steps. #

Description: Pragma Engine no longer supports embedding development defaults within the engine codebase. Dev defaults should be specified within config files as appropriate:

• ./platform/config/dev-defaults.yml: Pragma Engine-supplied defaults for development and useful for getting started. This is an engine file and therefore should not be modified by studios.
• ./platform/5-ext/config/dev.yml: studio-supplied dev config values. These config values will override the Pragma Engine-provided defaults, and is a checked-in file to share across a dev team.
• ./platform/5-ext/config/common.yml: studio-supplied configuration used for config values appropriate in all contexts, including production and development.
• ./platform/5-ext/config/local-dev.yml: local machine overrides (i.e. debug logging for local box). This file is not checked in and can be used to configure settings unique to a local dev machine (such as a local Unreal engine install directory).

Integration step:

1. Complete the following renames in pragma-engine/platform/5-ext/config/. Note that if you’ve already tried a build, you may need to replace or remove the common.yml and local-dev files that were copied from our templates.

   original	replacement
   CommonConfig.yml	common.yml
   LocalConfig.yml	local-dev.yml

2. Update anything that extends a ConfigObject, such as ServiceConfig or PluginConfig objects.

• Remove the mode parameter from both constructors and the call to the superclass constructor.
• Remove the mode parameter from the ConfigBackendModeFactory.getFor method.
• Move any default config values specified within the DEVELOPMENT mode into the new ./platform/5-ext/config/dev.yml file, which will simplify default configuration by keeping it in one place near the rest of your config.
• Dao configurations: The shared username and password config must be placed within the file for all Daos even when not specific within the code individually.

3. If you have unit tests that connect to the database (not ITs), replace any config creation to match the following example:

val config = InventoryDaoConfig.getFor(BackendMode.DEVELOPMENT, BackendType.GAME).apply {
this.databaseConfig.hostPortSchemas = configMapOfPrimitiveOf(
"1" to "localhost:3306/test_local_game_inventory1",
"2" to "localhost:3306/test_local_game_inventory2",)}

val config = InventoryDaoConfig.getFor(BackendType.GAME).apply {
this.databaseConfig.addCredentials("localhost:3306/test_local_game_inventory1", "localhost:3306/test_local_game_inventory2")

4. Update shard .env files to export the correct ENV_CONFIG paths to match the following example:

5. Update run configs in IntelliJ by doing the following commands:

rm 5-ext/.run/LocalConfigured.run.xml
make ext

Once this is complete, in IntelliJ navigate to File -> Reload all From Disk. Note that you may still need to adjust the working directory in the Edit Configurations dialog box, depending on how you’ve loaded the 5-ext project.

6. Update any customized run configs. For any custom run configurations used in IntelliJ, you’ll need to update the --configuration-filepaths to include the additional and renamed configs. For example:

--configuration-filepaths "config/dev-defaults.yml,5-ext/config/dev.yml,5-ext/config/common.yml,5-ext/config/local-dev.yml"

Example:

• Original

class ArbiterLeaderboardDaoConfig private constructor(
    mode: BackendMode, type: BackendType
) : ServiceConfig<ArbiterLeaderboardDaoConfig>(mode, type) {
    override val description =
        "Configuration for the LeaderboardDaoConfig"

    var databaseConfig by types.embeddedObject(
        UnpartitionedDatabaseConfig::class,
        "database config for the leaderboard dao"
    )

    companion object :
        ConfigBackendModeFactory<ArbiterLeaderboardDaoConfig> {
        override fun getFor(
            mode: BackendMode, type: BackendType
        ) = when (mode) {
            BackendMode.DEVELOPMENT -> ArbiterLeaderboardDaoConfig(
                mode, type
            ).apply {
                databaseConfig =
                    UnpartitionedDatabaseConfig.getFor(
                        mode, type
                    ).apply {
                        hostPortSchema =
                            "localhost:3306/local_game_leaderboard"
                    }
            }

            BackendMode.PRODUCTION -> ArbiterLeaderboardDaoConfig(
                mode, type
            ).apply {
                databaseConfig =
                    UnpartitionedDatabaseConfig.getFor(
                        mode, type
                    )
            }
        }
    }
}

• Replacement

class ArbiterLeaderboardDaoConfig private constructor(
    type: BackendType
) : ServiceConfig<ArbiterLeaderboardDaoConfig>(type) {
    override val description =
        "Configuration for the LeaderboardDaoConfig"

    var databaseConfig by types.embeddedObject(
        UnpartitionedDatabaseConfig::class,
        "database config for the leaderboard dao"
    )

    companion object :
        ConfigBackendModeFactory<ArbiterLeaderboardDaoConfig> {
        override fun getFor(type: BackendType) =
            ArbiterLeaderboardDaoConfig(type).apply {
                databaseConfig =
                    UnpartitionedDatabaseConfig.getFor(type)
            }
    }
}

• dev.yml entry

game:
 core:
 serviceConfigs:
    ArbiterLeaderboardDaoConfig:
      databaseConfig:
        username: "superuser"
        password: "password"
        hostPortSchema: "localhost:3306/local_game_leaderboard"
 pluginConfigs:
social:
  core:
  serviceConfigs:
  pluginConfigs:

Related note: See Docs note on the config renames.

Generate new Partner tokens (both Social and Game) to include gameShardIds. #

Description: We’ve made this organizational change so that Partner Game tokens can only be used to communicate with their assigned game shard. You can check for token validation errors using the following config:

game:
  core:
    logging:
      loggers:
        pragma.auth.PragmaTokenValidator: "DEBUG"

Integration step: Generate new Partner tokens (both Social and Game) to include gameShardIds for each platform instance you have. Visit the Authentication docs page to learn how to generate Partner tokens.

[/Script/PragmaSDK.PragmaSdkConfig]
...
PartnerSessionSocialAuthToken="<your-social-token-here>"
PartnerSessionGameAuthToken="<your-game-token-here>"
...

{
...
"partnerSessionGameAuthToken": "<your-game-token-here>",
"partnerSessionSocialAuthToken":"<your-social-token-here>"
  ...
}

Delete remaining Lobby service files. #

Description: As a cleanup step for the removal of the Lobby service, you’ll need to delete some remaining files. The Lobby service and associated protobuf files have been deleted, so the ext file corresponding to those protos should be deleted.

Integration step: If they exist, delete the files lobbyExt.proto and lobbyRpcExt.proto in platform\5-ext\ext-protos\src\main\proto\shared\.

Update your configs for identity providers to reflect the new structural changes. #

Description: We’ve moved the plugins for identity providers to a new plugin collection named AccountService.identityProviderPlugins.

Integration step: Update your config for identity providers to reflect the new structural changes.

Example: For a Discord identity provider, update your YAML files to make sure you’re using the new structure.

social:
pluginConfigs:
  AccountService.discordIdentityProvider:
    class: "pragma.account.DiscordIdentityProviderPlugin"
    config:
      clientId: "$discordClientId"
      clientSecret: "$discordClientSecret"
      redirectUri: "http://localhost:11000/v1/account/discord-redirect"

social:
pluginConfigs:
  AccountService.identityProviderPlugins:
    plugins:
      Discord:  <--- a unique key per Plugin
        class: "pragma.account.DiscordIdentityProviderPlugin"
        config:
          clientId: "$discordClientId"
          clientSecret: "$discordClientSecret"
          redirectUri: "http://localhost:11000/v1/account/discord-redirect"

Replace usages of the LinkIdentityProviderAccountV1 endpoint with the renamed versions. #

Description: We’ve renamed this endpoint to be consistent with Service endpoint naming conventions.

Integration step: Replace usages of the LinkIdentityProviderAccountV1 endpoint with the renamed versions.

Update any config files that use the Epic or Steam identity providers to reference their new class names. #

Description: We’ve renamed these class names to be consistent with plugin naming conventions.

Integration step: Update any config files that use the Epic or Steam ID Providers to reference their new class names.

Replace usages of InventoryRpc.DeletePlayerInventoryV2() with InventoryRpc.DeletePlayerInventoryV3(). #

Description: To complete the deprecation listed in release 0.0.87, we’ve removed this endpoint.

Integration step: Replace usages of InventoryRpc.DeletePlayerInventoryV2() with InventoryRpc.DeletePlayerInventoryV3(). We recommend using the rich layer in the SDK so inventory caches are updated accordingly.

Postman: To update your localhost environment, use the renamed file Localhost.pragma_environment.json. #

Description: To be consistent with the Postman UI, we’ve renamed the LocalNode1.pragma_environment.json file to Localhost.pragma_environment.json.

Integration step: To update your localhost environment, use the renamed file Localhost.pragma_environment.json.

If you’re using the test helper method matchCapacity_partyStartMatchV1Request, replace it with matchCapacity_startMatchV1Request. #

Description: With the removal of the Lobby service, we’re simplifying and deduplicating names.

Integration step: Rename the listed test helper method. Note that the arguments and return value are the same.

If you have custom implementations of the MatchmakingStrategy interface, remove the functions validateParty and addPartyToMatchAndBuildMatchmakingDetails. #

Description: As part of the Lobby service cleanup, we’ve removed two methods.

Integration step: If you have custom implementations of the MatchmakingStrategy interface, remove the functions validateParty and addPartyToMatchAndBuildMatchmakingDetails.

If you’re referencing SDK error enums by int (instead of by name) update the int values. #

Description: We’ve simplified SDK error enums as part of the Lobby service removal effort. The following errors have been removed from the Unreal (EPragma_SdkError) and Unity (public enum SdkError) SDKs, which means that error ints have changed and references to them will need to be updated to the correct ints.

• LobbyService_NotEnabled
• LobbyService_MatchAlreadyFound
• LobbyService_NoPlayAgainId

Integration step: If you’re referencing SDK error enums by int (instead of by name) update the int values.

For any custom services using InstancedConcurrentMap, update your code to handle the new internal exception correctly when getting keys from the map. #

Description: Referencing routing keys from the wrong instance will now throw an internal exception. This affects custom services using InstancedConcurrentMap.

Integration step: For any custom services using InstancedConcurrentMap, you’ll need to update your code. Note that requesting items from an InstancedConcurrentMap with keys not appropriate to the current Pragma node instance will result in an exception.

To use the new game client update notification feature, implement the game client update check on any GameServerCompatibilityPlugin. #

Description: When a party is shut down due to invalid GameServerVersions, party members who need to update their game clients should be notified.

Integration step: To use the new game client update notification feature, implement the update check on any GameServerCompatibilityPlugin:

Related note: See Features note about OnGameClientVersionUpdateRequired.

Bugs and Fixes #

• Fixed an error where players that were kicked via the KickV1 RPC were unable to join another party due to their session containing their original PARTY_ID. Players can now join another party after being kicked, while still being unable to join their original party.

• Fixed a server bug that prevented players from receiving a SessionChangedV1Notification when rejoining a match. After rejoining their original match, players will now correctly receive a SessionChangedV1Notification containing their match’s MATCH_ID.

• Fixed several bugs caused by declining party invites. These bugs included Pragma SDK clearing party states, not providing valid party data, and not allowing valid Pragma SDK actions from being performed. These bugs are fixed for both Unity and Unreal Pragma SDKS.

• Unreal SDK: Fixed an assertion error with the Unreal SDK when multiple login and disconnects occurred in a row.

• Portal: Fixed the item details tab opening by itself in a player’s inventory when switching between the Stackable and Instanced tabs.

• Portal: Fixed an error that prevented removing items from a player’s inventory.

• Portal: Fixed a bug that required users to press Enter or Return when creating a new tag to an account. You can now click the Apply button directly to create new tags for an account.

• Portal: Fixed a bug that caused a 404 page to show for 1 second after signing in to Portal with Google.

Docs #

• [Docs Rename] Services has been renamed to Concepts, and User Guides has been renamed to Tutorials. Old links to Services and User Guides have been redirected, so bookmarks to existing pages will not need to be updated.

• [Docs Rename] All uses of config files have been updated to reflect the config changes made this release. See related integration note on the config file changes.

• [Updated Concepts Guide] The Analytics Concepts section has been renamed to Telemetry. The Metrics page in the original Analytics section has been removed.

• [New Concepts Section] Added a new Concepts section called Operability with three new pages: an Overview page, the Metrics page that was previously in the Analytics section, and the Logging page from the README.

• [Updated Concepts Guide] Added a warning about account linking on the Cross-Platform Accounts page in the Accounts section.

• [Updated SDK Guide] Fixed the Unreal SDK Setup Guide Logging Into the Platform page by including a required step on calling InitSession() before using the session, and adding additional clarifying edits.

• [Updated Concepts Guide] Fixed the Identity Providers page in Accounts with updated code blocks on identity provider configuration.

October 11th, 2022

Features #

Parties now remain active when a party leader leaves. #

Description: Parties are no longer disbanded when a leader leaves the party or is disconnected from Pragma Engine. When a leader leaves a party, one of the remaining party members is granted party leadership.

Related note: See integration note about party disbandment.

Game clients can now retrieve match connection details using the new matchConnectionDetailsV1 endpoint. #

Description: Clients can now access connection details ad-hoc for an existing match by calling MatchLifecycleService.matchConnectionDetailsV1. This returns connection details using the MatchDetails object, which is also used by MatchReconnectV1Notification.

Details: The SDKs have been updated with the following methods on the Party service:

void UPragmaPartyService::MatchConnectionDetailsV1(const FMatchConnectionDetailsDelegate& OnComplete)
TFuture<TPragmaResult<FPragma_MatchLifecycle_MatchDetails>> UPragmaPartyService::MatchConnectionDetailsV1()
bool UPragmaPartyService::CanGetMatchConnectionDetailsV1() const
bool UPragmaPartyService::CanGetMatchConnectionDetailsV1(FPragmaError& OutError) const

public void MatchConnectionDetailsV1(MatchConnectionDetailsDelegate onComplete)
public Future<MatchDetails> MatchConnectionDetailsV1()
public bool CanGetMatchConnectionDetailsV1()
public bool CanGetMatchConnectionDetailsV1(out Error? error)

New player session endpoint for linking additional accounts. #

Description: Logged-in players can now link a new, additional account by passing a provider ID and a provider token to the new linkIdentityProviderAccountV2 endpoint.

Deprecations #

Use linkIdentityProviderAccountServiceV1 instead of linkIdentityProviderAccountV1. #

Description: linkIdentityProviderAccountV1 is being renamed to conform to our current naming conventions. Replace all uses of it with linkIdentityProviderAccountServiceV1.

Partner Game Tokens will now require a gameShardId. #

Description: In Pragma Engine 0.0.88, Partner Game Tokens will only be able to communicate with the specific game shard they are assigned to instead of all game shards belonging to a game title. Upon updating to Pragma Engine 0.0.88, regenerate your Partner Game Tokens for each of your game shards. You can do so via the Game Operator Portal (recommended) or by using the pragma-engine CLI.

• Game Operator Portal instructions:
  • Log into the Game Portal and navigate to the Game Server Management page.
  • Select a game shard from the dropdown, then create tokens. This creates both Social and Game partner tokens, but only the game tokens need to be updated. Updating the social tokens is optional.
• pragma-engine CLI instructions:
  • Build the latest jar via make build
  • To generate new tokens, run

  java -jar ./pragma-engine.jar crypto remoteServiceToken --type game --game-shard-id "{{gameShardId}}" --expiration-hours 876000 --key-base64 "{{base64EncodedJwtPrivateKey}}"
  

  • Replace {{gameShardId}} and {{base64EncodedJwtPrivateKey}} with the appropriate values.

Update usages of DeletePlayerInventoryV2 to DeletePlayerInventoryV3. #

Description: The RPCs for deleting player inventories now additionally remove all fulfillments. Update any usages of DeletePlayerInventoryV2 to DeletePlayerInventoryV3 by release 0.0.88.

Integrations #

Remove references to the expirationDays config value. #

Description: The TokenSignerConfig value expirationDays has been removed, and should be taken out of any config files.

Integration step: Find and remove any references to expirationDays in config files.

Use GameDataRPC.GetLoginDataV2 instead of GameDataRPC.GetLoginDataV1. #

Description: GameDataRPC.GetLoginDataV1 has been removed. GetLoginDataV2 brings necessary cleanup along with naming that more correctly aligns with inventory’s limited grant tracking IDs as a part of the LoginData payload. Note that this change only applies to GameDataRPC.GetLoginData, as InventoryRpc.GetLoginData has not been updated and should remain at V1.

Integration step: Update all usages of GameDataRpc.GetLoginDataV1 to GameDataRpc.GetLoginDataV2.

Update the config sections for TokenValidatorNodeService to the TokenDecoderNodeService. #

Description: The TokenValidatorNodeService has been renamed to the TokenDecoderNodeService, due to the service no longer performing token validation and only performing token decoding. If you’ve used the TokenValidatorNodeService directly in your code, update any references to the new TokenDecoderNodeService. Note that the service’s Test Factory tokenValidatorConfig was also renamed to tokenDecoderConfig.

Integration step: Update the config sections for TokenValidatorNodeService to the TokenDecoderNodeService.

game:
serviceConfigs:
  TokenValidatorConfig:
    jwtPublicKey: <some-public-key>
...
social:
serviceConfigs:
  TokenValidatorConfig:
    jwtPublicKey: <some-public-key>

game:
serviceConfigs:
  TokenDecoderConfig:
    jwtPublicKey: <some-public-key>
...
social:
serviceConfigs:
  TokenDecoderConfig:
    jwtPublicKey: <some-public-key>

If your game implementation relies on party disbandment upon a party leader leaving, manually replicate the behavior using the onRemovePlayer plugin to retain functionality. #

Description: With the new feature that keeps parties active when a party leader leaves, existing game logic may need to be refactored to account for the new expected behavior.

Integration step: If your game implementation relies on a party disbanding when a leader leaves the party, you can retain the existing flow by manually simulating this behavior using the onRemovePlayer plugin.

Related note: See feature note about party disbandment.

If you’re using the listed Test Factory helpers in the AccountTestFactory, replace them with the provided helpers. #

Description: We’ve removed/renamed several Test Factory helpers to eliminate duplication.

Integration steps: Replace the following helpers in AccountTestFactory with their updated versions:

Bugs and Fixes #

• Improved match reconnect reliability in the case where players disconnect and reconnect to the same match multiple times.

• Invalid or improperly-used tokens now report DEBUG server logs. Examples are tokens missing Authorization headers, corrupted tokens, or tokens being used for the wrong session or backend type.

Docs #

• [Moved SDK Guides] The SDKs & Tools guides have been moved to the new Setup Guides section in Introduction.

• [Updated Concepts Guide] Added section on Player Login Using Existing Sessions on the Login and Session page in Accounts.

• [Updated Concepts Guide] Added section on Connection Details to the Game Server Management page in Game Flow.

September 27th, 2022

Pragma Engine is moving to a six week release cadence. Version 0.0.88 is scheduled to be released on November 8th.

Features #

You can now authenticate to the social backend without a gameShardId. #

Description: The social backend sign-on is no longer tied to having a valid game. This means if there are no game shards configured, such as when starting a platform in PRODUCTION mode, an operator can still log into the platform.

Deprecations #

Use GameDataRPC.GetLoginDataV2 instead of GameDataRPC.GetLoginDataV1. #

Description: GameDataRPC.GetLoginDataV1 is being deprecated due to changes to InventoryRPC.GetLoginDataV1. GetLoginDataV2 brings necessary cleanup along with naming that more correctly aligns with inventory’s limited grant tracking ids as a part of the LoginData payload.

Unity:

Unreal:

Direct calls to RPC endpoints:

Use LoginDataPlugin.getLoginDataJobsV2 instead of LoginDataPlugin.getLoginDataJobs if you are not using DefaultPragmaLoginDataPlugin. #

Description: The dependent job structure on jobs coming from the LoginDataPlugin now uses a data class instead of a proto builder for better futureproofing. You will need to implement LoginDataPlugin.getLoginDataJobsV2 in custom implementations of LoginDataPlugin.

Integrations #

If you’re using the Limited Grants feature, you’ll need to drop all inventory databases, update your stackable specs to remove stackable trackables, and update any custom service implementations that refer to the list of issued limited grant IDs. #

Description: We recently removed the requirement for a stackable item tracker from the limited grants feature. If you’re using the Limited Grants feature, you will need to complete the listed integration steps.

Integration steps:

• Drop all inventory databases for all environments. This is required to avoid duplicating limited grant fulfillment, and it will clear out all stackable trackables.
  • You can see your configs for the host port schemas for a complete list of databases to drop. The default config schema is: “local_game_inventory1”.
• Update content and run the contentdata apply command.
  • Delete content/package/LimitedGrants.json.
  • Update content/src/LimitedGrants.json:
    • Replace trackingCatalogId with trackingId.
  • Remove all stackable specs for limited grant tracking in content/src/StackableSpecs.json.
  • Run the contentdata apply command.
• If a custom service uses the issuedLimitedGrantCatalogIds field in the GetLoginData call, it will need to be updated to issuedLimitedGrantTrackingIds.

Clients must stop calling matchReconnectV1. Clients should instead listen for the MatchReconnectV1Notification that is automatically sent after login. #

Description: matchReconnectV1 is now a service-only endpoint that automatically triggers on login. A notification with reconnection information will automatically be sent to the client shortly after login.

Integration step: In reconnect scenarios, clients should now listen for the MatchReconnectV1Notification. Remove any calls to matchReconnectV1 from your clients.

If you have game shards in production mode, add a shardId to both game and social core configs. #

Description: We’ve added a shardId into the core config to support game shards. It has been removed from the InventoryServiceConfig to avoid duplication.

Integration step: If you have game shards in production mode, you will need to add both game and social shardIds to the core config YAML file.

• You can find the game shardId by visiting the Game Title Management page on the social Portal webpage.

  The social shardId isn’t used yet, so its value can be any valid UUID.

  Default configuration should look like this:

  game:
    core:
      shardId: "00000000-0000-0000-0000-000000000001"
  

  social:
    core:
      shardId: "00000000-0000-0000-0000-000000000001"
  

Update usages of getDisplayNameForPragmaPlayerIdV1 or getDisplayNameForPlayerIdPartnerV2 to include the new required gameShardId parameter. #

Description: To support a multigame (and therefore multishard) setup for Pragma Engine, we’ve added a requirement for the gameShardId parameter on the getDisplayNameForPragmaPlayerIdV1 and getDisplayNameForPlayerIdPartnerV2 requests.

Integration step: Update usages of getDisplayNameForPragmaPlayerIdV1 or getDisplayNameForPlayerIdPartnerV2 from an SDK or any direct RPC call to include gameShardId on the request. You can access the gameShardId by calling a game shard’s <backendAddress>/v1/info endpoint.

Define columnNameOfPropertyToConsistentHash on all custom instances of PartitionDatabaseConfig. #

Description: The columnNameOfPropertyToConsistentHash field previously defaulted to an empty string. However, this field must now be defined in order to successfully start Pragma Engine.

Integration step: Define columnNameOfPropertyToConsistentHash for all your custom PartitionDatabaseConfigs by providing the database column name used to compute the consistent hash to store data for a player into the proper partition.

See `platform/2-pragma/game/src/main/kotlin/pragma/inventory/InventoryDaoConfig.kt` for an example.

Ensure that you call onConfigChanged() on DaoNodeServices prior to calling run(). #

Description: Previously, you could call run() on DaoNodeServices without calling onConfigChanged(). However, this is no longer the case. You must call onConfigChanged() before run() in order for the service to start.

Integration step: Ensure onConfigChanged() is called before run() on DaoNodeServices.

If you’re using getHostPortMap on AbstractDaoNodeService, switch to hostPortSchemas in DatabaseConfig. #

Description: Moving this functionality has allowed us to do some cleanup and remove unnecessary code. Any use of DbCleaner will need to be updated by removing the second argument.

If you are running multiple game shards in development mode, you will need to manually repopulate the game title and game shard data. #

Description: The local database was improperly named local_game_game and has been renamed to local_social_game as it is a social service.

If you are affected by this change, you will have to repopulate the following data:

• Game Titles & Game Shards
• Limited Access Events & Access Groups

Integration step: You can either manually repopulate your data or you can copy data over from the now-unused local_game_game database, as this change does not delete that database.

Update references to the GameShardId so that it’s pulled from the new location on the Connection object. #

Description: The Unreal and Unity SDKs have moved the GameShardId out of the SDKConfig and onto the Connection object.

Integration step:

• Update references to the GameShardId so that it’s pulled from the new location on the Connection object.
  • Unreal: Connection()->GetGameShardId()
  • Unity: Connection.GameShardId

Bugs and Fixes #

• Unreal SDK: Fixed a bug where HTTP RPCs that failed for HTTP reasons would never call their OnComplete callback.

• Unreal SDK: Fixed a bug where game servers would crash when receiving a MatchEnd response if the new MatchLifecycleService.MatchReady and MatchEnd functions are used.

Docs #

• [Updated User Guide] Removed stackable trackables from Limited Grants User Guide.

• [Updated SDK Guides] Added details for completing Discord Role-based authentication to Unreal and Unity Guides.

• [New Tech Blog Video] Purchasing Stackable Items in a Store video is now live and embedded in its corresponding tech blog article. It is also available via YouTube and the Pragma Blog.

September 20th, 2022

Features #

Added support for Playstation authentication.

• Description: You can now log in to Pragma Engine with Playstation by using a Pragma-provided plugin. Please reach out to us for integration support.

Added PlanContentChangesOperatorV1 endpoint which returns lists of content catalog source file changes that haven’t been applied.

• Description: The new endpoint PlanContentChangesOperatorV1 shows changes made to content catalog source files before they’ve been applied. It returns a list of new content, a list of changed content, and a list of removed content.

"contentChanges": {
 "newContentData": [ ],
 "changedContentData": [ ],
 "removedContentData": [ ]
}

Portal: Content catalogs now display data from content source files and the source file location.

• Description: Data from source files are now displayed in content catalogs, along with the name of the source file.

Bugs and Fixes #

Fixed protobuf generation issue that would fail with long file paths on Windows.

Fixed OnMatchFailed and OnMatchmakingFailed SDK events improperly clearing cached party data.

Docs #

[Updated SDK Guide] Added section on client-side authentication with Android to Unity Logging Into the Platform page.

[Updated Services Guide] Added section on game server selection based on player ping to the Matchmaking page.

[Updated Services Guide] Updated the description on the Game Flow Overview page.

[Updated Services Guide] Added section on secret encryption to the Configuration page in Customization.

[Updated Services Guide] Updated the Items page for clarity and accuracy.

September 13th, 2022

Features #

Twitch authentication now available.

• Description: You can now use TwitchIdentityProviderPlugin to configure Twitch login with Pragma Engine.

Added endpoint that returns a map of grouped content data for any given content type.

• Description: Added new getContentSourceOperatorV1 endpoint in Inventory service that returns content data grouped by source file for a given content type.

Party leaders can now assign a new leader or add additional leaders.

• Description: A party leader can assign another player to be party leader by calling assignPartyLeaderV1 with the PragmaId of the player to assign.

  When PartyConfig enableTransferPartyLeader is true, the player that calls assignPartyLeaderV1 will lose leader privileges (default behavior). If enableTransferPartyLeader is set to false, the assignPartyLeaderV1 call will result in multiple leaders in the party.

• Unity SDK:

  public void AssignPartyLeaderV1(PragmaId playerId, CompleteDelegate onComplete)
  
  public Future AssignPartyLeaderV1(PragmaId playerId)
  

  • Helper to get the list of all leaders: IReadOnlyList<IPartyPlayer> GetAllLeaders()

• Unreal SDK:

  void UPragmaPartyService::AssignPartyLeaderV1(const FString& PlayerId, const FOnCompleteDelegate& OnComplete)
  
  TFuture<TPragmaResult<>> UPragmaPartyService::AssignPartyLeaderV1(const FString& PlayerId)
  

  • Helper to get the list of all leaders: TArray<UPragmaPartyPlayer*> UPragmaParty::GetAllLeaders() const

Deprecations #

If you’re using getHostPortMap on AbstractDaoNodeService, switch to hostPortSchemas in DatabaseConfig.

• Description: Moving this functionality has allowed us to do some cleanup and remove unnecessary code. Any use of DbCleaner will need to be updated by removing the second argument.

Integrations #

If you currently have sharded inventory data, to prepare for the new dynamic sharding strategy, you’ll need to manually copy the inventory data to retain it.

• Description: The default sharding strategy is changing. This update changes how we determine where data is stored and will impact studios with existing inventory and payment data who have multiple databases configured.

  You must manually copy inventory data in order to keep any that is in a sharded state.

• Integration step:

  • Data copying: Manual data copying is very dependent on how many databases you currently have.

    You will need to back up all data, run a SQL copy of all relevant tables (inventory) from database shard 2 into shard 1, and configure inventory to utilize only one shard going forward.

    InventoryDaoConfig:
        databaseConfig:
            driver: "MYSQLDB"
            username: "superuser"
            password: "password"
            hostPortSchemas:
                1: "localhost:3306/local_game_player_inventory1"
    

    You will then need to rebalance your data. Please reach out if you need any support so we can assist.

If you’re relying on default values in your configs, you’ll need to add back a shard to continue using both local shards, as the default behavior has been changed to use a single shard.

• Description: For configs that rely on default values, this change will make your environment only use a single database shard.
• Integration step: Add the second connection in your config to continue using both local shards.
• Example:

InventoryDaoConfig:
    databaseConfig:
        driver: "MYSQLDB"
        username: "superuser"
        password: "password"
        hostPortSchemas:
            1: "localhost:3306/local_game_player_inventory1"
            2: "localhost:3306/local_game_player_inventory2"

For managed infrastructure customers, ensure that the 5-ext/buildkite/config.json file exists.

• Description: All Pragma Engine-related Buildkite builds are now handled via the pragma-ci-cd-buildkite-plugin. As a result, Buildkite-related scripts have been migrated from pragma-engine into the plugin. As of this release, the Buildkite-related scripts are being deleted from pragma-engine, so you must ensure the pragma-ci-cd-buildkite-plugin is in use to continue using Buildkite.
• Integration steps:
  • Confirm that 5-ext/buildkite/config.json exists. config.json only requires a plugin-version field. The file should look something like this:

  {
  "plugin_version": "0.0.43"
  }
  

  • Confirm that the value of plugin_version is at least equal to the version in 4-demo/buildkite/config.json.

Unreal SDK: Rename UpdatePlayerSelectionsV1 to CanUpdatePlayerSelectionsV1 to match naming patterns.

• Description: This change was made to fix a naming inconsistency.
• Integration step: Update the following instances:

Bugs and Fixes #

Improved error messaging when linking accounts to other identity providers.

• Description: For the HTTP endpoint /v1/account/linkidentityprovideraccount EXPECTED errors will now include the PragmaError ID and print out debug information when in DEVELOPMENT. UNEXPECTED errors will still return an empty 403 response.

SDK integration simplified with a new variable in the update-pragma-sdk.sh script that specifies the relative path within a Pragma Engine git repository.

The Arbiter repo has been moved to a new location. It will now be version tagged to provide an easier way to cross-reference against your own code.

Docs #

[Updated Services Guide] Quick Guide on kicking a player added to Party page.

[Updated Services Guide] New example for extension data on the Plugins and Extension Data page.

[Updated Introduction Guide] Updated instructions on the Initial Setup page.

[New Services Guide] Added page on Custom Errors to the Customization section.

August 30th, 2022

Features #

Added SDK event for MatchTerminationV1Notification for matches that are shut down by Pragma Engine.

• Description: Unity and Unreal game clients can now listen for a new SDK event named PartyService.OnMatchTermination, which occurs whenever an in-progress match is terminated by Pragma Engine due to failure reasons such as exceeding the absolute match timeout duration or missing heartbeat cycles.

Integrations #

Unreal: You must now initialize Pragma Session Subsystems before using them.

• Description: UPragmaSessionLocalPlayerSubsystem and UPragmaSessionGameServerSubsystem no longer automatically initialize SdkConfig with default values.
• Integration step: If using UPragmaSessionLocalPlayerSubsystem or UPragmaSessionGameServerSubsystem, you must call the respective InitSession before calling GetSession.

Bugs and Fixes #

For managed infrastructure customers: Separated Pragma Engine demo CI pipeline and customer ext CI pipeline.

• Description: We’ve added a new file at pragma-engine/platform/5-ext/buildkite/engine-ci.yml. This separation of engine-ci.yml files will allow studios to have separate, customizable CI steps in their workflows outside of Pragma Engine’s pipeline.

Unreal: Added a workaround for a JSON serialization bug where structs were serialized using the case-insensitive property FName.

Docs #

[Updated Services Guide] Added section on generating Partner tokens to Authentication page.

[Updated Services Guide] Added section on failure and success notifications to Match End page.

[Updated Services Guide] Removed references to enablePartyRecreate throughout docs as the feature has been deprecated.

[Updated Introduction Guide] Added section on logging to Initial Setup page.

August 23rd, 2022

Features #

Added Keep Alive Heartbeats feature in Match Lifecycle that sets a heartbeat to determine if matches need to be forcibly ended.

• Description: You can configure the Keep Alive loop by setting the MatchLifecyleServiceConfig.enableKeepAlive to true in the config. keepAliveIntervalMillis determines the interval of heartbeats. missedKeepAlivesBeforeCleanup determines how many heartbeats can be dropped before Pragma Engine ends the match.
• Details: Your game servers must use the newest Pragma Engine SDK and the new MatchLifecycleService.MatchReady and MatchLifecycleService.MatchEnd SDK functions.

Added Unreal and Unity SDK raw bindings for InventoryService.ApplyInventoryOperationsPartnerV1.

Added the ability to process player match ends prior to the end of the match.

• Description: Player match ends can now be processed prior to match end via the new Partner endpoint MatchLifecycleRpc.PlayerLeaveV1.

Portal: Users can now create an account and log in with Google.

• Description: We’ve implemented Google OAuth using an implicit grant flow to allow users to log in to Portal using Google. We’ve removed access_token and refresh_token from the backend as cleanup.

Integrations #

In the Match Lifecycle service config, update your configuration to not include enablePartyRecreate.

• Description: The config option MatchLifecycleServiceConfig.enablePartyRecreate has been deleted due to rearchitecture of the game loop flow.
• If this disrupts your intended Party flow, please reach out to us directly so we can help you resolve it.
• Integration steps:
  • Update configuration to not include MatchLifecycleServiceConfig.enablePartyRecreate if set.
  • Ensure client SDKs are compatible with the behavior of the platform–that players stay in a party during a match, and are released from the game loop after MatchEnd.

Migrate any usages of the StartReportCapacityPolling that does not take in a GameServerZone to the new StartReportCapacityPolling that does.

• Description: The version of the MatchCapacityService.StartReportCapacityPolling function in the SDKs that does not take in a GameServerZone has been removed in favor of a version that does.
• Integration steps:
  • Migrate any usages to the StartReportCapacityPolling function that is able to take in a GameServerZone.

    original	replacement
    Unity: public void StartReportCapacityPolling(string serverId, string gameVersion, float timeout, MatchAllocatedDelegate onComplete)	Unity: public void StartReportCapacityPolling(string serverId, string gameVersion, string gameServerZone, float timeout, MatchAllocatedDelegate onComplete)
    Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling(FString ServerId, FString GameVersion, float Timeout,const FMatchAllocatedDelegate& OnComplete)	Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling(FString ServerId, FString GameVersion, FString GameServerZone, float Timeout, const FMatchAllocatedDelegate& OnComplete)

  • If you don’t use GameServerZone, you can pass an empty string into these methods.

Unity: If your tests use any of the helpers listed below, update your using imports to include the new helpers folder.

• Description: A few test helper files in the Unity SDK have been moved into a helpers directory for better organization. The new folder is tests/helpers and contains the following files:
  • AsyncTest.cs
  • ControllableFireAndForget.cs
  • PartyTestHelpers.cs
  • PragmaSessionTestFixture.cs
  • RetryTracker.cs
  • test_messsages.proto
  • TestMessages.generated.cs
• Integration step:
  • If your tests were using any of the listed helpers, update your using imports to include the new helpers folder (i.e. using test.helpers.AsyncTest).

Bugs and Fixes #

A new file has been generated: platform/5-ext/buildkite/engine-ci.yml. You may safely commit this file. It will be used in a future release.

Docs #

[New Tech Blog video] Creating Stackable Items video is now live! The video is embedded in the Creating Stackable Items article and available via YouTube and the Pragma Blog.

[Updated Services Guide] Added a new Cancellations section on the Concurrency page.

[New User Guide] Added a new section on Creating A Test for the Echo service in the Custom Services guide.

[Revamped Services Guides] Overhauled the Game Services guide and renamed the category from Game to Game Flow.

• Description: All pages in this category from Party to Matchmaking to Game Server Management have been rewritten for clarity.

August 16th, 2022

Features #

Added a new MatchLifecycleConfig feature called inProgressMatchTimeoutMillis for setting timeouts for in-progress matches.

• Description: The new inProgressMatchTimeoutMillis configuration allows you to set a timeout for in-progress matches. enablePartyRecreate is honored in case of a match timing out, so if enabled, the players will be put back into a party. This change is backwards compatible.
• Details: To use this feature, in your game configuration, find MatchLifecycleConfig.inProgressMatchTimeoutMillis, and specify the milliseconds you want a game to go for before expiring the match completely. Any subsequent MatchEnd payloads for that match will be ignored.
• Example:

game:
  serviceConfigs:
      MatchLifecycleServiceConfig:
          inProgressMatchTimeoutMillis: 10000 // exp match in 10 sec

New configuration allows you to define the endpoint for email verification links.

• Description: To decouple the SocialGameGatewayConfig from the Account service, we’ve added a new configuration for defining where email verification links go. This is backwards compatible.
• Example:

social:
  serviceConfigs:
      AccountServiceConfig:
          verificationEmailEndpoint: "http://127.0.0.1:11000//v1/account/verifyemailv1"

Added RPC endpoints for applying inventory operations.

• Description: We’ve added endpoints for applying inventory operations such as stackable and instanced item grants and updates, instanced items to destroy, and rewards to grant.
• Details:
  • applyInventoryOperationsOperatorV1
  • applyInventoryOperationsPartnerV1
  • applyInventoryOperationsServiceV1

Added new fields for deleting instanced items on MatchEnd and in response to creating or updating an instanced item.

• Description: Fields have been added for destroying instanced items in two locations: InstancedItemPluginResult (in response to creating or updating an item) and InventoryOperationsPlugin.InventoryOperations (on MatchEnd).
• Details:
  • InstancedItemPluginResult is returned by InstancedItemPlugin.newInstanced and InstancedItemPlugin.update.

  data class InstancedItemPluginResult(
  val extInstancedItem: ExtInstancedItem,
  val rewardGrants: List<RewardGrant> = listOf(),
  val instancedItemServerGrants: List<InstancedItemServerGrant> = listOf(),
  val stackableItemGrants: List<StackableItemGrant> = listOf(),
  val serverInstancedItemUpdates: List<ServerInstancedItemUpdate> = listOf(),
  val instancedItemsToDestroy: List<InstanceId> = listOf() // NEW FIELD
  )
  

  • InventoryOperationsPlugin.InventoryOperations is returned by InventoryOperations.getInventoryOperationsFromMatchEnd.

  data class InventoryOperations(
  val stackableItemGrants: List<StackableItemGrant> = listOf(),
  val stackableItemUpdates: List<StackableItemUpdate> = listOf(),
  val instancedItemGrants: List<InstancedItemGrant> = listOf(),
  val instancedItemServerGrants: List<InstancedItemServerGrant> = listOf(),
  val instancedItemUpdates: List<InstancedItemUpdate> = listOf(),
  val rewardGrants: List<RewardGrant> = listOf(),
  val instancedItemsToDestroy: List<InstanceId> = listOf() // NEW FIELD
  )
  

Integrations #

Update SDK configuration with new authorization tokens.

• Description: The original partnerSessionAuthToken config value in Unity/Unreal SDKs was built before the separation of Social and Game backend tokens. The new config values partnerSessionGameAuthToken and partnerSessionSocialAuthToken have been added to allow Partner sessions to designate specific tokens per backend.
• Integration steps:
  • In the Unreal/Unity SDK, update any configs with a Partner session auth token (such as in pragma.json).

    original	replacement
    partnerSessionAuthToken	partnerSessionGameAuthToken

  • Add a partnerSessionSocialAuthToken config option for situations where a Partner session needs to connect to the Social backend, and provide it with a Partner Social token.

Replace the listed RPC request implementation calls with their replacements, as they are being removed.

• Description: This is part of our larger engine cleanup.
• Integration step: If you’re using any of these calls in plugins or custom services, replace them and apply transforms when necessary.

  original	replacement
  Service::requestRpcAndTransform()	Service::requestRpc()
  RpcClient::requestRpcAsync()	async { requestRpc() }
  Service::requestRpcAsync()	async { requestRpc() }
  Service::requestRpcAsyncAndTransform()	async { Service::requestRpc() }

Update PartyPlugin implementation by migrating any logic from recreate into returnFromMatchmaking and returnFromMatch.

• Description: The method recreate has been replaced by the returnFromMatchmaking & returnFromMatch methods. These two new methods have a more flexible interface and allow a subset of the whole party to be returned to the Party service.
• Integration steps:
  • Open PartyPlugin implementations.
  • Replace implementations of recreate with the new functions returnFromMatchmaking and returnFromMatch.
  • Delete implementation of recreate from interface.

    original	replacement
    recreate	returnFromMatchmaking & returnFromMatch

Bugs and Fixes #

Added a new fix for cleaning up a match if MatchLifecycleServiceConfig.enablePartyRecreate is disabled.

• Description: When MatchLifecycleServiceConfig.enablePartyRecreate is disabled, Pragma Engine now properly unsets all game loop related session data, and the SDKs properly clean up their cached Party information.

Docs #

[Updated Services Guide] Updated Extension Data section on the Party page to include information like hidden data.

[New Introduction Page] Added a generated configuration table.

[Updated Introduction Page] Updated the Plugins & Extension Data section within Introduction.

[Updated Services Guide] Added new content to the Plugins & Extension Data section within Customization.

[Updated Services Guide] Replaced the “Dependent Jobs” page with a new Concurrency page which contains information on both concurrency and dependent jobs in Pragma Engine.

August 9th, 2022

Features #

Added requestingPlayer parameter to limit access to party detail changes.

• Description: The requestingPlayer parameter has been added to the Party plugin interface to allow plugins to decide who can change party details. For example, you can deny changes requested by a party member other than the party leader.
• Related notes: See related integration note.

Added new account tag actions in the Unity/Unreal SDKs for Partners.

• Description: Partner sessions can now view and bulk modify tags on player accounts via Unity and Unreal SDKs.
• Details:
  • New SDK bindings for the following existing Partner endpoints:
    • AccountService.getAccountTagsPartnerV1(playerSocialIds: get the tags for a given list of accounts
    • AccountService.AddAccountTagsPartnerV1(playerSocialIds, tagsToAdd): add tags to multiple accounts
    • AccountService.removeAccountTagsPartnerV1(playerSocialIds, tagsToRemove): remove tags from multiple accounts
  • New endpoint and SDK binding:
    • AccountService.viewTagsPartnerV1(): retrieve all existing tags in the system

Integrations #

Add the requestingPlayer parameter to implementations of PartyPlugin.updateParty().

• Descriptions: To enable the new requestingPlayer feature, you must complete the listed integration step.
• Integration step: Add requestingPlayer: PartyPlayer as the first parameter of the PartyPlugin.updateParty() method. Update any references to UpdateDisplayNameV1Request to UpdateDisplayNameOperatorV1Request.

suspend fun updateParty(
requestExt: ExtUpdatePartySelectionsRequest,
party: Party, partyConfig: PartyConfig
)

suspend fun updateParty(
 requestingPlayer: PartyPlayer,
 requestExt: ExtUpdatePartySelectionsRequest,
 party: Party, partyConfig: PartyConfig
)

• Related note: See related feature note.

If you’re using dynamicSharding support, correct columnNameOfpropertyToConsistentHash in InventoryDaoConfig by capitalizing the word Property.

• Description: We’ve adjusted this capitalization to more accurately follow naming standards.
• Integration step:
  • Make the following change in InventoryDaoConfig:

    original	replacement
    columnNameOfpropertyToConsistentHash	columnNameOfPropertyToConsistentHash

Migrate all instances of ShutdownV1Notification to the new RemovedV1Notification.

• Description: We’ve replaced ShutdownV1Notification with a more accurately named notification called RemovedV1Notification. This should be used to alert clients when a player is removed from a party.
• Integration step: Complete the following migration:

  original	replacement
  ShutdownV1Notification	RemovedNotification

Replace all uses of authenticateOrCreateV1 with authenticateOrCreateV2.

• Description: The authenticateOrCreateV1 http endpoint and the AuthenticateOrCreateV1Request and AuthenticateOrCreateV1Response messages have been removed.
• Integration steps:
  • Update any usages of authenticateOrCreateV1 endpoint to the authenticateOrCreateV2 endpoint and use the corresponding AuthenticateOrCreateV2Request and AuthenticateOrCreateV2Response messages.
  • The AuthenticateOrCreateV2Response no longer contains the pragma_player_token. Instead you should use the pragma_game_token and pragma_social_token depending on what service is being connected to.

    original	replacement
    authenticateOrCreateV1	authenticateOrCreateV2
    pragma_player_token	pragma_game_token and pragma_social_token

Update all references of the MatchFoundPlugin to the Match Lifecycle service package.

• Description: MatchFoundPlugin’s definition has been moved from the Matchmaking service package to a Match Lifecycle service package. You’ll need to update the MatchFoundPlugin import if you’ve defined your own implementation, or update the config if you use the Pragma Engine-provided one.
• Integration steps:
  • If you’ve defined your own implementation of MatchFoundPlugin, update the import from pragma.matchmaking.MatchFoundPlugin to pragma.matchlifecycle.MatchFoundPlugin.
  • If your config uses the Pragma Engine-provided pragma.matchmaking.DefaultMatchFoundPlugin, update it to pragma.matchlifecycle.DefaultMatchFoundPlugin.

Update all references to UpdateDisplayNameV1Request to UpdateDisplayNameOperatorV1Request.

• Description: We’ve renamed the UpdateDisplayNameV1Request Operator RPC to match our naming standards and avoid session-type collisions.
• Integration step: Update references to UpdateDisplayNameV1Request to capture the rename.

  original	replacement
  UpdateDisplayNameV1Request	UpdateDisplayNameOperatorV1Request

• Note that If you’ve built a Portal from source instead of using the packaged portal-base, you’ll need to rebuild and redeploy Portal.

Add configuration for PaymentDaoNodeService to prepare for upcoming payments functionality.

• Description: In preparation for upcoming payments functionality, a new DaoNodeService has been created which will require configuration.
• Integration step: Add the following new configuration for the PaymentDaoNodeService in your YAML file:

social:
    serviceConfigs:
        PaymentDaoConfig:
            databaseConfig:
            driver: "MYSQLDB"
            username: "<database user>"
            password: "<encrypted password>"
            hostPortSchemas:
                1: "<database host>:<database port>/<shard>_social_orderhistory1"
                2: "<database host>:<database port>/<shard>_social_orderhistory2"

August 2nd, 2022

Features #

• A Party leader can now specify a list of preferred game server zones to be used by the Matchmaking service to select a GameServerZone for a match.
  • Description: Party leaders specify a list of PreferredGameServerZones, which is included in the Party service CreatePartyV1 call and can be updated with SetPreferredGameServerZonesV1. This list can then be used by MatchmakingStrategy.addToMatchAndBuildMatchmakingDetails to select a single GameServerZone to be used in Matchmaking. Game servers should pass in the GameServerZone to MatchCapacityService.StartReportCapacityPolling.
  • Related notes: See related deprecation, feature, and integration notes for GameServerZone.
• A GameServerZone can now be mapped to a Multiplay region using the MultiplayCapacityProvider.
  • Description: MultiplayCapacityProvider can now take a GameServerZone and map it to a Multiplay region. To use this, provide a new configuration to map GameServerZones to Multiplay RegionIds and remove the old regionId field from the config.
    
    If using AllocateV2, gameServerZone is passed into the allocation. You can then query the Multiplay local proxy to get the game server zone to be passed to the SDK’s MatchmakingService.StartReportCapacityPolling. Note that to use multiple region support, you will need to implement all related game server zone integrations.
  • Example:

  game:
  pluginConfigs:
    MatchCapacityService.capacityProvider:
      class: "pragma.matchcapacity.MultiplayCapacityProvider"
      config:
        gameServerZoneToMultiplayRegionId:
          gameServerZone1: "b7a6d0e8-a9eb-11eb-8c6a-7d2df11035b2"
          gameServerZone2: "291b8a29-468d-4eef-aeb8-7591402c4044"
  

  • Related notes: See related deprecation, feature, and integration notes for GameServerZone.
• Added two methods on both SDKs for kicking a player from a party.
  • Description: Players can be kicked from a party, which prevents them from rejoining the party unless they receive a new invitation. KickPlayerV1 makes an RPC call to kick the provided PlayerId from a party, and CanKickPlayerV1 lets the client know if it’s able to execute a kick.
    
    When a player is kicked, everyone in the party receives a PartyDetailsV1Notification to update the party state, and the kicked player receives a RemovedV1Notification with a KICKED reason.
• [Portal] All config.json data has been relocated to portalDevConfig.default.js to prevent merge conflicts and ease custom portlet development.
  • Description: The /platform/web/portal/src/assets/public/config.json config has been removed, and all data has been relocated to /platform/web/portal/portalDevConfig.default.js, which can now be extended locally like all other portal configurations. The config.json data can be found under app.config and app.extraConfig configuration keys. This only affects studios with active development on custom portlets when running the Portal locally in development mode.
  • Example: To enable a custom portlet, the following needs to be added to /platform/web/portal/portalDevConfig.local.js:

  module.exports = {
     default: {
        "app.extraConfig": {
         modules: ["MyCustomPortlet"]
        }
     },
  }
  

Deprecations #

• Update MatchCapacityService.StartReportCapacityPolling to take the new parameter GameServerZone.

  • Description: The StartReportCapacityPolling function in the MatchCapacity service takes the new parameter GameServerZone. You will need to either update your code in the SDKs or pass in an empty string.

  Original	Replacement	Removal Patch
  Unity: public void StartReportCapacityPolling( string serverId, string gameVersion, float timeout, MatchAllocatedDelegate onComplete )	Unity: public void StartReportCapacityPolling( string serverId, string gameVersion, string gameServerZone, float timeout, MatchAllocatedDelegate onComplete )	0.0.80
  Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling( FString ServerId, FString GameVersion, float Timeout, const FMatchAllocatedDelegate& OnComplete )	Unreal: UPragmaMatchCapacityService::StartReportCapacityPolling( FString ServerId, FString GameVersion, FString GameServerZone, float Timeout, const FMatchAllocatedDelegate& OnComplete )	0.0.80

  • Related notes: See related integration and feature notes for GameServerZone.

• Replace the listed RPC request implementation calls with their replacements, as they are being removed.

  • Description: This is part of our larger engine cleanup. If you’re using any of these calls in plugins or custom services, replace them and apply transforms when necessary.

    original	replacement	removal patch
    Service::requestRpcAndTransform()	Service::requestRpc()	0.0.80
    RpcClient::requestRpcAsync()	async { requestRpc() }	0.0.80
    Service::requestRpcAsync()	async { requestRpc() }	0.0.80
    Service::requestRpcAsyncAndTransform()	async { Service::requestRpc() }	0.0.80

• Update SDK configuration with new authorization tokens.

  • Description: The original partnerSessionAuthToken config value in Unity/Unreal SDKs was built before the separation of Social and Game backend tokens. The new config values partnerSessionGameAuthToken and partnerSessionSocialAuthToken have been added to allow partner sessions to designate specific tokens per backend. The original config value will be removed in 0.0.80.
    
    Add a partnerSessionSocialAuthToken config option for situations where a partner session needs to connect to the Social backend, and provide it with a partner Social token.
    
    In the Unreal/Unity SDK, update any configs with a partner session auth token (such as in pragma.json).

    original	replacement	removal patch
    partnerSessionAuthToken	partnerSessionGameAuthToken	0.0.80

Integrations #

• If you’ve customized your CapacityTracker or MatchmakingStrategy, you will need to update your plugins for the new GameServerZone features.
  • Description: Studios who have customized their own CapacityTracker or MatchmakingStrategy will need to update their plugins. These two game loop plugins allow the user to set up GameServerZone flows within their match loop.
  • Integration steps:
    • Update implementations of the CapacityTracker add function to receive a new parameter indicating which GameServerZone a game should be created in.
    • Update implementations of the MatchmakingStrategy function addToMatchAndBuildMatchmakingDetails to return a Pair<ExtCreateMatchV1Request, String>?. The second new string return value allows the plugin to indicate which GameServerZone the match should be created in. If you don’t want to use GameServerZone, use an empty string here.

      original	replacement
      ExtCreateMatchV1Request?	Pair<ExtCreateMatchV1Request, String>?

• Add new ExtHiddenPartyData and ExtHiddenPlayerData proto definitions to partyRpcExt.proto.
  • Description: The new ExtHiddenPartyData and ExtHiddenPlayerData protos will allow you to store temporary data about players and parties throughout the game loop.
  • Integration step: Add the following proto definitions to ext-protos/src/main/proto/shared/partyRpcExt.proto in order to successfully compile.

    message ExtHiddenPartyData {
    }
    message ExtHiddenPlayerData {
    }
    

• If you’ve implemented your own MatchCapacity provider, remove the coroutineScope argument from the init() method.
  • Description: To increase product maintainability and reliability, CapacityProvider.init() no longer takes coroutineScope as an argument.
  • Integration step: If you’ve implemented your own MatchCapacity provider from the ground up, remove coroutineScope from its init() method. If you’ve extended an existing Pragma Engine MatchCapacity provider, no action is required.
    
    If you still need coroutineScope support, please reach out to us directly.
• [Portal] If you’ve written a custom PortalModulePlugin, CORS definitions need to be rerouted into their respective gateways.
  • Description: Anyone who has written a custom PortalModulePlugin will need to reroute CORS definitions. The attachPortalModule function on the Portal plugin has been removed and the install CORS functionality has been moved out to the gateways.
  • Integration step: Update attachPortalRoutes to take in an Application instead of a Routing object. For example:

override fun attachPortalRoutes(
  routing: Routing,
  pragmaNode: PragmaNode,
  infoEndpoint: Url
) {
  routing.route("config/config.json") {
    get {
      call.respondText(
        buildConfigJson(pragmaNode,infoEndpoint),
        ContentType.Application.Json
      )
    }
  }
  routing.static {
    staticRootFolder = File(config.portalSource)
    files(".")
    default("index.html")
  }
}

override fun attachPortalRoutes(
  application: Application,
  pragmaNode: PragmaNode,
  infoEndpoint: Url
) {
  application.apply {
    routing {
      options {
        call.respond(HttpStatusCode.OK)
      }

      route("config/config.json") {
        get {
          call.respondText(
            buildConfigJson(
              pragmaNode,
              infoEndpoint
            ),
            ContentType.Application.Json
          )
        }
      }

      static {
        staticRootFolder = File(config.portalSource)
        files(".")
        default("index.html")
      }
    }
  }
}

• [Unreal] Update C++ Raw Service class names from Pragma to the root of your proto package.
  • Description: For any generated raw services, the C++ class names have changed to use the root of your proto package instead of Pragma.
  • Integration step: Update generated custom raw service names:

    original	replacement
    UPragmaCustomServiceRaw	UGameCustomServiceRaw

Docs #

• [New Services Guide] Dependent Jobs services guide is now live!
• [Updated Services Guide] Updated Login & Session services guide with information about dependent jobs.
• [Updated Services Guide] Updated Party services guide with a quick guide on using local game servers with Party matchmaking.
• [New Services Guide] New Custom Services landing page is now live!
  • Description: The brand new Custom Services landing page provides the information needed to get started with extending Pragma Engine using custom services.
• [API Reference] Third-level nesting of types within packages for API ref docs is now live.
• [Pragma Blog] Setting Up Pragma Engine video tutorial is now live!
• [Tech Blog] The Pragma Engine Tech Blog is now live!
  • Description: The Tech Blog provides friendly, accessible articles about Pragma Engine’s features, functions, and capabilities.
• [New Tech Blog articles] The Stackables series is now live!
  • Creating Stackable Items
  • Purchasing Stackable Items in a Store
  • Creating a Crafting System Using Stores

July 26th, 2022

Deprecations #

• Migrate all instances of ShutdownV1Notification to the new RemovedV1Notification.
  • Description: We’ve replaced ShutdownV1Notification with a more accurately named notification called RemovedV1Notification. This should be used to alert clients when a player is removed from a party.

    Original	Replacement	Removal Patch
    ShutdownV1Notification	RemovedV1Notification	0.0.78

Integrations #

• Update any references from the TestFactory function generateList2 to generateList.

  • Description: Two similar implementations of the generateList Test Factory pattern have now been collapsed into one function.
  • Integration step:
    • Update any references in test code from the TestFactory function generateList2 to generateList.

      Original	Replacement
      TestFactoryUtils.generateList2	TestFactoryUtils.generateList

• Update any references in SDK code from OnMatchStartFailureV1Notification to OnMatchFailureV1Notification.

  • Description: Collapsed two similar notifications sent to the SDK in scenarios where a player finished matchmaking but failed to start the match.
  • Integration step:
  • Update any references in SDK code directly attached to the raw Matchmaking service’s OnMatchStartFailureV1Notification to the raw MatchLifecycle service’s OnMatchFailureV1Notification event.

    Original	Replacement
    OnMatchStartFailureV1Notification	OnMatchFailureV1Notification

• Update any references in SDK code for the listed match-related service handlers from PartyServiceRaw to MatchLifecycleServiceRaw.

  • Description: Three match-related service handlers have been relocated in the Unreal and Unity SDKs, so references to the raw handlers will need to be updated. Note that these are still mapped into the PartyService; only the location of the raw endpoints has been moved.
  • Integration step:
    • Update any references in SDK code for the following raw service handlers from PartyServiceRaw to their new locations in MatchLifecycleServiceRaw.

      Original	Replacement
      PartyServiceRaw.OnMatchReadyV1Notification	MatchLifecycleServiceRaw.OnMatchReadyV1Notification
      PartyServiceRaw.OnMatchFailedV1Notification	MatchLifecycleServiceRaw.OnMatchFailedV1Notification
      PartyServiceRaw.OnMatchReconnectV1Notification	MatchLifecycleServiceRaw.OnMatchReconnectV1Notification

• Update references to CostEntry and PurchaseRequirements to their new locations in InventoryCommon.

  • Description: To support the ongoing development of a microtransaction feature, CostEntry and PurchaseRequirements needed more shareable access, so they’ve been moved to InventoryCommon.
  • Integration step:
    • Update references to CostEntry and PurchaseRequirements from their old locations in InventoryContent to their new locations in InventoryCommon.

      Original	Replacement
      InventoryContent.CostEntry	InventoryCommon.CostEntry
      InventoryContent.PurchaseRequirements	InventoryCommon.PurchaseRequirements

• If you’ve implemented the PartyPlugin, update the onRemovePlayer function with the new RemovalReason field.

  • Description: PartyPlugin.onRemovePlayer has a new RemovalReason field which provides the reason for a player leaving a party. This change only impacts studios who have already implemented their PartyPlugin.

  • Integration step:

    • Update the onRemovePlayer function with the new RemovalReason field.

    Original	Replacement
    override suspend fun onRemovePlayer( party: Party, removedPlayer: PartyPlayer ) { ... }	override suspend fun onRemovePlayer( party: Party, removedPlayer: PartyPlayer, removalReason: RemovalReason ) { ... }

• Unreal: Replace ReportCapacityUntilMatchAllocated with StartReportCapacityPolling.

  • Description: This change will make sure that ReportCapacity continues to poll even after finding a match. Note that the order of the ReportCapacityTimeout argument and callback (the last 2 arguments) need to be reversed. Note that this change only impacts Unreal users, as the Unity change was previously implemented.
  • Integration step:
    • Replace ReportCapacityUntilMatchAllocated with StartReportCapacityPolling.

      Original	Replacement
      ReportCapacityUntilMatchAllocated	StartReportCapacityPolling

Docs #

• [New User Guide] New Custom Services User Guide is now live!
• [Updated SDKs & Tools Guides] Updated SDKs & Tools Guides to have third-level nesting for Steam and Discord tutorials.
• [Updated Services Guide] Updated Using Discord section of the Authentication Service Guide.

July 19th, 2022

Features #

• Added server authoritative token refresh to prevent players from bypassing restrictions for limited access events.

  • Description: With the added server authoritative token refresh, the platform keeps track of how long the session should be open for. If a user does not refresh their session, they will be disconnected when their session expires. This is to avoid situations where a user could hack the game client to skip limited access events’ expiration logic for user sessions.

• You can now allocate players in the same party to different, custom teams during matchmaking.

  • Description: Players in the same party can be allocated to different teams during matchmaking to allow for custom teams within a party. To override the default behavior and allow for custom teams, you can set the value of the teamNumber property stored for each player in the MatchmakingParty.playerInfoList list. When the teamNumber is empty, the matchmaking system will decide which team a player should be on. Setting the property to a value will override the typical matchmaking system, which allows for custom teams.

• Portal: Added search and filter options in Player Support.

  • Description: Visit Player Support > Players. You can now search and filter through player accounts.

• Unreal: Code generation can now use FName instead of FString by using the export_as_key field option in protos.

  • Description: To improve code performance by reducing string operations in some proto messages, you can now use Unreal code generation to generate FName instead of FString. This works for fields tagged with the custom option export_as_key. Note that you may need to Reload All Maven Projects before the new option is recognized in Intellij.

• Unreal: Pragma-provided subsystems can now initialize their PragmaSession with a custom SdkConfig.

  • Description: You can now use the Pragma-provided PragmaSessionLocalPlayerSubsystem and PragmaSessionGameServerSubsystem with custom runtime configurations instead of needing to manage your own PragmaSession pointer.

Integrations #

• Migrate all GameDataStrategyPlugin logic in the new LoginDataPlugin.
  • Description: The GameDataStrategyPlugin has been removed in favor of a new plugin, LoginDataPlugin, which defines the dependent jobs to be run to collect login data.
  • Integration step:
    • Migrate all your custom logic from GameDataStrategyPlugin into LoginDataPlugin. While GameDataStrategyPlugin and LoginDataPlugin are both designed to accomplish the same tasks, their structures are different, so you cannot simply copy your existing code over.

      original	replacement
      GameDataStrategyPlugin	LoginDataPlugin

Bugs and Fixes #

• Unity: Fixed race condition in WebSocket send causing silent disconnect with no reconnect.

Docs #

• [New Services Guide] New Portal Services section is now live!
  • Description: A new Services section about the Portal has been added. This includes an overview, getting started steps, and customization using portlets.

July 12th, 2022

Features #

• New Operator endpoint added to list and filter player identities with an additional requirement for game shard ID.
  • Description: We’ve added a new endpoint GetPragmaPlayerOverviewsOperatorV1. This has the same filtering capabilities as the GetPragmaAccountOverviewsOperatorV1 endpoint, but also requires a game shard ID.
  • Postman Path:
• Portal: Instanced items can now be removed from player inventories.
  • Description: Visit Player Support > Players and select a player, then click Inventory. From the Instanced tab, items can be removed using the remove button at the end of the row.
• Portal: Previous search criteria is now saved and repopulated when clicking the back button.
  • Description: When filtering information on any page, clicking the back button will show the last search criteria used.
  • For example, from the Accounts page, you can filter player information, select a player to see their details page, and then click the back button–the original search criteria will be used.
  • If a page is opened through a shared link, clicking the back button will return a page without any saved search criteria.
• Portal: Amounts of stackable items in player inventories can now be modified.
  • Description: Visit Player Support > Players and select a player, then click Inventory. Select a stackable item name, then Edit Item to modify the Amount field.
  • Note that if an item is not set to be removed at 0 in the content catalog, it will remain in the table with the amount of 0. Otherwise, it will be removed from the table.
• Portal: Improved JSON validation error messages.
  • Description: New targeted JSON validation messages are now available in Portal. These messages can be clicked, causing the editor to scroll and select the relevant line.
• Unreal users no longer need to write SDK boilerplate for custom services RPC APIs.
  • Description: Unreal raw service code is now automatically generated based on protobuf RPCs. These classes can be found under the generated Public/Dto folder after running make gen-sdk-types-unreal4.
  • Related note: See integration note for steps required to enable this feature and guidelines for keeping any handwritten raw services.
    • Social → RPC Operator → Account → GetPragmaPlayerOverviewsOperatorV1

Deprecations #

• Replace ReportCapacityUntilMatchAllocated with StartReportCapacityPolling. Note that the order of the ReportCapacityTimeout argument and callback (the last 2 arguments) needs to be reversed.
  • Description: This change will make sure that ReportCapacity continues to poll even after finding a match.

    Original	Replacement	Removal Patch
    ReportCapacityUntilMatchAllocated	StartReportCapacityPolling	0.0.77

Integrations #

• Portal: If you’re using the current redirectSigninToSocial default (true), you will need to add a config flag, as the default has changed.
  • Description: We’ve changed Portal’s default for redirectSigninToSocial to false to avoid hostname issues with providers like Discord. If you’re currently using the redirect default, you’ll need to add a config flag.
  • Integration step:
    • If you’re using the current redirect default, you will need to add this config flag:

    pluginConfigs:
      GameOperatorGatewayNodeService.portalPlugin:
        class: "pragma.gateway.FilePortalModulePlugin"
        config:
                redirectSignInToSocial: true
    

• Unreal: Configure the game server SDK to use HTTP, and specify Social backend in RPC files for automatic generation. Make sure any handwritten raw services have unique class names.
  • Description: To enable the new automatically generated SDK service code, you’ll need to set a new SDK config option and specify backend type for Social RPCs (otherwise it defaults to Game). If you’d rather continue using your own handwritten raw service code, you can continue to do so as long as class names are different.
  • Integration steps:
    • Automatic generation setup:
      • Game Server only: Change SDK config option ProtocolType to HTTP (defaults to WebSocket). This can also be set via command line with -PragmaProtocolType="Http".
      • Add the following line at the top of Rpc.proto files for any Social backend RPCs to make sure code generation correctly identifies them: option (backend_type) = SOCIAL;
    • Handwritten raw service integration:
      • Confirm there are no conflicting file names with the new automatically generated files.
  • Related note: See Unreal automatic generation feature note above.

Bugs and Fixes #

• Unreal payloads >2048 characters are now truncated in Verbose. They will still be full length in VeryVerbose.

Docs #

• [Updated User Guide] Updated Crafting guide to reflect changes in various interfaces.
• [Updated User Guide] Updated Crafting: Time-based guide to reflect changes in various interfaces.
• [Updated User Guide] Updated Items guide to reflect changes in various interfaces.

July 5th, 2022

Features #

• You can now trigger a variety of inventory operations on a per-player basis at match end via the new InventoryOperationsPlugin.
  • Description: You can now update or grant stackable and instanced items on a per-player basis at match end via the new InventoryOperationsPlugin.
  • Details: If you opted into using the early preview of this plugin via the @OptIn(WorkInProgress::class) annotation, please see the integration note below.

Integrations #

• Update your InstancedItemPlugin to match the new interface.

  • Description: You can now return additional item grants, rewards, and updates on InstancedItemPlugin.newInstanced. Changes have been made to the InstancedItemPlugin interface to support this new feature, so you will need to make updates to your InstancedItemPlugin.

  • Integration steps:

    • UpdateResult has been renamed to InstancedItemPluginResult to reflect that this is the return type for both InstancedItemPlugin.newInstanced() and InstancedItemPlugin.update().

  • In addition to the new return type, newInstanced() has additional parameters.

    Original	Replacement
    fun newInstanced( instancedSpec: InventoryContent.InstancedSpec, clientRequestExt: ExtPurchaseRequest?, serverRequestExt: ExtInstancedItemServerGrant? ): ExtInstancedItem	fun newInstanced( instancedSpec: InventoryContent.InstancedSpec, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtPurchaseRequest?, serverRequestExt: ExtInstancedItemServerGrant? ): InstancedItemPluginResult
    fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult	fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): InstancedItemPluginResult

• Follow the integration steps below to fully remove the Progression service. Note that steps are organized based on your Pragma Engine version.

  • Description: The Progression service and all related protos, classes, and utils have finally been removed. The Progression service and all related protos, classes, and uils have finally been removed.
  • Integration steps: Depending on the version of Pragma Engine you’re upgrading from, steps will vary.
    • If you’re currently on Pragma Engine 0.0.70 or later:

      • Rename the following service calls:

        Original	Replacement
        MatchEndV2	MatchEndV4
        PlayerMatchEndV2	PlayerMatchEndV4

      • After confirming that they do not contain any wanted data, manually drop the player_progression databases.

      • If you’re using the Docker environment provided via /pragma-engine/platform/devenv/docker-compose-devenv for local development, you can also drop the following databases:

        • ete_test_game_player_progression1
        • ete_test_game_player_progression2
        • lobby_match_ete_test_game_player_progression1
        • lobby_match_ete_test_game_player_progression2
        • local_game_player_progression1
        • local_game_player_progression2
        • test_local_game_player_progression1
        • Test_local_game_player_progression2
    • If you’re currently on Pragma Engine 0.0.69 or earlier, update to Pragma Engine 0.0.73 first by following all required integrations listed in prior release notes, then update to Pragma Engine 0.0.74 by following the steps detailed in this release note.
  • If you’re an early user of PlayerDataUpdatesPlugin, rename the PlayerDataUpdatesPlugin to InventoryOperationsPlugin.
    • Description: See feature note above.

Bugs and Fixes #

• You can now view and edit huge JSON files in Pragma Portal without your browser tab locking up.
• Matchmaking now sends team assignment information to the game server.
  • Description: Matchmaking assigns teams to parties that enter matchmaking, but this information was not being sent to the game server. This is now properly sent to the game server.
  • Details: Added new team_number field to the PlayerInfoV2 payload that is sent to game servers in MatchDataV2. This field will be populated with the team number the player was assigned in matchmaking.

June 28th, 2022

Features #

• New game loop configuration options available.
  • Description: We’ve added the following new config options for match lifecycle: SessionConfig.enableMatchReconnect and MatchLifecycleServiceConfig.enablePartyRecreate. These both default to true, so to switch off match reconnect and party recreation configs, you’ll need to switch them to false.
• You can now configure game server version in the DefaultGameServerCompatibilityPlugin.
  • Description: To allow easy customization of a hardcoded game server version for CI/testing scenarios, we’ve introduced a gameServerVersion configuration class to the DefaultGameServerCompatibilityPlugin.
• InventoryService now supports multiple updates to a single InstancedItem through match end processing or the various UpdateItem APIs.
  • Description: Previously, attempting to apply multiple updates to an instanced item would cause only the last update to apply. Now, Pragma Engine handles multiple updates.
  • Details: InstancedItemPlugin.UpdateResult has been updated with a new field serverInstancedItemUpdates which is a List<ServerInstancedItemUpdate>.

Integrations #

• Modify your custom services by following the provided directions.

  • Description: We have reduced the number of thread pools in Pragma Engine to make the overall system more monitorable and configurable. This may affect your custom services.

  • Integration steps:

    • Make the following changes in your custom service.

    Original	Replacement
    launch	scope.launch
    async	scope.async
    coroutineContext	scope.coroutineContext

    • If you rely on PragmaNode being a CoroutineScope in your custom service, or if your service does not appear to run in Pragma Engine 0.0.73, please contact us to assess the best solution for your specific usage.

• Remove the ProgressionData parameter from your implementations of StorePlugin and CraftingPlugin.

  • Description: To prepare for the deletion of ProgressionService, we are removing progression-related fields from various plugins.
  • Integration steps:
    • Remove the ProgressionData parameter from your implementations of the following plugins:
      • StorePlugin
      • CraftingPlugin

• Replace usage of MatchProcessedV2Notification with MatchProcessedV3Notification.

  • Description: To prepare for the deletion of ProgressionService, we are disabling support for MatchProcessedV2Notification in order to remove progression-related data.
  • Integration steps:
    • Replace usage of MatchProcessedV2Notification with MatchProcessedV3Notification.

    Original	Replacement
    MatchProcessedV2Notification	MatchProcessedV3Notification

• Add new inventoryData parameter to update() method in custom implementations of InstancedItemPlugin.

  • Description: The InstancedItemPlugin interface has been updated. The update() method now expects inventoryData to be passed in. inventoryData contains a snapshot of the player’s inventory.

  • Integration steps:

    • Change the InstancedItemPlugin.update() method to include the new inventoryData parameter.

    Original	Replacement
    fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult	fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult

    • Note that the data class UpdateResult has also been updated with a new parameter, but as it has a default value, no integration steps are required.

• You may need to create your own test factory if you use certain InventoryProtoTestFactory methods.

  • Description: Certain InventoryProtoTestFactory methods have been changed to return the default instance.

  • Integration steps:

    • If you use any of the below InventoryProtoTestFactory methods, create your own test factory with the provided replacement or an appropriate equivalent.

    Original	Replacement
    InventoryProtoTestFactory.extStackableSpec()	fun extStackableSpec(i: Int) = generateProto(ExtStackableSpec::class, i)
    InventoryProtoTestFactory.extInstancedItemServerGrant(I:Int)	fun extInstancedItemServerGrant(i: Int) = generateProto(ExtInstancedItemServerGrant::class, i)

Bugs and Fixes #

• Removed references to the awsRegion configuration in the MultiplayCapacityProvider, as this value will always be eu-west-1 according to Multiplay.

June 14th, 2022

Features #

• New Party plugin function added to manage player ready states.
  • Description: The new Party plugin function canChangeReady which is called when players attempt to call SetReadyState. Return true to accept the update, and false to deny it.
  • Related notes: See ready state integration note and docs note.
• Unity: The Unity game server now reports match capacity usage.
  • Description: The Unity game server now uses ReportCapacityPolling to communicate match capacity usage to Pragma Engine from when a match has been allocated until the match is complete.
• Portal: Pragma Portal can now grant items and reward tables to players.
  • Description: You can now grant items and reward tables to players via the Pragma Portal. This can be found in the Player Support on a player’s page, under Inventory for a specific game. There are now buttons for granting rewards and items.
• Portal: Now contains a richer view of player inventory.
  • Description: You can now view player inventory items with details, filtering, and sorting. This can be found in Player Support on a player’s page under Games > Inventory.

Deprecations #

• Reimplement all GameDataStrategyPlugin logic in the new LoginDataPlugin.
  • Description: The GameDataStrategyPlugin is being removed in favor of a new plugin, LoginDataPlugin, which defines the dependent jobs to be run to collect login data.
  • Integration steps:
    • Reimplement all your custom logic from GameDataStrategyPlugin into LoginDataPlugin. While GameDataStrategyPlugin and LoginDataPlugin are both designed to accomplish the same tasks, their structures are different, so you cannot simply copy your existing code over.

      Original	Replacement	Removal Patch
      GameDataStrategyPlugin	LoginDataPlugin	0.0.74

Integrations #

• Rename methods and objects in implementations of MatchEndPlugin.

  • Description: MatchEndPlugin has been modified. The changes are mostly cosmetic, with new names for objects that reflect their nature more clearly. The most substantive change is that access to the DependentJobContext (old MatchEndContext) and the ThreadsafeMutable (old ConcurrentNotificationBuilder) are now provided on the method signature of the DependentJob (old MatchEndBuilder) instead of injected on construction.

  • Integration steps:

    • Rename the following items:

    Original	Replacement
    MatchEndPlugin.getMatchEndBuilders	MatchEndPlugin.getMatchEndJobs
    MatchEndContext	DependentJobContext
    ConcurrentNotificationBuilder	ThreadsafeMutable
    MatchEndBuilder	MatchEndDependentJob

    • Access DependentJobContext and ThreadsafeMutable via the methods on MatchEndDependentJob.

• Add canChangeReady implementation to Party plugin.

  • Description: Implementing this function is required for the new ready state feature.
  • Integration step: Add this function to Party plugin implementations to compile.
  • Related notes: See ready state feature note and docs note.

• Update references to Inventory service’s matchEndV1 and matchEndV2 endpoints to matchEndV4.

  • Description: The Service endpoints InventoryService.matchEndV1 and InventoryService.matchEndV2 have been replaced with InventoryService.matchEndV4, along with related protos.
    These calls only require integration if you’re calling them from a custom service. Pragma Engine handles all version bumps for Pragma-owned services.

  • Integration steps:

    • Update references to the following:

    Original	Replacement
    InventoryService.matchEndV1 InventoryService.matchEndV2	InventoryService.matchEndV4
    InventoryRpc.MatchEndV1Request InventoryRpc.MatchEndV1Response InventoryRpc.MatchEndV2Request InventoryRpc.MatchEndV2Response	InventoryRpc.MatchEndV4Request InventoryRpc.MatchEndV4Response

• Update references to Inventory service’s deletePlayerInventoryV1 endpoint to deletePlayerInventoryV2.

  • Description: The dev-only endpoint Player endpoint InventoryService.deletePlayerInventoryV1 has been replaced with InventoryService.deletePlayerInventoryV2, along with related protos.

  • Integration steps:

    • Update references to the following:

    Original	Replacement
    InventoryService.deletePlayerInventoryV1	InventoryService.deletePlayerInventoryV2
    InventoryRpc.DeletePlayerInventoryV1	InventoryRpc.DeletePlayerInventoryV2

• Update references to Lobby service’s endpoint lockV1 to lockV2.

  • Description: The Service endpoint LobbyService.lockV1 has been replaced with LobbyService.lockV2, along with related protos.
    These calls only require integration if you’re calling them from a custom service. Pragma Engine handles all version bumps for Pragma-owned services.

  • Integration step:

    • Update references to the following:

    Original	Replacement
    LobbyService.lockV1	LobbyService.lockV2
    LobbyRpc.LockV1Request LobbyRpc.LockV1Response	LobbyRpc.LockV2Request LobbyRpc.LockV2Response

• Update references to Match Lifecycle service’s matchendV3 to matchEndV4.

  • Description: The Partner endpoint MatchlifecycleService.matchEndV3 has been replaced with MatchlifecycleService.matchEndV4, along with related protos.
    The new endpoint does not include any Progression-related data fields on the payload.
    Note that matchEndV4 can still send MatchEndNotificationV2 messages, which have Progression-related fields, as the MatchEndNotificationV2 deprecation is still in progress.

  • Integration step:

    • Update references to the following:

    Original	Replacement
    MatchlifecycleService.matchEndV3	MatchlifecycleService.matchEndV4
    MatchlifecycleRpc.MatchEndV3Request MatchlifecycleRpc.MatchEndV3Response	MatchlifecycleRpc.MatchEndV4Request MatchlifecycleRpc.MatchEndV4Response

• Modify all custom IdentityProviders to return IdProviderAccount instead of PragmaResult<IdProviderAccount, PragmaError>.

  • Description: The validate function in IdentityProviderPlugins has been changed to either return an IdProviderAccount on success or to throw a PragmaException otherwise.
  • Integration step:
    • Modify any custom IdentityProviders to return an IdProviderAccount where they would return a PragmaResult containing the IdProviderAccount, and to throw a PragmaException when they would return a PragmaResult containing an error.

    Original	Replacement
    PragmaResult<IdProviderAccount, PragmaError> containing an IdProviderAccount	IdProviderAccount
    PragmaResult<IdProviderAccount, PragmaError> containing a PragmaError	Throw a PragmaException

• Unreal: Update references to UpdateLoadout in Party service to UpdatePlayerSelections.

  • Description: These renames will make the SDK interfaces better conform to the RPC endpoints.
  • Integration step:
    • Update references in the Unreal SDK’s Party service to the following:

    Original	Replacement
    UpdateLoadoutV1	UpdatePlayerSelectionsV1
    CanUpdateLoadoutV1	CanUpdatePlayerSelectionsV1

Docs #

• [New Services Guide] New Content Data landing page is now live!
  • Description: The brand new Content Data landing page contains everything you need to understand the Content Data system, from adding content to accessing and leveraging that content.
• [Updated Services Guide] Hidden Inventory summary and related quick guide have been added to the Items Services page.
• [Updated Services Guide] Steam authentication quick guide has been updated on the Authentication Services page.
• [Updated Services Guide] Ready state quick guide has been updated on the Party Services page.
  • Related notes: See ready state feature note and integration note.
• [Updated Getting Started Guide] Added Postman reminder to Initial Setup page.
  • Description: Remember to occasionally pull the latest Postman collection after new releases to ensure you’re getting updated calls.

June 7th, 2022

Deprecations #

• Upgrade the listed Inventory RPC calls to their new versions to support hidden inventory.

  • Description: To support the new hidden inventory feature, the following InventoryRpc calls have been updated to partition data into player and hidden sections.

  Original	Replacement	Removal Patch
  InventoryRpc.UpdateItemsPartnerV1	InventoryRpc.UpdateItemsPartnerV2	0.0.73
  InventoryRpc.UpdateItemsServiceV1	InventoryRpc.UpdateItemsServiceV2	0.0.73
  InventoryRpc.ServiceGetInventoryV1	InventoryRpc.ServiceGetInventoryV2	0.0.73
  InventoryRpc.GrantItemsServiceV1	InventoryRpc.GrantItemsServiceV2	0.0.73

• Upgrade to MatchProcessedV3Notifications to prepare for the removal of the Progression service.

  • Description: In preparation for the removal of Progression service, MatchProcessedV2Notifications are being deprecated. By release 0.0.73, you must have updated to the MatchProcessedV3Notifications.

  Original	Replacement	Removal Patch
  Unity: OnMatchProcessedV2Notification	Unity: OnMatchProcessedV3Notification	0.0.73
  Unreal: OnMatchProcessedV2	Unreal: OnMatchProcessedV3	0.0.73

  • Integration steps:

    • A feature toggle in MatchLifecycleService can be configured to switch to V3 once you’re ready:

    game:
      serviceConfigs:
        MatchLifecycleServiceConfig:
          sendMatchProcessedV3Notification: true
    

    • Once you’ve successfully switched over to V3, be sure to update any references to the new version.

Integrations #

• Remove all uses of PartyPlayer.progression in the PartyPlugin functions.
  • Description: As part of the Progression service deprecation, we’re removing all progression data from interservice calls and plugins.
  • Integration steps:
    • Audit your use of these functions to ensure that you are not using PartyPlayer.progression:
      • initializeParty
      • recreateParty
      • onAddPlayer
      • onRemovePlayer
      • updatePlayer
      • updateParty
      • buildMatchmakingKey
      • buildExtEnterMatchmakingV2Request
• Update MatchLifecycle.MatchEndV4Request to use new itemServerGrants field.
  • Description: MatchLifecycle.MatchEndV4Request is being changed to use the itemServerGrants field instead of itemGrants to better reflect the fact that these grants are coming from the server and are trusted.
  • Integration steps:
    • Assign any item grants in PlayerMatchEndV4 under the itemServerGrants field.

    Original	Replacement
    itemGrants: List<inventory.ItemGrantV2>	itemServerGrants: List<inventory.ItemServerGrantV1>

Bugs and Fixes #

• Unreal SDK: Fixed issue with core SDK always invalidating the Makefile. This should decrease build times by a few seconds.

Docs #

• [Updated Services Guide] New sections have been added to the Party Services Guide for custom Party behavior, along with a related Quick Guide.

June 1st, 2022

Features #

• Inventory items can now be hidden from players.

  • Description: Player stats such as matchmaking ratings can be tracked as ext fields on instanced items. These items can now be hidden to avoid leaking data to players.

    The table below contains a list of affected service calls and their new behavior.

  Service call	Description
  craftV1, storePurchaseV4, updateItemV4, and updateItemsV0	returned segments/deltas won’t contain items with tags that match the configuration
  getStoresV0	return stores will not contain store entries with tags that match the configuration
  getInventoryV2	returned inventory will not contain instanced and stackables whose corresponding content specs contain tags that match the configuration
  GameDataService.GetLoginDataV1 which uses InventoryService.GetLoginData	returned player inventory and content items (stores, update entries, item catalog, crafting entries, etc) are all filtered based on the tags in the configuration
  GetInventoryServiceV3	inventory data split by hidden and player visible items
  UpdateItemsPartnerV2, UpdateItemsServiceV2, and GrantItemsServiceV2	segments/deltas split by hidden and player visible items

• Game server hostname and port information can now be provided as part of the MatchReadyV1Notification.

  • Description: Previously, game servers communicated hostname and port information to game clients via ext behavior. We’ve promoted this functionality into base Pragma. Game servers can now provide hostname and port information through the MatchLifecycleService.MatchReadyV2 endpoint. However, if you’ve already implemented this functionality via ext, you can keep using that implementation indefinitely.

• Operators can now clear all inventory caches.

  • Description: Added Operator endpoint for ClearAllInventoryCacheOperatorV1Request. This already existed as a Service endpoint, and is now available for Operator.

• Partners can now get filtered Pragma account overviews.

  • Description: Added Partner endpoint for GetPragmaAccountOverviewsPartnerV1Request. This already existed as an Operator endpoint, and is now available via Partner.

• Partners can now get full inventory for a player.

  • Description: Added Partner endpoint for GetInventoryPartnerV1Request. This already existed as an Operator endpoint, and is now available via Partner.

• [Portal] The content catalog is now shown in a more readable format by default with JSON rendering of ext data.

• [Portal] Date of player account creation and last login is now shown.

• [Portal] Rendering of date and time throughout Pragma Portal is now consistent.

  • Description: Datetimes are now shown in 24h format in the browser’s timezone. On hover, the UTC datetime is shown. Example: 27 May 2022 14:34:12 (Europe/Bucharest).

Deprecations #

• Remove any references to LeaderClientVersion field.
  • Description: The LeaderClientVersion field of EnterMatchmakingV2Request RPC and MatchmakingParty Kotlin object is being removed as it is unnecessary.

    Original	Replacement	Removal Patch
    LeaderClientVersion field of EnterMatchmakingV2Request RPC and MatchmakingParty object	No replacement needed	0.0.71

• Update deletePlayerInventory endpoints to new versions to remove Progression service data.

• Update endpoints to new versions to capture Progression service removals.

  • Description: Endpoints that currently return progression-related data are being versioned to no longer include the progression data fields.

    The Inventory and Lobby service RPC calls only require integration if you’re calling them from a custom service. Pragma Engine handles all version bumps for Pragma-owned services.

Integrations #

• Create a new recreateParty function definition.

  • Description: We’ve added a new plugin flow to the PartyService which will enable handling recreated parties with custom logic.
  • Integration steps:
    • Add a new recreateParty function definition to custom implementations of PartyPlugin in order to compile.

• Replace listed InventoryRpc protos.

  • Description: We’ve completed the move from the listed protos and are now removing the old ones.
  • Integration step: Replace the listed InventoryRpc protos.

    Original	Replacement
    InstancedDelta	InstancedDeltaV2
    InventoryDeltaV1Data	InstancedDeltaV2

• Move over from the Progression service to the Inventory service.

  • Description: The Progression service is being removed.
  • Integration step: If you are currently using the Progression service, please contact us for help moving over to the Inventory service.

• Remove gatewayWorkerThreadpoolSize value in config YAML files.

  • Description: Ktor defaults create thread pools of the appropriate size, so this configuration is not needed.
  • Integration step: Remove gatewayWorkerThreadpoolSize value in config YAML files.

• Add required Maven dependency to 5-ext/ext/pom.xml.

  • Description: We’re moving Test Factory classes into the core engine to better separate the proto auto generated code steps from the rest of the engine build. In the future, generated code will be embedded directly into the engine library, rather than linked through a library dependency. This will streamline incremental builds and make the overall engine project structure simpler.

  • Integration step: Add the following Maven dependency to 5-ext/ext/pom.xml if it is not already here. If pragma.mvn.version is undefined, match whatever version you are using for other engine dependencies (eg. ${revision}, or PRAGMA-LOCAL-SNAPSHOT).

    <dependency>
        <groupId>pragma</groupId>
        <artifactId>core</artifactId>
        <version>${pragma.mvn.version}</version>
        <type>test-jar</type>
        <scope>test</scope>
    </dependency>
    

• Create a new local configuration file to continue using custom portlets.

  • Description: Custom portlets can now be loaded from any custom directory under platform/web/portal/src/portlets. If you currently have a portlets/5-ext directory with custom portlets, follow the integration steps to include them in the build.
  • Integration steps:

    • Create platform/web/portal/portalDevConfig.local.js (next to portalDevConfig.default.js).

    • Add the following contents to portalDevConfig.local.js:

      module.exports = {
          default: {
              'portlets.extraSrcDirs': ['5-ext']
          },
          deploy: {
              target: ['5-ext/portal']
          }
      }
      

• Make the following changes for project structure improvements.

  • Description: To enable the recent project structure improvements, make the following changes, which are listed by file.
  • Integration steps:

    • In 5-ext/pom.xml:

      • Remove <module>ext-protos</module> from <modules>.
      • Add <groupid>[studio_name]</groupid> above <artifactId> tag.
      • Add the following properties block:

      <properties>
        <revision>[project_name]-LOCAL-SNAPSHOT</revision>
        <company>[project_name]</company>
        <pragma.version>LOCAL</pragma.version>
        <pragma.mvn.version>PRAGMA-LOCAL-SNAPSHOT</pragma.mvn.version>
      </properties>
      

    • In 5-ext/ext/pom.xml:

      • Change <parent><groupId>pragma</groupId></parent> to <parent><groupId>[studio_name]</groupId></parent> with your studio’s name in the brackets.
      • Change the following dependency block:

      Original	Replacement
      <dependency> <groupId>pragma</groupId> <artifactId>ext-protos</artifactId> <version>${revision}</version> </dependency> <dependency> <groupId>pragma</groupId> <artifactId>ext-protos</artifactId> <version>${revision}</version> <type>test-jar</type> <scope>test</scope> </dependency>	<dependency> <groupId>[studio_name]</groupId> <artifactId>ext-protos</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>[studio_name]</groupId> <artifactId>ext-protos</artifactId> <version>${project.version}</version> <type>test-jar</type> <scope>test</scope> </dependency>

      • Change the following dependency block:

      Original	Replacement
      <dependency> <groupId>pragma</groupId> <artifactId>core</artifactId> <version>${revision}</version> </dependency>	<dependency> <groupId>pragma</groupId> <artifactId>core</artifactId> <version>${pragma.mvn.version}</version> </dependency>

    • For each of the dependencies listed, update ${revision} to ${pragma.mvn.version}. Be sure to check for and update two dependency blocks, one default, and one with <type>test-jar</type>:

      • pragma.core
      • pragma.server-base
      • pragma.social
      • pragma.game
      • pragma.game-common
      • Pragma.social-common

    • In 5-ext/ext-protos/pom.xml:

      • Make the following parent change:

      Original	Replacement
      <parent> <groupId>pragma</groupId> <artifactId>5-ext</artifactId> <version>${revision}</version> </parent>	<parent> <groupId>pragma</groupId> <artifactId>engine-settings</artifactId> <version>PRAGMA-LOCAL-SNAPSHOT</version> <relativePath>../../engine-settings.xml</relativePath> </parent>

      • Add <groupId>[studio_name]</groupId> above the <artifactId> tag.
      • Add <version>[studio_name]-LOCAL-SNAPSHOT</version> below the <artifactId> tag.
      • For each of the dependencies listed, update ${revision} to ${pragma.mvn.version}:
        • pragma.proto-defs
        • pragma.proto-defs (<type>test-jar</type>)

    • In 5-ext/ext-server/pom.xml:

      • For the pragma.server-base dependency, update ${revision} to ${pragma.mvn.version}.
      • Change <parent><groupId>pragma</groupId></parent> to <parent><groupId>[studio_name]</groupId></parent>.
      • Make the following dependency change:

      Original	Replacement
      <dependency> <groupId>pragma</groupId> <artifactId>ext</artifactId> <version>${revision}</version> </dependency>	<dependency> <groupId>[studio_name]</groupId> <artifactId>ext</artifactId> <version>${project.version}</version> </dependency>

Bugs and Fixes #

• SDK RefreshToken flows now run at appropriate intervals.
  • Description: Authentication token intervals were previously dependent on clients’ clocks, leading to incorrect refresh intervals when clocks were incorrect. Token refresh intervals are now independent of player clocks.
• Searching for display names containing the # (number sign) character now works properly.

May 24th, 2022

Features #

• New Party service endpoint makes it possible for parties to be joined directly by party ID.
  • Description: New Party Service endpoint available at JoinWithPartyIdV1. You can use this to write automated party invite flows in your UI.
• You can now validate cross-content IDs under ext fields.
  • Description: We’ve added a way to validate cross-content IDs under ext fields. All content validation occurs when you run the contentdata apply command and on startup. If any invalid content is found, you should get an error message letting you know which content object has a problem.
• Portal: Full Access List now available.
  • Description: Operators can now create a full access list for players, such as friends and family. This can be managed in the Game Title Management section, at the bottom of the Shard page.
• Portal: Ability to delete player groups added.
  • Description: Operators can now delete player groups. To delete a player group, select the group name on the Groups page, click the Edit Details button at the top right of the page, and click the red Delete group button.

Deprecations #

• Replace listed InventoryRpc protos by release 0.0.70.

  Original	Replacement	Removal Patch
  InstancedDelta	InstancedDeltaV2	0.0.70
  InventoryDeltaV1Data	InstancedDeltaV2	0.0.70

Integrations #

• Update custom MatchEndBuilders to MatchEndV2 to support hidden inventory.
  • Description: To support hidden inventory, we’ve updated the Inventory service MatchEnd endpoint and InventoryMatchEndBuilder. You will need to update custom MatchEndBuilders to look for the new MatchEndV2Response.
  • The contents of the MatchEnd response have also changed. If you currently inspect the UpdateSummaries that come back from InventoryService in custom MatchEndBuilder, the new response contains a ServiceUpdateSummary, which is composed of two UpdateSummary objects.
  • Until you start using hidden inventory, the player UpdateSummary field is equivalent to what was there before.
  • Integration steps:
    • If you have custom MatchEndBuilders inspecting context, you will need to update what they look for:

      Original	Replacement
      InventoryRpc.MatchEndV1Response::class	InventoryRpc.MatchEndV2Response::class

• Update references to the Party plugin’s PartyPlayer inventory field.
  • Description: The Party plugin’s PartyPlayer inventory field has a new type. This new class contains two InventoryDatas with content split using the new hidden inventory system.
  • Integration steps:
    • Update references using inventory and underlying fields on a PartyPlayer. Until hidden inventory is configured, use the player InventoryData object as the equivalent of the old inventory field.

      Original	Replacement
      InventoryFullV1Data	ServiceInventoryData

Docs #

• [New Category] Starter Kit documentation has been added.
• [Updated Services Guide] JoinWithPartyIdV1 added to Party Services Guide.

May 17th, 2022

Features #

• New Party service is now live!
  • Description: The new Party service is now available, and recommended for use instead of the old Lobby service.
• Account discriminators are now randomly generated instead of sequentially assigned.
  • Description: Accounts would previously receive sequentially-assigned discriminators. For example, the first account named Alice would be Alice#0001 and the second would be Alice#0002. The discriminator is now randomly assigned.

Deprecations #

• Move over from the Progression service to the Inventory service.
  • Description: The Progression service will be fully removed in 0.0.70. If you are currently using the Progression service, please contact us for help moving over to the Inventory service.

Integrations #

• Move and rename Party service protos.
  • Description: Some ext protos have been moved and renamed in preparation for Party service release.
  • Integration steps:
    • In the /platform/5-ext/ext-protos/src/main/proto/shared/ directory:
      • Delete partyExt.proto.
      • In the partyRpcExt.proto file, create the following protos. Remove the import relating to partyExt.proto if found.

// ext field for party state
message ExtPartySelections {
}
// ext field for player selection state within a party
message ExtPlayerSelections {
}
// ext field for private player selection state within a party
message ExtPrivatePlayerSelections {
}
// request ext field for creating a party
message ExtCreateRequest {
}
// request ext field for adding a player to a party
message ExtPlayerJoinRequest {
}
// request ext field for updating a player selection
message ExtUpdatePlayerSelectionsRequest {
}
// request ext field for updating a party selection
message ExtUpdatePartySelectionsRequest {
}

• Use InventoryService.MatchEndV1 instead of InventoryService.MatchEndV0.
  • Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to MatchLifecycleService.matchEndV3.
  • Integration step:
    • Make the following changes: InventoryRpc protos:

      Original	Replacement
      MatchEndV0Request	MatchEndV1Request
      MatchEndV0Response	MatchEndV1Response
      Inventory RPC service route:
      Original	Replacement
      ———–	——————
      matchEndV0	matchEndV1

Bugs and Fixes #

• Pragma Portal: Searching by Discord Account ID has been fixed.

Docs: #

• [Feature] Basic task steps are now nested under “Quick Guides” headers on relevant Services guides.
• [Updated Services Guide] The Party Services Guide has been updated with the new Party service details, including quick guides on basic tasks.

May 10th, 2022

Features #

• Cross-content validation for Inventory Service content available.

  • Description: Inventory Service Content now has additional validation across content types, which is performed during the ContentData apply command.

  For example, a StoreEntry might reference other content by CatalogId via its receivedQuantityByCatalogId or costByCatalogId fields. These CatalogIds are now checked during ContentData apply to ensure that they refer to valid inventory entries.

  This validation can be added to your own custom content by implementing the ContentData<*>.validateWithAllContent(contentByType: mapOf<String, ContentData<*>>) function on the ContentHandler.

  Note that this initial rollout of cross-content validation does not validate anything nested under an ext message.

• Upgraded Portal now live!

  • Description: The Portal has been upgraded to be faster and more modular. It can be found at platform/web/portal. If you don’t have custom modules, the Portal is backwards compatible, and can still be found at platform/web/portal-base.

  View the README_PORTAL.md file in platform/web for more information about the new Portal.

  • Related note: Integration may be required. View the related integration note below.

Integrations #

• Update Portal build directory and update custom modules if necessary.
  • Description: The new Portal is now available at platform/web/portal. If you don’t have custom modules, the Portal is backwards compatible, and can still be found at platform/web/portal-base. If you do have custom modules, you’ll need to follow the integration steps.
  • Integration steps:
    • You may need to update the build directory if you have a custom build step.
    • Custom Portal modules may need to be individually integrated. Contact us if you have custom Portal development and have not yet received help with integration.
  • Related note: see feature announcement for more information on the new Portal.
• Update the ContentDataProxy class primary constructor if necessary.
  • Description: The kClass param has been removed from the ContentDataProxy class’s primary constructor.
  • Integration steps:
    • If you are using this class with custom content, you will need to remove the kClass param as shown below. No action is required otherwise.

class ContentDataProxy<ContentProto : GeneratedMessageV3>(
    private val kClass: KClass<ContentProto>,
    private val resourcePath: String,
) : ContentData<ContentProto>

class ContentDataProxy<ContentProto : GeneratedMessageV3>(
      private val resourcePath: String,
) : ContentData<ContentProto>

• Rename InMemSocialIT.yml and InMemGameIT.yml.
  • Description: Certain files have been renamed due to the removal of the in-memory database driver.
  • Integration steps:
    • The Makefile has been updated to copy InMemSocialIT.yml and InMemGameIT.yml over. If you are using a custom Makefile, please update it.
    • Merge the contents of your existing InMemSocialIT.yml and InMemGameIT.yml files into the new files.

• Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.
  • Description: TokenUtils::createPragmaJWT has been replaced by PragmaJwtSigner.
  • Integration steps:
    • Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.

• Update the Makefile to reflect changes to the relevant gen-sdk-types-<ENGINE> targets.
  • Description: The SDK type generation targets have been fixed to also build Pragma protos.
  • Integration steps:
    • If you have your own copy of the Makefile, ensure that the relevant gen-sdk-types-<ENGINE> also depends on the protos step.

Bugs and Fixes #

• Pragma Platform console output during startup has been cleaned up.
  • Description:
    • PragmaNode config output during startup was previously too verbose, making it difficult to see the most relevant information. However, if the PragmaNode fails to start and the entire config object has been loaded, it will be printed out to assist with troubleshooting.
    • The config can be viewed via the SystemReporterNodeServicePB.GetConfigV1Request RPC.
• Portal display name searches now handle the underscore _ and percent % characters properly.
• Fixed BackgroundableTicker warnings and strict Include-What-You-Use (IWYU) compilation in Unreal 5.

Docs #

• [Updated Getting Started Guide] Details added to Understanding Pragma Engine.
• [Updated Getting Started Guide] Initial Setup guide rewritten.

May 3rd, 2022

Features #

• The Unity SDK now logs debug details from service errors.
  • Description: Developers can now view service errors in the Unity Editor console.
• Match reconnect now available.
  • Description: Match reconnect is now available using the Party system and can be used by players to rejoin in-progress matches.

Deprecations #

• /v1/info endpoint connection fields are being renamed.

  • Description: The scheme and wsScheme fields in the <protocol>://<host>:<port>/v1/info endpoint are being deprecated, and will be replaced with protocol and webSocketProtocol.

    Original	Replacement	Removal Patch
    scheme	protocol	0.0.68
    wsScheme	webSocketProtocol	0.0.68

• Inventory MatchEndV0 RPC and protos are being renamed to MatchEndV1.

  • Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to MatchLifecycleService.matchEndV3.
  • InventoryRpc protos:

    Original	Replacement	Removal Patch
    MatchEndV0Request	MatchEndV1Request	0.0.68
    MatchEndV0Response	MatchEndV1Response	0.0.68

  • Inventory RPC service route:

    Original	Replacement	Removal Patch
    matchEndV0	matchEndV1	0.0.68

Integrations #

• Change from MariaDB to MySQL.
  • Description: Beginning in release 0.0.66, Pragma Engine will no longer have an in-memory option for databases. Your platform and infrastructure will not load until you have completed this change. All data that is not migrated to MySQL will be lost.
  • Integration step: A guide has been provided for affected customers. Follow the guide for instructions for both local and non-local environments.
• Update partnerConnectionInfo config in configuration YAML files.
  • Description: The url config property is being deprecated. Provide the appropriate values for the host, port, and protocol fields instead. Note that protocol defaults to http in development mode, but a protocol must be specified in production mode in order for the platform to successfully start up.
  • Integration step: Update partnerConnectionInfo config as specified below.

partnerConnectionInfo:
  url: "http://localhost"
  host: "localhost"
  port: 10106

partnerConnectionInfo:
  protocol: "http"
  host: "localhost"
  port: 10106

• Update InstancedItemPlugin code that uses UpdateResult.
  • Description: instancedItemGrants has been renamed to instancedItemServerGrants.
  • Integration steps: Update all plugins that return a InstancedItemPlugin.UpdateResult by renaming instancedItemGrants to instancedItemServerGrants.

return InstancedItemPlugin.UpdateResult(
  extInstancedItem
  instancedItemGrants
  stackableItemGrants
)

return InstancedItemPlugin.UpdateResult(
  extInstancedItem
  instancedItemServerGrants
  stackableItemGrants
)

• Change ContentDataNodeService.getHandler method.
  • Description: The ContentDataNodeService.getHandler method with kclass parameter has been removed, and you’ll need to confirm you’re using the recommended, functional method.
  • Integration step: Use the ContentDataNodeService.getHandler method without the kclass parameter.

fun <ContentProto : GeneratedMessageV3> getHandler(
  kClass: KClass<ContentProto>,
  resourcePath: String
): ContentData<ContentProto>

fun <ContentProto : GeneratedMessageV3> getHandler(
  resourcePath: String
): ContentData<ContentProto>

• Update the following functions as mentioned in release 0.0.64.

  • Description: Session and WebSocket cleanup changes.
  • Integration step: Make the following changes:

    Original	Replacement
    JumpData::longClassNameToShortName()	ProtoUtils.protoShortName()
    TokenUtils.createPragmaJWT	use PragmaJwtSigner methods

• Update server configuration for listed gateway config fields.

  • Description: Update server configuration for the following gateway config fields.
  • Integration step: SocialOperatorGatewayConfig, SocialPlayerGatewayConfig, SocialPartnerGatewayConfig, GameOperatorGatewayConfig, GamePlayerGatewayConfig, GamePartnerGatewayConfig

    Original	Replacement
    schema	protocol
    wsSchema	webSocketProtocol

Bugs and Fixes #

• Pragma Portal now properly excludes players who are already a member of a group from being shown in the Add Accounts to Player Group page for that group.

Docs #

• [New Services Guide] Match reconnect added.
• [Updated Services Guide] Details added to Play Again section.

April 26th, 2022

Features #

• Added a new way to track account creation and most recent login.
  • Description: Unix timestamps for account creation and most recent login have been added to the Social table. Fields have been added to all existing endpoints that use the SocialIdentityWithPersonal proto message.
  • Postman paths:
    • Social → RPC - Operator → Account → ViewSocialIdentitiesV1Response
    • Social → RPC - Operator → Account → ViewSocialIdentityV1Response
    • Social → RPC - Partner → ViewSocialIdentityPartnerV2Response