Pragma Engine 0.0.73 #

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.
      OriginalReplacement
      launchscope.launch
      asyncscope.async
      coroutineContextscope.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.
      OriginalReplacement
      MatchProcessedV2NotificationMatchProcessedV3Notification
  • 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.
      OriginalReplacement
      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.
      OriginalReplacement
      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.

Pragma Engine 0.0.72 #

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.
        OriginalReplacementRemoval Patch
        GameDataStrategyPluginLoginDataPlugin0.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:
      OriginalReplacement
      MatchEndPlugin.getMatchEndBuildersMatchEndPlugin.getMatchEndJobs
      MatchEndContextDependentJobContext
      ConcurrentNotificationBuilderThreadsafeMutable
      MatchEndBuilderMatchEndDependentJob
      • 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:
      OriginalReplacement

      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:
      OriginalReplacement

      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:
      OriginalReplacement

      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:
      OriginalReplacement

      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.
      OriginalReplacement
      PragmaResult<IdProviderAccount, PragmaError> containing an IdProviderAccountIdProviderAccount
      PragmaResult<IdProviderAccount, PragmaError> containing a PragmaErrorThrow 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:
      OriginalReplacement
      UpdateLoadoutV1UpdatePlayerSelectionsV1
      CanUpdateLoadoutV1CanUpdatePlayerSelectionsV1

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.

Pragma Engine 0.0.71 #

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.
    OriginalReplacementRemoval Patch
    InventoryRpc.UpdateItemsPartnerV1InventoryRpc.UpdateItemsPartnerV20.0.73
    InventoryRpc.UpdateItemsServiceV1InventoryRpc.UpdateItemsServiceV20.0.73
    InventoryRpc.ServiceGetInventoryV1InventoryRpc.ServiceGetInventoryV20.0.73
    InventoryRpc.GrantItemsServiceV1InventoryRpc.GrantItemsServiceV20.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.
    OriginalReplacementRemoval Patch
    Unity: OnMatchProcessedV2NotificationUnity: OnMatchProcessedV3Notification0.0.73
    Unreal: OnMatchProcessedV2Unreal: OnMatchProcessedV30.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.
      OriginalReplacement
      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 #

Pragma Engine 0.0.70 #

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 callDescription
    craftV1, storePurchaseV4, updateItemV4, and updateItemsV0returned segments/deltas won’t contain items with tags that match the configuration
    getStoresV0return stores will not contain store entries with tags that match the configuration
    getInventoryV2returned inventory will not contain instanced and stackables whose corresponding content specs contain tags that match the configuration
    GameDataService.GetLoginDataV1 which uses InventoryService.GetLoginDatareturned player inventory and content items (stores, update entries, item catalog, crafting entries, etc) are all filtered based on the tags in the configuration
    GetInventoryServiceV3inventory data split by hidden and player visible items
    UpdateItemsPartnerV2, UpdateItemsServiceV2, and GrantItemsServiceV2segments/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.
      OriginalReplacementRemoval Patch
      LeaderClientVersion field of EnterMatchmakingV2Request RPC and MatchmakingParty objectNo replacement needed0.0.71
  • Update deletePlayerInventory endpoints to new versions to remove Progression service data.
OriginalReplacementRemoval Patch

InventoryService.deletePlayerInventoryV1

  • InventoryRpc.DeletePlayerInventoryV1Request
  • InventoryRpc.DeletePlayerInventoryV1Response

InventoryService.deletePlayerInventoryV2

  • InventoryRpc.DeletePlayerInventoryV2Request
  • InventoryRpc.DeletePlayerInventoryV2Response
0.0.71
  • 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.

OriginalReplacementRemoval Patch

InventoryService.matchEndV2

  • InventoryRpc.MatchEndV2Request
  • InventoryRpc.MatchEndV2Response

InventoryService.matchEndV4

  • InventoryRpc.MatchEndV4Request
  • InventoryRpc.MatchEndV4Response
0.0.72

LobbyService.lockV1

  • LobbyRpc.LockV1Request
  • LobbyRpc.LockV1Response

LobbyService.lockV2

  • LobbyRpc.LockV2Request
  • LobbyRpc.LockV2Response
0.0.72

MatchLifecycleService.matchEndV3

  • MatchLifecycleRpc.MatchEndV3Request
  • MatchLifecycleRpc.MatchEndV3Response

MatchLifecycleService.matchEndV4

  • MatchLifecycleRpc.MatchEndV4Request
  • MatchLifecycleRpc.MatchEndV4Response
0.0.72

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.
      OriginalReplacement
      InstancedDeltaInstancedDeltaV2
      InventoryDeltaV1DataInstancedDeltaV2
  • 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:
        OriginalReplacement
        <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:
        OriginalReplacement
        <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:
        OriginalReplacement
        <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:
        OriginalReplacement
        <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.

Pragma Engine 0.0.69 #

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.
    OriginalReplacementRemoval Patch
    InstancedDeltaInstancedDeltaV20.0.70
    InventoryDeltaV1DataInstancedDeltaV20.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:
        OriginalReplacement
        InventoryRpc.MatchEndV1Response::classInventoryRpc.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.
        OriginalReplacement
        InventoryFullV1DataServiceInventoryData

Docs #

Pragma Engine 0.0.68 #

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:
        OriginalReplacement
        MatchEndV0RequestMatchEndV1Request
        MatchEndV0ResponseMatchEndV1Response
        Inventory RPC service route:
        OriginalReplacement
        ———–——————
        matchEndV0matchEndV1

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.

Pragma Engine 0.0.67 #

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.
OriginalReplacement
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.
OriginalReplacement
ext/src/test/resources/localDevelopmentShardConfig/InMemSocialIT.ymlext/src/test/resources/localDevelopmentShardConfig/SocialIT.yml
ext/src/test/resources/localDevelopmentShardConfig/InMemGameIT.ymlext/src/test/resources/localDevelopmentShardConfig/GameIT.yml
  • Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.
    • Description: TokenUtils::createPragmaJWT has been replaced by PragmaJwtSigner.
    • Integration steps:
      • Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.
OriginalReplacement
TokenUtils::createPragmaJWTPragmaJwtSigner
  • 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.
OriginalReplacement
gen-sdk-types-unreal4: ext-protosgen-sdk-types-unreal4: protos ext-protos

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 #

Pragma Engine 0.0.66 #

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.
      OriginalReplacementRemoval Patch
      schemeprotocol0.0.68
      wsSchemewebSocketProtocol0.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:
      OriginalReplacementRemoval Patch
      MatchEndV0RequestMatchEndV1Request0.0.68
      MatchEndV0ResponseMatchEndV1Response0.0.68
    • Inventory RPC service route:
      OriginalReplacementRemoval Patch
      matchEndV0matchEndV10.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.
OriginalReplacement
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.
OriginalReplacement
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.
OriginalReplacement
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:
      OriginalReplacement
      JumpData::longClassNameToShortName()ProtoUtils.protoShortName()
      TokenUtils.createPragmaJWTuse 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
      OriginalReplacement
      schemaprotocol
      wsSchemawebSocketProtocol

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 #

Pragma Engine 0.0.65 #

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

Integrations #

  • Upgrade to IntelliJ 2022 and Kotlin 1.6 plugin.
    • Description: To keep up with updates in developer tooling, we’re upgrading to IntelliJ 2022. The latest version of IntelliJ is bundled with the correct plugin version. Note that this plugin is not supported by the previously recommended version of IntelliJ (2021.2.1).
    • Integration step: Update to IntelliJ 2022 and the version of the Kotlin plugin used by Intellij to v1.6.2 or greater.
  • Replace references to ClearPlayerInventoryCacheV1 with DeletePlayerInventoryV1.
    • Description: We’ve deprecated ClearPlayerInventoryCacheV1.
    • Integration step: Use DeletePlayerInventoryV1 instead of ClearPlayerInventoryCacheV1.
      OriginalReplacement
      ClearPlayerInventoryCacheV1DeletePlayerInventoryV1
  • Move MatchLifecycleService configurations from serviceConfigs to pluginConfigs.
    • Description: MatchLifecycleService strategy configuration has been moved, as mentioned in release 0.0.61.
    • Integration step: Move MatchLifecycleService configs.
OriginalReplacement
serviceConfigs:
MatchLifecycleServiceConfig:
   matchFoundBuilderStrategy: "CustomMatchFoundBuilderClass"
   notifyMatchAllocatedStrategy: "CustomNotifyMatchAllocatedClass"
pluginConfigs:
MatchLifecycleService.matchFoundBuilderPlugin:
  class: "CustomMatchFoundBuilderClass"
MatchLifecycleService.notifyMatchAllocatedPlugin:
  class: "CustomNotifyMatchAllocatedClass"
  • Update MatchLifecycleService strategy class signatures on custom ext implementations.
    • Description: The matchFoundBuilderStrategy and notifyMatchAllocatedStrategy fields are being deprecated in favor of plugins.
    • Integration steps:
      • Update ext implementations to use MatchFoundBuilderPlugin and NotifyMatchAllocatedPlugin interfaces instead.
      • Update primary constructor to required plugin signature.
      OriginalReplacement
      class CustomMatchFoundBuilderClass : MatchFoundBuilderStrategy 
      
      class CustomNotifyMatchAllocatedClass : NotifyMatchAllocatedStrategy
      
      class CustomMatchFoundBuilderClass(service: Service, contentDataNodeService: ContentDataNodeService) : MatchFoundBuilderPlugin
      
      class CustomNotifyMatchAllocatedClass(service: Service, contentDataNodeService: ContentDataNodeService) : NotifyMatchAllocatedPlugin
      

      Bugs and Fixes #

      • Unreal SDK: Fixed a crash caused by logic in a destructor calling response delegates after their targets were already destructed.

Pragma Engine 0.0.64 #

April 19th, 2022

Features #

  • Unity SDK: New method allows a game server to directly report match capacity data to Pragma Engine.
    • Description: The new method ReportCapacityUntilMatchAllocated on MatchCapacityService handles reporting into Pragma Engine until a match is available. Once a match is found, it returns the associated match data.
  • Unreal SDK: You can now initialize Pragma without access to a World.
    • Description: PragmaSession no longer requires access to a World.
  • Unreal SDK: Internal SDK timers now sync to game tick to guarantee they persist across World transitions.
    • Description: All timers are based on engine game tick instead of World timers to ensure they persist across levels.
  • New endpoints for updating inventory items.
    • Description: Items can be updated given a playerID and a list of ServerItemUpdateV2. This list is a oneof including either a ServerInstancedItemUpdate or a StackableItemUpdate. This will return an InventorySegmentV1Data, which contains the updated item and a delta of changes. The Service call is UpdateItemsServiceV1.
    • Postman paths:
      • Game → RPC - Operator → Inventory → UpdateItemsOperatorV1
      • Game → RPC - Partner → Inventory → UpdateItemsPartnerV1

Deprecations #

  • UnpartitionedDaoNodeService and PartitionedDaoNodeService will now use executeSingle (single interaction) and transact (multiple statements).

    OriginalReplacementRemoval Patch
    executeexecuteSingle0.0.66
    executeTransactiontransact0.0.66
  • Session and WebSocket cleanup changes.

    OriginalReplacementRemoval Patch
    JumpData::longClassNameToShortName()ProtoUtils.protoShortName()0.0.66
    TokenUtils.createPragmaJWTuse PragmaJwtSigner methods0.0.66

Integrations #

  • Replace old PragmaClient methods.
    • Description: Several methods have been replaced as part of a WebSocket lifecycle code cleanup.
    • Integration steps: Refer to the following table. If you’ a’re using any method listed in the “Original” column, replace it with the corresponding method listed in the “Replacement” column.
      OriginalReplacement
      gameConnection.pragmaIdplayerId
      socialConnection.pragmaIdsocialId
      fun isConnectedToGame(): BooleangameConnection.isConnected()
      fun isConnectedToSocial(): BooleansocialConnection.isConnected()
      suspend fun logoutFromGame(notifyBackend: Boolean = true)gameConnection.stop()
      suspend fun logoutFromBoth(notifyBackend: Boolean = true)stopBoth()
  • Update implementations of EmailSenderPlugin to match the new signature.
    • Description: The return type of the EmailSenderPlugin has been changed. This is part of an effort to simplify and clean up our plugin interfaces.
    • Integration steps: Update any implementations of EmailSenderPlugin to throw an exception instead of returning a PragmaError.
OriginalReplacement
suspend fun sendVerificationEmail(recipient: String, verificationEmailEndpoint: String, uniqueCode: String): PragmaResult<EmailMessageSent, PragmaError>
suspend fun sendVerificationEmail(recipient: String, verificationEmailEndpoint: String, uniqueCode: String): EmailMessageSent
  • Use new ViewSocialIdentityPartnerV2Request service call.
    • Description: ViewSocialIdentityPartnerV1Request has been removed in favor of ViewSocialIdentityPartnerV2Request.
    • Integration steps:
      • Replace all instances of ViewSocialIdentityPartnerV1Request with ViewSocialIdentityPartnerV2Request.
OriginalReplacement
ViewSocialIdentityPartnerV1RequestViewSocialIdentityPartnerV2Request

Bugs and Fixes #

  • Unreal SDK: Fixed a bug where the Connection state would not return to Connected after being Degraded.

Docs #

  • [Feature] “Core Concepts” added to User Guides.
    • Description: New “Core Concepts” callouts on User Guides contain links to relevant Services guides. This should redirect beginner users to the appropriate service overview page before beginning the hyperspecific tutorial.
  • [Bug] Missing Match End services content has been readded.
  • [New User Guide] Unreal SDK: Authenticating with Steam added.
  • [New User Guide] Limited Grants added.

Pragma Engine 0.0.63 #

April 12th, 2022

Features #

  • The Unreal SDK can now recognize when a connection is degraded/recovered and surface that information to users.
    • Description: The Unreal SDK now fires Connection::OnDegraded when one or both websockets are having connection trouble, and Connection::OnRecovered when they are fully connected again.
  • You can now delete instancedItems via Operator, Partner, or Service gateways.
    • Description: Items will be destroyed when this endpoint is given a playerID and an ItemServerDestroyV1 list. This list is a oneof InstancedItemServerDestroy, which is an instance ID. Please note the Operator endpoint will be added to Postman with the next release.
    • InventoryRpc endpoints::
      • DestroyItemsPartnerV1
      • DestroyItemsOperatorV1
      • DestroyItemsServiceV1
  • Telemetry service is now live!
    • Description: You can now send arbitrary telemetry events from the game client, game server, plugins, and custom services. This service provides a realtime event pipeline that persists events to various terminating data stores or data lakes. Currently supports MySQL/MariaDB collectors, and other collectors can be implemented with the TelemetryPlugin.

Bugs and Fixes #

  • Makefile now supports user paths with spaces.
  • The Unreal & Unity SDKs now reset the lobby state when a connection is degraded.
    • Description: The SDK Lobby Service now resets the lobby state OnDegraded to keep client and platform states in sync.
  • Pragma Portal: Issue with searching by account provider ID has been resolved.

Pragma Engine 0.0.62 #

April 5th, 2022

Features #

  • ExtException now supports an optional message.
    • Description: When authoring plugin content and choosing to throw a custom error using ExtException, you can now also pass an optional explanatory string message providing additional detail.
  • Send players one-time content drops with the new Limited Grant system.
    • Description: You can now create a content file that grants players a drop of content when they log in (this does not grant multiple drop on multiple logins). This system supports instanced items, stackable items, and rewards.
    • Steps to enable:
      • Create the new LimitedGrant content files by running make ext or make build from the command line.
    • Unreal SDK: On shutdown, dangling response handlers are called with errors.
      • Description: When shutting down a Pragma Session, the Unreal SDK looks for any response handlers that have not yet been called, and calls them with EPragma_SdkError::ProtocolShuttingDown.

Deprecations #

  • ViewSocialIdentityPartnerV1Request is being deprecated in favor of ViewSocialIdentityPartnerV2Request.
    OriginalReplacementRemoval Patch
    ViewSocialIdentityPartnerV1RequestViewSocialIdentityPartnerV2Request0.0.64

Integrations #

  • Rewrite your configuration files (e.g. LocalConfig.yml or CommonConfig.yml) to specify plugins by their fully qualified path.
    • Description: All configuration of strategies and plugins must use a fully qualified name (JVM name) instead of a simple name. Previously either were accepted.
OriginalReplacement
pluginConfigs:
GameDataService.gameDataStrategyPlugin:
  class: "DefaultPragmaGameDataStrategyPlugin"
pluginConfigs:
GameDataService.gameDataStrategyPlugin:
  class: "pragma.gamedata.DefaultPragmaGameDataStrategyPlugin"

Bugs and Fixes #

  • Player Groups are now associated with socialId instead of accountId.
    • Description: accountIDs are intended to be used for Personally Identifiable Information (PII). As Player Group data is not PII, it is now being kept in association with a player’s socialId. This is a purely behind-the-scenes change and should not cause any visible effects.

Pragma Engine 0.0.61 #

March 29nd, 2022

Features #

  • New endpoint for deleting a player group.
    • Description: We’ve added a new RPC endpoint for deleting a player group. The payload requires a playerGroupId.
    • Postman Path:
      • Social → RPC - Operator → Account → RemovePlayerGroupOperatorV1
  • ID Provider information updated on login.
    • Description: When users sign in via an identity provider, the platform updates the provider username to match the service username. This means that users will have up-to-date Discord/Epic/Steam username information based on the last time they logged in.
  • Player tags are now associated with social ID instead of account ID.
    • Description: Tags were previously linked to a player’s account ID, which is where content like PII are kept. As tags are not PII, they are now linked directly with the social ID.

Deprecations #

  • MatchLifecycleService strategy configuration has been moved. Configurations must be moved from serviceConfigs to pluginConfigs by patch 0.0.63.
OriginalReplacementRemoval Patch
serviceConfigs:
MatchLifecycleServiceConfig:
   matchFoundBuilderStrategy: "CustomMatchFoundBuilderClass"
   notifyMatchAllocatedStrategy: "CustomNotifyMatchAllocatedClass"
pluginConfigs:
MatchLifecycleService.matchFoundBuilderPlugin:
  class: "CustomMatchFoundBuilderClass"
MatchLifecycleService.notifyMatchAllocatedPlugin:
  class: "CustomNotifyMatchAllocatedClass"
0.0.63

Integrations #

  • Update MatchLifecycleService strategy class signatures on custom ext implementations.
    • Description: The matchFoundBuilderStrategy and notifyMatchAllocatedStrategy fields are being deprecated in favor of plugins.
    • Integration steps:
      • Update ext implementations to use MatchFoundBuilderPlugin and NotifyMatchAllocatedPlugin interfaces instead.
      • Update primary constructor to required plugin signature.
OriginalReplacement
class CustomMatchFoundBuilderClass : MatchFoundBuilderStrategy 

class CustomNotifyMatchAllocatedClass : NotifyMatchAllocatedStrategy
class CustomMatchFoundBuilderClass(service: Service, contentDataNodeService: ContentDataNodeService) : MatchFoundBuilderPlugin

class CustomNotifyMatchAllocatedClass(service: Service, contentDataNodeService: ContentDataNodeService) : NotifyMatchAllocatedPlugin

Bugs and Fixes #

  • Updated PragmaPartnerTokens to contain empty UUIDs.
    • Description: These tokens will have empty UUIDs for their player ID, social ID, and game shard ID fields. They will also no longer have warn messages prompting users to recreate the token when they do not have a game shard ID.

Pragma Engine 0.0.60 #

March 22nd, 2022

Features: #

  • Social IDs are now sent to game servers.
    • Description: Player’s social IDs are now sent to game servers. Additionally, social IDs are now included with all PragmaSessionKeys, making them easily available to plugins.
  • Added OpenTelemetry as a replacement for Jaeger.
    • Description: As Jaeger is being deprecated, we’ve added OpenTelemetry as a replacement. We currently have some auto-instrumentation along with manual spans around RPC and database operations.
      • Note: OpenTelemetry is still being integrated and support for running it alongside custom extensions will arrive in a future patch.
    • Steps to enable:
      • Ensure Jaeger is running in Docker. See the instructions in the readme here: devenv/docker-compose-devenv/README.md
      • Start Pragma with the run-demo-with-otel make target.
      • Spans can be viewed locally through Jaeger at http://localhost:16686/search
        • Search for the local-pragma service.
        • Search by Operation: HTTP POST, WebSocketSession.inboundWorker
    • Token refreshes in the Pragma SDKs now trigger an SDK event when successful.
      • Description: Developers can take advantage of a new SDK event when client tokens successfully refresh. Add a handler for OnTokenRefreshCompleted, which provides two strings as parameters: the first is the refreshed social token, and the second is the refreshed game token.

Integrations #

  • Confirm you’ve replaced AddAccountsToPlayerGroupOperatorV1 with BulkActionOperatorV1.
    • Description: We replaced AddAccountsToPlayerGroupOperatorV1 with BulkActionOperatorV1 several patches ago. The code has now been fully removed.
      OriginalReplacement
      AddAccountsToPlayerGroupOperatorV1BulkActionOperatorV1

Bugs and Fixes #

  • Fixed compilation errors and warnings in preview builds of Unreal Engine 5.

Pragma Engine 0.0.59 #

March 15th, 2022

  • Required Integrations:
    • Make sure you’ve switched to the new content system. If you haven’t, follow the integration steps listed.
    • Replace LongRangeProxy with RandomProxy.
    • Use the new getHandler, as the old one has been deprecated along with the old content system.
    • Add ExtUpdatePartyRequest message to partyRpcExt.proto to successfully build.
    • Replace Makefile line to remove duplication and clean up old scripts.
    • Replace the listed files in your 5-ext folder with the linked templates to clean up old code.

Integrations: #

  • Make sure you’ve switched to the new content system. If you haven’t, follow the integration steps listed.
    • Description: The legacy content system has now been removed, so you must be using the new content system. If your content files are located in 5-ext/content/shared, you’re using the old content system. If they’re located in 5-ext/content/src, you’re on the new system.
    • Integration step:
      • Move your content into 5-ext/content/src. Note the JSON format has also changed as content is now authored as a JavaScript array of objects.
  • Replace LongRangeProxy with RandomProxy.
    • Description: LongRangeProxy has been deleted.
    • Integration step:
      • Replace the following:
        OriginalReplacement
        LongRangeProxyRandomProxy
    • Details:
      • See 2-pragma/core/src/main/kotlin/pragma/utils/RandomProxy.kt for implementation details.
      • See 2-pragma/core/src/test/kotlin/pragma/utils/RandomProxyTest.kt for example usages.
  • Use the new getHandler, as the old one has been deprecated along with the old content system.
    • Description: ContentDataNodeService.getHandler(kClass: KClass<ContentProto>, resourcePath: String) has been removed.
    • Integration step:
      • Use ContentDataNodeService.getHandler(resourcePath: String) instead.
        OriginalReplacement
        ContentDataNodeService.getHandler(kClass: KClass<ContentProto>, resourcePath: String)ContentDataNodeService.getHandler(resourcePath: String)
  • Add ExtUpdatePartyRequest message to partyRpcExt.proto to successfully build.
    • Description: To support Party feature development, you must define the following message in the partyRpcExt proto.

    • Integration step:

      • Paste the following into partyRpcExt.proto:
      message ExtUpdatePartyRequest {
      }
      
    • Reference: 5-ext/ext-protos/src/main/shared/protos/partyRpcExt.proto

  • Replace Makefile line to remove duplication and clean up old scripts.
    • Description: Cleaning up and fixing old scripts.
    • Integration step: Replace the following line in the Makefile.
  • Replace the listed files in your 5-ext folder with the linked templates to clean up old code.
    • Description: The 5-ext/**/pom.xml files have been simplified by refactoring and removing duplication.
    • Integration steps: Replace the following files in your 5-ext folder with the related templates:
      • 5-ext/pom.xml
      • 5-ext/ext-protos/pom.xml
      • 5-ext/ext/pom.xml
      • 5-ext/ext-server/pom.xml

Pragma Engine 0.0.58 #

March 8th, 2022

  • Endpoints that use the Player Search Filter have new filters.
  • Added GetMatchmakingInfoV1 endpoint to allow players to query the size of the matchmaking queue.
  • InstancedItemPlugin.Update can now return instanced and stackable item grants.
  • Deprecations:
    • LeaveMatchmakingV1 has been updated to V2.
    • Rewrite your configuration files (e.g. LocalConfig.yml or CommonConfig.yml) to specify plugins by their fully qualified path
  • Required Integrations:
    • Reimplement plugins that implement BulkActionPlugin as suspend methods.
    • Create a new proto file partyRpcExt.proto to successfully build your Pragma extension.
  • Bugs and fixes:
    • Encryption on email table has been removed to allow for built-in encryption by the database provider.
    • Default authentication ports for config files have been fixed to ensure Player, Operator, and Partner flows are separate.
    • Fix for Unity SDK when accessing inventory payloads before checking for response success.

Features:

  • Endpoints that use the Player Search Filter have new filters.
    • Description: We’ve added two new filters to Player Search–accounts can now be filtered by Pragma Full Display Name and Identity Provider Display Name.
    • Postman Paths:
      • Social → RPC - Operator → Account → BulkAccountOperatorV1
      • Social → RPC - Operator → Account → GetPragmaAccountOverviewsOperatorV1
      • Social → RPC - Operator → Account → AddAccountsToPlayerGroupOperatorV1
  • Added GetMatchmakingInfoV1 endpoint to allow players to query the size of the matchmaking queue.
    • Description: There is a new config option within Matchmaking, enableGetMatchmakingInfo which must be set to true for the endpoint to function. It is set to false by default.
    • Postman Paths: Game → RPC - Player → Matchmaking → GetMatchmakingInfoV1
    • Steps to Enable: Ensure the following is present in the appropriate config file (e.g. LocalConfig.yml).
game:
  serviceConfigs:
    MatchmakingConfig:
      enableGetMatchmakingInfo: true
  • InstancedItemPlugin.Update can now return instanced and stackable item grants.
  • Description: UpdateResult returned from InstancedItemPlugin.Update now includes a list of instancedItemGrants and stackableItemGrants. To use this feature, simply populate the UpdateResult with a list of InstancedItemServerGrant and/or StackableItemGrant.
  • Reference:
data class UpdateResult(
val extInstancedItem: ExtInstancedItem,
  val rewardGrants:List<RewardGrant> = listOf(),
  val instancedItemGrants: List<InstancedItemServerGrant> = listOf(),
  val stackableItemGrants: List<StackableItemGrant> = listOf()
)

Deprecations: #

  • LeaveMatchmakingV1 has been updated to V2.

    OriginalReplacementRemoval Patch
    MatchmakingRpc.LeaveMatchmakingV1MatchmakingRpc.LeaveMatchmakingV20.0.60
  • Rewrite your configuration files (e.g. LocalConfig.yml or CommonConfig.yml) to specify plugins by their fully qualified path.

    Original (example)Replacement (example)Removal Patch
    pluginConfigs:
    GameDataService.gameDataStrategyPlugin:
      class: "DefaultPragmaGameDataStrategyPlugin"
    
    pluginConfigs:
    GameDataService.gameDataStrategyPlugin:
      class: "pragma.gamedata.DefaultPragmaGameDataStrategyPlugin"
    
    0.0.60

    Integrations: #

    • Reimplement plugins that implement BulkActionPlugin as suspend methods.
      • Description: Updated BulkActionPlugin interface to use suspend methods for needsFullPragmaAccount and apply.
      • Integration steps:
        • If you have plugins that implement the BulkActionPlugin interface, reimplement the relevant methods as suspend methods:
          • needsFullPragmaAccount
          • apply
          • Any of your own methods that call the above two methods.
      • References
        • 2-pragma/social-common/src/main/kotlin/pragma/account/BulkActionPlugin.kt
        • 4-demo/demo/src/main/kotlin/demo/account/DemoBulkActionPlugin.kt
    • Create a new proto file partyRpcExt.proto to successfully build your Pragma extension.
      • Description: In order to support Party feature development, we have added new protos. You must create these protos in order to successfully build your plugin.
      • Integration steps:
        • Create partyRpcExt.proto in the 5-ext/ext-protos/src/main/proto/shared/ directory.
        • Paste the following into partyRpcExt.proto:
    syntax = "proto3";
    
    package pragma.party;
    option csharp_namespace = "Pragma.Party";
    option (unreal_namespace) = "Party";
    option java_multiple_files = true;
    
    import "pragmaOptions.proto";
    
    message ExtUpdateLoadoutRequest {
    }
    

    Bugs and Fixes: #

    • Encryption on email table has been removed to allow for built-in encryption by the database provider.
      • Description: Upgrading to the newest version of Pragma will drop any existing emails that were gathered using the AccountRpc.UpdateEmailV1 endpoint.
    • Default authentication ports for config files have been fixed to ensure Player, Operator, and Partner flows are separate.
      • Description: Resolves authentication errors caused by Player, Operator, and Partner flows using the same authentication port.
    • Fix for Unity SDK when accessing inventory payloads before checking for response success.
      • Description: The Unity SDK no longer crashes when accessing inventory payloads.

Pragma Engine 0.0.57 #

March 1st, 2022

  • Limited Access Event Mode is now available via the Pragma Portal.
  • Required integration:
    • 5-ext/ext-protos/pom.xml has been updated and needs to be regenerated.
    • The Portal configuration location has changed.
    • longRangeProxy has been deprecated.
      • Removed InstancedItemPlugin.init method.
      • Updated RewardSelectorPlugin.init parameters.
    • runBlockingTestWithTimeout has been removed.
    • As part of a code cleanup, many runBlocking calls have been removed.
    • Several party ext protos have been renamed.
  • Improvements and bug fixes
    • Additional validation for storeEntries in Stores.json.
    • Fixed a crash in the SDK when trying to handle valid CraftV1 responses that contained Errors associated with the craft attempt.

Integrations: #

  • 5-ext/ext-protos/pom.xml has been updated and needs to be regenerated.
    • Description: 5-ext/ext-protos/pom.xml has been updated to add compatibility with Apple Silicon.
    • Integration steps:
      • Move your existing 5-ext/ext-protos/pom.xml out of the pragma-engine directory. (If you have never customized this file, you may instead delete it.)
      • Run make ext to regenerate the pom.xml file.
      • If you made customizations to this file, diff the new and old pom.xml files and manually restore the changes you have made.
  • The Portal configuration location has changed.
    • Description: Portal config has been moved out of game-config.json and social-config.json and is now in YAML (e.g. LocalConfig.yml or CommonConfig.yml) as part of the FilePortalModulePlugin settings.
    • Integration steps:
      • Most users will not want to directly translate the game-config.json and social-config.json to the yml; the defaults should remain in place for the majority of portal uses. Your config file should only have these entries (with the portalSource value being the path to the folder containing the portal HTML and JavaScript files):
      game:
        pluginConfigs:
          GameOperatorGatewayNodeService.portalPlugin:
            class: "FilePortalModulePlugin"
            config:
              portalSource: "web/portal-base"
      social:
        pluginConfigs:
          SocialOperatorGatewayNodeService.portalPlugin:
            class: "FilePortalModulePlugin"
            config:
              portalSource: "web/portal-base"
      
      • If you are doing something custom, you’ll want to include the relevant sections in the config to add or override the settings. Here’s an example:
      game:
        pluginConfigs:
          GameOperatorGatewayNodeService.portalPlugin:
            class: "FilePortalModulePlugin"
            config:
              portalSource: "custom/portal/path" //override
              modules:
                1: "PlayerSupport"
                2: null //disable a module
                3: "ContentCatalogs"
                100: "MyCustomGameModule" //add custom module
              defaultModule: "MyCustomGameModule" //override
              discordClientId: "DISCORD_CLIENT_ID" //override
      social:
        pluginConfigs:
          SocialOperatorGatewayNodeService.portalPlugin:
            class: "FilePortalModulePlugin"
            config:
              portalSource: "custom/portal/path" //override
              modules:
                1: "Accounts"
                2: null //disable a module
                100: "MyCustomSocialModule" //add custom module
              defaultModule: "MyCustomSocialModule" //override
              discordClientId: "DISCORD_CLIENT_ID" //override
      
  • longRangeProxy has been deprecated.
    • Description: Please use randomProxy instead of longRangeProxy.
    • Details:
      • See 2-pragma/core/src/main/kotlin/pragma/utils/RandomProxy.kt for implementation details.
      • See 2-pragma/core/src/test/kotlin/pragma/utils/RandomProxyTest.kt for example usages.
      • Note the two integration items below regarding InstancedItemPlugin.init and RewardSelectorPlugin.init.
  • Removed InstancedItemPlugin.init method.
    • Description: Removed InstancedItemPlugin.init as longRangeProxy has been removed.
  • Updated RewardSelectorPlugin.init parameters.
    • Description: longRangeProxy has been deprecated.
    • Integration step: use randomProxy in place of longRangeProxy.
OriginalReplacement
fun init(
  randomProxy: LongRangeProxy,
  content: InventoryServiceContent
)
fun init(
  content: InventoryServiceContent
)
  • runBlockingTestWithTimeout has been removed.
    • Description: We have updated the runBlocking functions for unit tests.
    • Integration steps:
      • Use runTest in place of runBlockingTestWithTimeout for unit tests.
      • Use runIntegrationTest in place of runBlockingTestWithTimeout for integration tests.
OriginalReplacement

runBlockingTestWithTimeout

runTest for unit tests

runIntegrationTest for integration tests

  • As part of a code cleanup, many runBlocking calls have been removed.

    • Description: Many runBlocking calls have been removed. This will require changes in your codebase.
    • Integration step: Make the following changes in your code.
    OriginalReplacement
    TestAccountManager.operatorClientTestAccountManager.getOperatorClient()
    TestAccountManager.partnerClientTestAccountManager.getPartnerClient()
    PragmaClientFactory.playerEndpointInfoPragmaClientFactory.getPlayerEndpointInfo()
    PragmaClientFactory.operatorEndpointInfoPragmaClientFactory.getOperatorEndpointInfo()
    PragmaClientFactory.partnerEndpointInfoPragmaClientFactory.getPartnerEndpointInfo()
  • Several party ext protos have been renamed.

    • Description: As part of the ongoing development of the party service, a couple ext protos have been renamed. You will need to make changes in 5-ext to have empty definitions for these new protos in order to compile.
    • Integration step: Make the following changes in 5-ext/ext-protos/src/main/proto/shared/partyExt.proto.
    OriginalReplacement
    ExtPartyDetailsExtPublicPartyData
    ExtPartyPlayerExtPublicPlayerData

Features: #

  • Limited Access Event Mode is now available via the Pragma Portal.
    • Description: Limited Access Events (LAEs) restrict which Players can log in and stay logged in to a specific Game Shard by associating Player Groups to an LAE. LAEs also have a start and an end date that will indicate how long the LAE is enforced. LAEs can be turned on in the portal by setting a Game Shard Access Mode to Specific Groups.

Bugs and fixes: #

  • Additional validation for storeEntries in Stores.json.
    • Description: The content system will now ensure that StoreEntries have receivedQuantityByCatalogId field populated. This check is performed during content apply and service startup, and the engine will not start if this field is missing.
  • Fixed a crash in the SDK when trying to handle valid CraftV1 responses that contained Errors associated with the craft attempt.

Pragma Engine 0.0.56 #

February 22nd, 2022

  • Added ability to directly add or remove players in a Player Group.
  • Required integration:
    • Update implementations of LobbyStrategy.setExtPlayerInfo with the new LobbyModel parameter.
    • Update implementations of StorePlugin.meetsRequirements with the new storeId parameter.
    • Replace references to the helper method assertProtoEquals() with JUnit’s assertEquals().

Features: #

  • Added ability to directly add or remove players in a Player Group.
    • Description: We’ve added functionality that allows directly adding or removing players in a Player Group. Responses include playerGroupIds.
    • Postman paths:
      • Social → RPC - Operator → Account → AddAccountToPlayerGroupOperatorV1
      • Social → RPC - Operator → Account → RemoveAccountFromPlayerGroupOperatorV1

Integrations: #

  • Update implementations of LobbyStrategy.setExtPlayerInfo with the new LobbyModel parameter.
    • Description: We’ve added a new parameter to the setExtPlayerInfo function in the LobbyStrategy plugin interface, so you can access data from the Lobby when setting player ext info.
    • Integration step: Make the following changes in implementations of LobbyStrategy.setExtPlayerInfo.
OriginalReplacement
setExtPlayerInfo(
  lobbyPlayer: LobbyPlayer,
  extPlayerInfo: ExtPlayerInfo
)
setExtPlayerInfo(
  lobbyPlayer: LobbyPlayer,
  extPlayerInfo: ExtPlayerInfo,
  lobbyModel: LobbyModel
)
  • Update implementations of StorePlugin.meetsRequirements with the new storeId parameter.
    • Description: We’ve added a new parameter to the meetsRequirements function in the StorePlugin plugin interface, so access data about the store when making a purchase from the store.
    • Integration step: Make the following changes in implementations of StorePlugin.meetsRequirements.
OriginalReplacement
meetsRequirements(
  storeEntry: InventoryContent.StoreEntry,
  inventoryData: InventoryData,
  progressionData: PlayerProgressionRpc.ProgressionV1Data
)
meetsRequirements(
  storeId: String,
  storeEntry: InventoryContent.StoreEntry,
  inventoryData: InventoryData,
  progressionData: PlayerProgressionRpc.ProgressionV1Data
)
  • Replace references to the helper method assertProtoEquals(), which has been removed.
    • Description: We’ve removed the assertProtoEquals() helper method. Use JUnit’s assertEquals() method instead.
    • Integration step:
      OriginalReplacement
      assertProtoEquals()JUnit’s assertEquals()

Pragma Engine 0.0.55 #

February 15th, 2022

  • Added capability to grant rewards with the InstancedItemPlugin.update function.
  • Required integration:
    • Update InstancedItemPlugin.update() with new parameter and return type.
  • Optional integration:
    • Rename histogram config to continue using histogram metrics.
  • Bug fix:
    • Removed distributedServiceCounts configuration.

Features: #

  • Added capability to grant rewards with the InstancedItemPlugin.update function.
    • Description: We’ve made two changes to the InstancedItemPlugin.update() interface to enable rewards grant.

      • New parameter inventoryContent: InventoryServiceContent which gives access to all content
      • Returns type UpdateResult instead of ExtInstancedItem
    • Reference:

      • Structure of UpdateResult:
      data class UpdateResult(
        val extInstancedItem: ExtInstancedItem,
        val rewardGrants: List<RewardGrant>
      )
      
    • Related note: Integration required. See content system note below.

Integrations #

  • Update InstancedItemPlugin.update() with new parameter and return type.

    • Description: You will need to update InstancedItemPlugin.update() to integrate with the new crafting system.

    • Integration step:

      • In the update() method, add inventoryContent: InventoryServiceContent parameter after updateEntry.
      • In the update() method, change return type from ExtInstancedItem to UpdateResult.
      OriginalReplacement
      InventoryContent.UpdateEntryinventoryContent: InventoryServiceContent
      ExtInstancedItemUpdateResult
    • Reference:

      • Check out the pet update example in DemoInstancedItemPlugin for a sample implementation.
    • Related note:

      • New related feature. See rewards feature note above.
  • Rename histogram config to continue using histogram metrics.

    • Description: Histogram metric config has been renamed.
    • Integration step:
      • To continue using histogram metrics, you must rename the config.
      OriginalReplacement
      enableHistogramenableHistogramMetrics

Bug fix #

  • Fixed issue with creating Limited Access Events with multiple player groups.
    • Description: You can now create and update Limited Access Events with more than one player group using MariaDB.

Deprecations #

  • Removed distributedServiceCounts configuration.
    • Description: We don’t expect anyone to be using this, so no integration steps are required. We will be adding a multi-node configuration soon. If you are using this configuration to change the number of instances of a service, please contact us for help integrating.

Pragma Engine 0.0.54 #

February 8th, 2022

  • Added bulk action account plugin.
  • Added new type of item grant to crafting calls to allow for randomized rewards.
  • Game Shard Access Mode is now live.
  • Required integrations:
    • You will need to update your crafting plugin to integrate with the new crafting system.

Features #

  • Added bulk action account plugin.

    • Description: We’ve added a BulkActionPlugin that lets users perform customer-defined actions leveraging our account searching functionality.
    • Reference: Pragma.Account.BulkActionPlugin
  • Added new type of item grant to crafting calls to allow for randomized rewards.

    • Description: We’ve added a rewardGrants option into the crafting class so players can receive a RewardGrant in addition to instancedItems and stackableItems. A RewardGrant maps to a RewardTable that can result in a set of guaranteed rewards items and/or random rewards by using RewardSlots.
    • Related notes: Integration required. See content system note below.
    • Reference:
    data class CraftResult(
      val instancedItemGrants: List<InstancedItemServerGrant>,
      val stackableItemGrants: List<StackableItemGrant></StackableItemGrant>,
      val rewardGrants: List<RewardGrant> = listOf()
    )
    
  • Game Shard Access Mode is now live.

    • Description: shardAccessMode is now enforced on authenticateOrCreate. Authentication will respect the set shardAccessMode and deny access to users not in approved player groups on active limited access events. Default access is set to everyone.
    • Postman path:
      • Social → RPC - Operator → Game Management → SetShardAccessModeV1

Integrations #

  • Update crafting plugin with new content map.
    • Description: You will need to update your crafting plugin to integrate with the new crafting system.

    • Integration step:

      • In the craft() method, replace the catalog parameter with inventoryContent:
      OriginalReplacement
      catalog: InventoryCataloginventoryContent: InventoryServiceContent
    • Reference:

      • inventoryContent.instancedSpecs[<CATALOG_ID>] returns the InstancedSpec proto.
      • View 4-demo’s CookingCrafter.completeCooking() or Quests.complete() for an example of the InventoryContentService and how to properly add a rewardGrant to the CraftResult.
      • Check this pull request or contact us for additional information or assistance.
    • Related notes: New related feature. See rewards feature note above.

Deprecations #

  • AddAccountsToPlayerGroupOperatorV1 has been replaced by BulkActionOperatorV1.
    • See the Postman collection for an example of the payload.
OriginalReplacement
AddAccountsToPlayerGroupOperatorV1BulkActionOperatorV1
  • StackableSpecs and InstancedSpecs are now accessed as maps instead of lists in code.
    • There are no changes to the formatting of StackableSpecs and InstancedSpecs in content or protos. InstancedSpecs.json and StackableSpecs.json still consist of arrays of objects.
OriginalReplacement
List<StackableSpec>Map<String, StackableSpec>
List<InstancedSpec>Map<String, InstancedSpec>

Pragma Engine 0.0.53 #

February 1st, 2022

  • Users can now use map accessors instead of iterating over an array all the time.
  • Platform can be configured to bind to a port different from what it advertises.
  • Unreal can now build with Unity and PCH disabled.
  • Required integrations:
    • Some protos have been renamed, so relevant imports and references will need to be updated. See full notes for complete list.
    • New matchmaking function must be added to successfully compile.
    • Added suspend to LobbyStrategy interface functions.
    • Update references to renamed TestFactory classes.
    • Changed config getter method names in BaseServerIT class.
  • Bugfix:
    • Removed unsupported WebSocket scheme in HTTP responses for GET /v1/info.

Features #

  • Users can now use map accessors instead of iterating over an array all the time.

    • Description: ItemCatalog now has InstancedEntriesMap and StackableEntriesMap.
  • Platform can be configured to bind to a port different from what it advertises.

    • Description: Platform can now be configured to bind to a port different from what it’s advertising, such as when used behind a dynamically registering load balancer. Unless explicitly set in configuration, these values will default to the relevant socialPort/gamePort config values. This change is backwards compatible.
    • Details:
      • SocialPlayerGatewayConfig has new value socialBindPort.
      • GamePlayerGatewayConfig has new values socialBindPort and gameBindPort.
  • Unreal can now build with Unity and PCH disabled.

    • Description: The Unreal SDK now builds properly with both “Unity” and “PCH” disabled (strict IWYU).
  • Added new hooks to Lobby service to enable refreshing cached inventory and progression.

    • Description: We’ve added refreshInventory and refreshProgression functions to the LobbyPlayer data class passed to existing lobby plugins. These allow you to trigger updates to cached information from the client.
    • Details:
      • refreshInventory and refreshProgression functions return an updated copy of data and recache the new result with that player.
      • These functions take in an InventoryClient and ProgressionClient respectively, which can be constructed and used from within the plugin.
      • These calls should be invoked sparingly–not on every plugin call. We recommend using ext fields to make an UPDATE command that can be called from the client if the player is in a lobby and an operation causing a cache refresh occurs.

Integrations #

  • Some protos have been renamed, so relevant imports and references will need to be updated.

    • Description: Protos have been updated for consistency. Please make the changes below to ensure compatibility.
    • Integration steps:
      • Renamed rewardsContent.proto to rewardContent.proto.
        • Any imports will need to be updated.
      • Renamed RewardsCount message to RewardCount.
        • Any references and imports will need to be updated.
      • Renamed RewardsTable message to RewardTable.
        • Requires updating any code referencing RewardsTable proto messages, as well as the following InventoryTestFactory methods:
          OriginalReplacement
          rewardsTables()rewardTables()
          rewardsTable()rewardTable()
      • Moved RewardsCatalog from RewardContent.proto to InventoryRpc.proto.
        • This message was only used by RPC, not content. Any references and imports will need to be updated.
      • Renamed references to the following content access properties in InventoryServiceContent:
        OriginalReplacement
        stackableItemSpecsstackableSpecs
        instancedItemSpecsinstancedSpecs
        catalogUpdateEntriesupdateEntries
        rewardsTablesrewardTables
      • Renamed the following content files in the {{% variable "Pragma" "path-content" %}}:
        OriginalReplacement
        CatalogCraftingEntries.jsonCraftingEntries.json
        CatalogUpdateEntries.jsonUpdateEntries.json
        InstancedItemSpecs.jsonInstancedSpecs.json
        StackableItemSpecs.jsonStackableSpecs.json
  • New matchmaking function must be added to successfully compile.

    • Description: Add new function addToMatchAndBuildMatchmakingDetails to implementations of MatchmakingStrategy plugin. This will be used in our upcoming game loop systems.
    • Integration step:
      • Paste the following no-op stub into any MatchmakingStrategy implementations:
override fun addToMatchAndBuildMatchmakingDetails(
  matchmakingKey: ExtMatchmakingKey,
  partiesByTeamId: MutableMap<Int, MutableSet<MatchmakingParty>>,
  partyToAdd: MatchmakingParty
): ExtCreateMatchV1Request? {
  return null
}
  • Added suspend to LobbyStrategy interface functions.

    • Description: Added suspend to function definitions setExtPlayerInfo and setExtLobbyInfo.
    • Integration steps:
      • You will need to make the following changes:

        OriginalReplacement
        fun setExtPlayerInfosuspend fun setExtPlayerInfo
        fun setExtLobbyInfosuspend fun setExtLobbyInfo
      • If the code is called in mockk every or verify blocks, you will also need to update:

        OriginalReplacement
        every { lobbyStrategy.setExtLobbyInfo... }coEvery { lobbyStrategy.setExtLobbyInfo... }
        verify { lobbyStrategy.setExtLobbyInfo... }coVerify { lobbyStrategy.setExtLobbyInfo... }
  • Update references to renamed TestFactory classes.

    • Description: You will need to update references to any of the TestFactory classes listed below. These have been renamed for increased clarity.
    • Integration step:
      • If you have any tests using any TestFactory from this table, you will need to update your references to the new class name:
        OriginalReplacement
        (pragma.inventory.)TestFactoryInventoryTestFactory
        (pragma.matchmaking.)TestFactoryMatchmakingTestFactory
        (pragma.)InventoryTestFactoryInventoryProtoTestFactory
        (pragma.)MatchmakingTestFactoryMatchmakingProtoTestFactory
  • Changed method names in BaseServerIT class

    • Description: getConfigAsJsonNode() has been renamed to getGame ConfigAsJsonNode() and getSocialConfigAsJsonNode() has been added.
    • Integration step:
      • You will need to change all calls to getConfigAsJsonNode() to getGameConfigAsJsonNode().

Bugfix #

  • Removed unsupported WebSocket scheme in HTTP responses for GET /v1/info.
    • Description: HTTP requests to the GET /v1/info endpoint will no longer return the nonfunctioning wsScheme in the authenticateBackend section.

Deprecations #

OriginalReplacement
ItemCatalog.InstancedEntries/StackableEntriesItemCatalog.StackableEntriesMap/InstancedEntriesMap
ContentData.get(Long)ContentData.get(String)
ContentDataNodeService::getOrLoadContent()use ContentDataNodeService::getHandler() OR the ContentDataProxy class

Pragma Engine 0.0.52 #

January 25th, 2022

  • Optional integrations:
    • For any classes using the MatchmakingStrategy interface, you must define a new method to validate if a party can be put into matchmaking.
    • If you have existing custom portal development, you will need to migrate to the new portal 5.ext-webapp structure.

Integrations #

  • For any classes using the MatchmakingStrategy interface, you must define a new method to validate if a party can be put into matchmaking.
    • Description: Define a new method for validate(matchmakingKey: ExtMatchmakingKey, matchmakingParty: MatchmakingParty).
  • If you have existing custom portal development, you will need to migrate to the new portal 5.ext-webapp structure.
    • Description: The portal 5.ext-webapp structure has changed. Once the steps below are completed, all regular development is done under /web/packages/5-ext-webapp.

    • Steps:

      1. Rename web/packages/5-ext-webapp to web/packages/5-ext-webapp_initial.
      2. Create a new 5-ext-webapp:
        $ cd platform && make portal-ext-create
        
      3. Bring your custom code over by replacing the entire /web/packages/5-ext-webapp/src folder with web/packages/5-ext-webapp_initial/app/src.
      4. Update the config files by replacing the /web/packages/5-ext-webapp/public/config folder with web/packages/5-ext-webapp_initial/app/public/config.
      5. (optional) If needed, add your extra dependencies to /web/packages/5-ext-webapp/package.json, then run: run npm install
    • Additional information: We’ve added a new make command for building the ext portal for CI. This will create a bundle ready to be deployed under platform/web/packages/5-ext-webapp/build.

      $ cd platform
      $ make ci-portal-ext
      

      For development, start the server in /web/packages/5-ext-webapp with:

      npm run start
      

      For more information, read the README_PORTAL.md file.

Deprecations #

  • none

Pragma Engine 0.0.51 #

January 18th, 2022

  • Required integration:
    • You must define message ExtEnterMatchmakingV2Request in matchmakingExt.proto to successfully compile.

Integrations #

  • You must define message ExtEnterMatchmakingV2Request in matchmakingExt.proto to successfully compile.
    • Description: The new proto message ExtEnterMatchmakingV2Request must be defined. This is to prepare for the new party service currently being built.
      message ExtEnterMatchmakingV2Request {
      }
      
    • Path:{{% variable "Pragma" "path-extProto" %}}matchmakingExt.proto

Pragma Engine 0.0.50 #

January 12th, 2022

  • Added endpoints for Operators and Partners to edit tags on accounts.
  • Added verificationEmailEndpoint parameter for verification email templates to allow players to verify emails with one click.
  • Stores can now accept instanced and stackable items as required ingredients for crafting.
  • Bugs and Fixes
    • Order changed in Service.shutdown().
    • playAgain function fixed.
    • Player inventory now properly checked for purchasability.

Features #

  • Added endpoints for Operators and Partners to edit tags on accounts.

    • Description: Added endpoints to let Operators and Partners get/add/remove tags on accounts.
    • Postman Paths:
      • Social → RPC Operator → Account → ViewPlayerGroupOperatorV1
      • Social → RPC Operator → Account → RemoveAccountTagsOperatorV1
      • Social → RPC Operator → Account → AddAccountTagsOperatorV1
      • Social → RPC Partner → RemoveAccountTagsPartnerV1
      • Social → RPC Partner → GetAccountTagsPartnerV1
  • Added verificationEmailEndpoint parameter for verification email templates to allow players to verify emails with one click.

    • Description: A new parameter, verificationEmailEndpoint, can be added to verification email templates.
  • Stores can now accept instanced and stackable items as required ingredients for crafting.

    • Description: requiredCatalogIds in Stores.json now accepts instancedItem catalogIds as well as stackableItem catalogIds.

Integrations #

  • You must define exts in implementation types to successfully compile. This change is to prepare for the new party service currently being built.
    • Description: Add the following lines to partyExt.proto.
      message ExtPartyDetails {
      }
      
      message ExtPartyPlayer {
      }
      
    • Path:{{% variable "Pragma" "path-extProto" %}}partyExt.proto

Bugs and Fixes #

  • Order changed in Service.shutdown().

    • Description: shutdownService() is now called before we cancel all jobs.
  • playAgain function fixed.

    • Description: Recreates a lobby and invites players from previous match.
  • Player inventory now properly checked for purchasability.

    • AnnotatedStore now consults a player’s inventory properly when determining if they can purchase a storeEntry.

Deprecations #

  • none

Pragma Engine 0.0.49 #

January 4th, 2022

  • Updated Inventory content validation flow in preparation for upcoming content system changes.
  • Renamed player group property to be consistent with other calls.
  • Improved variable visibility for PragmaException messages.
  • Required integrations:
    • Unit tests must be updated from runBlockingTest to runTest.
    • Calls to content getters will need to be updated to Kotlin property names.

Features #

  • Updated Inventory content validation flow in preparation for upcoming content system changes.
    • Description: Inventory content is now validated and loaded on Inventory service startup, instead of on content request. Pragma engine will fail to start if there are any errors related to JSON, proto, or custom validation in shared content files.
  • Renamed player group property to be consistent with other calls.
    • Description: CreatePlayerGroupOperatorV1Response uses group instead of player_group as the property.
    • Postman Path:
      • Social → RPC Operator → Account → CreatePlayerGroupOperatorV1
    • Improved variable visibility for PragmaException messages.
      • Description: Added ' around variables to improve PragmaException messages.

Integration Steps #

  • Unit tests must be updated from runBlockingTest to runTest.
    • Description: Kotlin and Kotlin coroutine versions have been updated, causing deprecation warnings for tests using runBlockingTest.
    • Integration steps:
      • Change any instances of runBlockingTest to runTest.
  • Calls to content getters will need to be updated to Kotlin property names.
    • Description: References to content getter methods have been replaced with Kotlin properties.
    • Integration steps:
      • Calls to content getters in InventoryServiceContent will need to be updated to property names. Full table below.
        OriginalReplacement
        getStackableItemSpecs()stackableItemSpecs
        getInstancedItemSpecs()instancedItemSpecs
        getCatalogUpdateEntries()catalogUpdateEntries
        getStores()stores
        getRewards()rewards
        getRewardsTables()rewardsTables
        getRewardSlots()rewardSlots
        getRewardBags()rewardBags
        getCraftingEntries()craftingEntries

Deprecations #

The following endpoints have been changed:

OriginalReplacement
{{% variable "Pragma" "postman-authenticateOrCreateV1" %}}{{% variable "Pragma" "postman-authenticateOrCreateV2" %}}
AccountService.getPragmaPlayerIdsForProviderIdsV1AccountService.getPragmaPlayerIdsForProviderIdsV2
InventoryServiceContent getter methods have been updatedSee integration notes above

Pragma Engine 0.0.48 #

December 14th, 2021

  • Added new player group capabilities, such as creating new player groups, viewing information about them, and bulk adding players by tag.
    • Please note that these features are early access and require Postman. They require running against 4-demo or following the implementation steps in the player tags feature below.
  • Required integration:
    • New GameDataStrategy interface: Follow the steps in the detailed section below to adjust your implementation to migrate from setLoginDataProtoFields to the new getExtLoginData wrapper.
  • Optional integration:
    • Updated confirmation email expiration duration to be 7 days, with an optional configuration step: Add an emailTokenExpirationMinutes config into CommonConfig.yml with the desired duration

Features #

  • Added ability to create a player group and view information about it.
    • Description: We’ve added the ability to create and view details about player groups, such as a beta group.
    • Reference:
      • CreatePlayerGroupOperatorV1 allows you to create a player group with a name and optional description.
      • ViewPlayerGroupOperatorV1 displays information about all player groups. It includes which users are part of a player group, and provides information about the group name and description.
    • Postman Paths:
      • Social → RPC Operator → Account → ViewPlayerGroupOperatorV1
      • Social → RPC Operator → Account → CreatePlayerGroupOperatorV1
  • Added ability to make changes to a player group name and description.
    • Description: We’ve added the ability to make changes to player group names and descriptions.
    • Reference:
      • EditPlayerGroupOperatorV1 allows you to edit the name and description of a player group.
    • Postman Path:
      • Social → RPC Operator → Account → EditPlayerGroupOperatorV1
  • Added ability to tag user accounts on account creation.
    • Description: We’ve added the ability to add tags to player accounts on user creation. This step is required to bulk add players to a player group.
    • Reference:
      • registerEmailV1 registers a new user account using an email address. If you’re not running pragma-engine against 4-demo, you must implement the appropriate exts. Refer to 4-demo and its implementation of Pragma.Account.AccountPlugin for an example of adding tags and providing them to an account with registerEmailV1.
    • Paths:
      • Social → RPC Partner → registerEmailV1
      • platform/4-demo/demo-protos/src/main/proto/shared/accountRpcExt.proto contains ExtCreateAccountRequest
  • Added ability to get user counts of player groups, bulk add players by tag, and manage excluded player groups.
    • Description: We’ve added the ability to manage player groups using tags.
    • Reference:
      • GetPlayerCountByTagsOperatorV1 displays the number of players in a group by tag.
      • AddAccountstoPlayerGroupOperatorV1 enables adding players by tag to a player group, with an optional excluded player field.
    • Postman Paths:
      • Social → RPC Operator → Account → GetPlayerCountByTagsOperatorV1
      • Social → RPC Operator → Account →AddAccountstoPlayerGroupOperatorV1

Integration Steps #

  • New GameDataStrategy interface to increase cohesion between plugins.

    • Description: To increase cohesion between plugins, we’ve updated the GameDataStrategy interface. This change includes a data wrapper which will need to be integrated instead of using the previous builder object.
    • Integration steps:
      1. Delete any implementations of fun init(contentDataNodeService: ContentDataNodeService). No replacement is required as the plugin constructor provides access to the ContentDataNodeService.
      2. Update setLoginDataProtoFields to getExtLoginData. Create ExtLoginData, fill it out with the existing logic being passed into the builder, and return it.
      3. Locate plugin configurations for GameDataService.gameDataStrategy and update them to GameDataService.gameDataStrategyPlugin.
  • Updated confirmation email expiration duration to be 7 days, with an optional configuration step.

    • Description: Email expiration duration was previously tied to player session expiration, and has now been changed to a default of 7 days. This default can be overwritten manually via CommonConfig.yml.
    • Integration steps: Add an emailTokenExpirationMinutes line into CommonConfig.yml with the desired duration.
    • Reference:
      social:
        serviceConfigs:
          TokenSignerConfig:
            emailTokenExpirationMinutes: 10
      

Deprecations #

  • None

Pragma Engine 0.0.47 #

November 30th, 2021

  • Added ability to attach multiple provider accounts to pragmaSocialIds
  • Required integration:
    • None
  • Optional integration:
    • None

Features #

  • Players can now log in to the same account using different identity providers.
    • Description:
      • A given e-mail address or Discord account can only be associated with one Pragma account.
      • E-mails and Discord accounts cannot be unlinked from Pragma accounts.
      • Multiple types of identity providers can be linked with one Pragma account.

Integration Steps #

  • None

Deprecations #

  • None

Pragma Engine 0.0.46 #

November 23rd, 2021

  • Added a service call to delete the entire contents of a player’s inventory.
  • Added a way to include additional metadata with crafting requests.
  • Required integration:
    • New format of /v1/info response: Update Pragma Platform before integrating the latest SDKs, not the other way around.
  • Optional integration:
    • Configure the ext jar to be copied and renamed on build: Copy the plugin block that was added to ext-server-pom.template and paste it into your 5-ext/ext-server/pom.xml.

Features #

  • Added a service call to delete the entire contents of a player’s inventory.
    • Description: Added DeletePlayerInventoryV1 which allows players to delete all of their inventory.
    • Reference: New config value in InventoryServiceConfig.enableDeletePlayerInventory controls whether the endpoint is active (default: FALSE).
    • Path: pragma-engine/platform/2-pragma/game/src/main/kotlin/pragma/inventory/InventoryServiceConfig.kt
  • Added a way to include additional metadata with crafting requests.
    • Description: Added ExtCraftRequest to the meetsRequirements() function in the CraftingPlugin.
    • Reference: For an implementation example, check out the PetEvolutionRequest used in 4-demo’s PetCrafter.kt.
    • Path: pragma-engine/platform/4-demo/demo/src/main/kotlin/pragma/inventory/PetCrafter.kt

Integration Steps #

  • Updated the format of the /v1/info response.
    • Description: The format of the /v1/info response has been updated. Although this is backwards compatible, newer clients cannot communicate with an older Pragma backend.
    • Integration steps: Update Pragma Platform before integrating the latest SDKs, not the other way around.
  • Users can configure the ext jar to be copied and renamed on build.
    • Description: The ext jar can now be automatically copied to a more convenient location and renamed when building.
    • Integration steps: Copy the plugin block that was added to ext-server-pom.template and paste it into your 5-ext/ext-server/pom.xml
    • Reference:
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>com.coderplus.maven.plugins</groupId>
        <artifactId>copy-rename-maven-plugin</artifactId>
        <version>1.0</version>
        <executions>
          <execution>
            <id>copy-file</id>
            <phase>install</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <sourceFile>target/ext-server-PRAGMA-LOCAL-SNAPSHOT-jar-with-dependencies.jar</sourceFile>
              <destinationFile>../../5-ext/target/pragma.jar</destinationFile>
            </configuration>
          </execution>
        </executions>
      </plugin>
      

Deprecations #

The following endpoints have been changed:

OriginalReplacement
PlayerMatchEndV2.item_updatesPlayerMatchEndV2.server_item_updates
getDisplayNameForPragmaPlayerIdForPartnerV1use match data for player display names

Pragma Engine 0.0.45 #

2021-11-16

Features #

  • New Pragma CLI option crypto remoteServiceToken for generating partner game and social tokens
  • RegisterEmailV1 api is configurable to create a pragma account and send an email with unique code to a prospective Beta user

Integration Notes #

  • Renamed any references to Arbiter or Example to Demo (eg ArbiterMatchEndPlugin -> DemoMatchEndPlugin)
  • Renamed 4-example-ext to 4-demo, and all example submodules to demo instead
  • Updated Makefile and various build scripts to use 4-demo instead of 4-example-ext
  • Renamed Unity and Unreal PragmaSDK ExampleProjects to be PragmaDemo
  • Delete all references to CatalogTestFactory in test code. Reimport from InventoryTestFactory. CatalogTestFactory has been collapsed into InventoryTestFactory.
  • Update all references from function InventoryTestFactory.stackableCatalogEntries to InventoryTestFactory.stackableSpecs
  • Update all references from function InventoryTestFactory.instancedCatalogEntries to InventoryTestFactory.instancedSpecs
  • Update all references from function InventoryTestFactory.repeatedStackableDelta to InventoryTestFactory.stackableDeltas
  • Update all references from function InventoryTestFactory.repeatedInstancedDeltaV2 to InventoryTestFactory.instancedDeltaV2s

Pragma Engine 0.0.44 #

2021-11-09

Features:

  • Many protos related to Inventory have been relocated to make the system more understandable for a designer. CONSULT INTEGRATION NOTES.
  • CreatePartnerTokenV1 has been updated to return a Partner Social token
  • Enabled server authoritative item update flow on match end. New ExtInstancedItemServerUpdate added to inventoryRpcExt.proto.
  • Added new operator RPC UpdateGameTitleV1 for editing a game title name or description. Part of the featureset for Portal Game Management.
  • Added new operator RPC CreateGameTitleV1 for creating a new game title with a name and description.
  • Added new operator RPC ViewGameTitlesV1 for listing all game titles and their game shards.
  • Added new operator RPC ViewGameTitleV1 for retrieving a single game title and its game shard by id.

Integration Notes #

  • You will also need to sim-ship your client and server code when adopting this release. We try to avoid these sorts of breaking changes, so we would like to call specific attention to that.

  • Update 5-ext/ext-server/pom.xml - remove the dependency with:

    • groupId: pragma
    • artifactId: server
  • Within all Kotlin/proto code:

    • Relocate ExtCraftRequest from inventoryExt.proto to inventoryRpcExt.proto
    • Add new message definition to inventoryRpcExt.proto in 5-ext:
      • message ExtInstancedItemServerUpdate { }
    • Relocate all protos from both catalogExt.proto and storeContentExt.proto to inventoryContentExt.proto.
    • Delete catalogExt.proto
    • Delete storeContentExt.proto
    • Replace all references from CatalogContent.GameCatalog to InventoryContent.ItemCatalog
    • Replace all references from both pragma.catalog.CatalogContent and pragma.store.StoreContent to pragma.inventory.InventoryContent
    • Replace all references from pragma.InventoryTestFactory.gameCatalog to pragma.InventoryTestFactory.itemCatalog
    • Replace all import namespaces references from both pragma.catalog and pragma.store to pragma.inventory
    • Update all references from GameCatalog to ItemCatalog when handling LoginData, GetLoginDataV1Response, or GetCatalogOperatorV1Response protos
    • Rebuild all protos and SDK types
  • Within your Unreal game:

    • Replace all references from Dto/PragmaCatalogContentDto.h to Dto/PragmaInventoryContentDto.h
    • Replace all references from FPragma_Catalog_GameCatalog to FPragma_Inventory_ItemCatalog
    • Replace all references from FPragma_Catalog_StackableSpec to FPragma_Inventory_StackableSpec
    • Replace all references from FPragma_Catalog_InstancedSpec to FPragma_Inventory_InstancedSpec
    • Replace all references from FPragma_Store_Store to FPragma_Inventory_Store
    • Replace all references from FPragma_Store_StoreEntry to FPragma_Inventory_StoreEntry
    • Replace all references from FPragma_Store_PurchaseRequirements to FPragma_Inventory_PurchaseRequirements
    • Replace all references from FPragma_Store_CraftingEntry to FPragma_Inventory_CraftingEntry
    • Replace all references from FPragma_Store_CostEntry to FPragma_Inventory_CostEntry
    • Replace all references from FPragma_Store_UpdateEntry to FPragma_Inventory_UpdateEntry
    • Replace all references from FPragma_Catalog_ExtStackableSpec to FPragma_Inventory_ExtStackableSpec
    • Replace all references from FPragma_Catalog_ExtInstancedSpec to FPragma_Inventory_ExtInstancedSpec
    • Replace all references from FPragma_Store_ExtPurchaseRequirements to FPragma_Inventory_ExtPurchaseRequirements
    • Replace all references from FPragma_Store_ExtUpdateEntry to FPragma_Inventory_ExtUpdateEntry
    • Replace all references from FPragma_Store_ExtCraftingEntry to FPragma_Inventory_ExtCraftingEntry
    • Replace all references from FPragma_GameData_GetLoginDataV1Response.Payload().LoginData.GameCatalog to FPragma_GameData_GetLoginDataV1Response.Payload().LoginData.ItemCatalog
  • Within your Unity game:

    • Delete any broken using statements and import new references after regenerating SDK types.
    • Update references from GameCatalog to ItemCatalog.
  • Use PlayerMatchEndV2.server_item_updates instead of PlayerMatchEndV2.item_updates

  • Migrate existing InstancedDataProviderPlugin implementations to new name InstancedItemPlugin

    • Use the single new newInstanced method for all instanced item creation. Presence of the requestExt indicates server or client pathway.
    • The update method now has a requestExt for either a server or client pathway.
    • Change the parameter names of plugin implementations to match those found on the interface.
    • Update plugin configuration with new name
      • InventoryService.instancedItemPlugin: class: "YourPluginName"
    • Remove old plugin configuration item InventoryService.defaultInstancedDataProviderPlugin

Deprecations #

- `PlayerMatchEndV2.item_updates` deprecated.
- `getDisplayNameForPragmaPlayerIdForPartnerV1` deprecated. Use match data for player display names.
- Renamed operator RPC `ViewGamesV0` to `ViewGameTitlesV1`. No change in behavior.

Pragma Engine 0.0.43 #

2021-11-02

Features #

  • Players can now invite others using Lobby Invite Codes.

Deprecations #

  • Removed insertAccountsOrIgnoreLegacy from UnsafeIdentityDaoNodeService. Use insertOrIgnoreAccounts as a replacement.
  • Types.DisplayName has been removed in favor of AccountCommon.DisplayName
  • Removed MatchLifecycleRpc.PlayerInfo in favor of MatchLifecycleRpc.PlayerInfoV2
    • (PlayerInfo.DisplayName string)/(DisplayNameV2 Types.DisplayName) is now reflected in (PlayerInfoV2.DisplayName AccountCommon.DisplayName)
  • Removed MatchLifecycleRpc.MatchData in favor of MatchLifecycleRpc.MatchDataV2
    • MatchData.PlayerInfo has been updated to MatchData.PlayerInfoV2
  • Removed MatchLifecycleService.MatchReadyV1 in favor of MatchLifecycleService.MatchReadyV2.
  • Removed MatchCapacityRpc.ReportCapacityV1Request/Response in favor of MatchCapacityRpc.ReportCapacityV2Request/Response.
  • Removed buildExtensionMatchFoundNotification.

Pragma Engine 0.0.42 #

2021-10-26

Features #

  • Attempting to invite a player that is already in the lobby will now result in a LobbyService_AlreadyInLobby error.
  • Ignoring module 4-example-ext/example-ext-protos in Intellij by default to allow running All Tests when using oneof pattern in Exts
  • InviteReceivedV1Notification includes new field inviter_info, containing the InviterInfo (new message) from the player who sent the invite.
  • Players may no longer repeatedly send lobby invites to a player
  • New LobbyConfig config value, repeatInviteDelaySeconds. Sets how long a player must wait between sending a repeat invite to the same player. Default: 1.
  • New InviterInfo on InviteReceivedV1Notification is intended to replace the functionality currently achieved with the getDisplayNameForPragmaIdForPartnerV1 and getDisplayNameForPragmaPlayerIdForPartnerV1 calls.
  • CreatePartnerTokenV1 api will return a new Game Partner JWT token for when we cut over to the more restrictive JWT rules. This will need to be configured in the PartnerConnectionInfoConfig under the gameToken parameter

Integration Notes #

  • TimeProxy object has been moved to a class with a companion object. Any existing references to TimeProxy should be redirected to TimeProxy.defaultInstance
  • InventoryContent now returns ContentDataWrappers instead of GeneratedMessageV3 for the following calls: getStackableSpec(), getInstancedSpec(), getCatalogUpdateEntry(), getRewardsTable(), getRewardSlot(), getRewardBag(), and getCraftingEntry(). The data wrapper objects expose the same data as the proto object, but some names are slightly different. For example, RewardsTable.rewardSlotIdsList -> RewardsTableWrapper.rewardSlotIds. The GeneratedMessageV3 can still be accessed via the toProtobuf() function on the data wrappers.
  • Change runBlockingTimeout -> runBlockingTestWithTimeout
    • This has changed to return a type compatible with the Junit test runner to ensure tests are executed properly.

Pragma Engine 0.0.41 #

2021-10-19

Integration Notes #

  • InventoryV1Data field on LobbyPlayer has been removed, replaced by InventoryFullV1Data.

Pragma Engine 0.0.40 #

2021-10-19

Features #

  • Protobufs associated with content in the content/shared folder now use a string ID instead of int64. These changes affect the store and catalog system as well as the rewards system. Although any numeric value for an ID in the content definition files will automatically get cast to a string, this ID needs to be passed as a string through one’s application.
  • The local_game_player_inventory1 and local_game_player_inventory2 tables in the DB are destroyed and recreated with an additional catalogIdStr field persisting the string value as defined above. The numeric catalogId field will contain the (SipHash24) hash of this string ID.
  • Promoted the RPC endpoint CraftV0 to CraftV1 - The Unreal4, Unity and C# SDKs now have access to use the CraftV1 RPC endpoint. Implementation examples can be found in the ArbiterInstancedDataProviderPlugin and ArbiterCraftingPlugin; crafting catalog examples can be found in platform/4-example-ext/content/shared/CatalogCraftingEntries.json
  • Documentation can now be found in pragma-engine/documentation/release. Open Default.htm to view the new doc site.
    • The Google Docs directory is now deprecated but will remain available until all docs are ported over.

Integration Notes #

  • PartnerConnectionInfoConfig token was renamed to gameToken, if you configure this value you will need to update it or authentication errors will occur in GameServer calls

Deprecation #

  • InventoryV1Data field on LoginData has been removed.
  • InventoryV1Data field on LobbyPlayer has been removed.
  • MatchLifecycleRpc.MatchEndV2Request/Response has been removed.
  • MatchLifecycleRpc.MatchEnd has been removed.
  • InventoryRpc.UpdateItemV3Request/Response has been removed.
  • InventoryCommon.ItemGrant has been removed.
  • InventoryCommon.ItemUpdate has been removed.
  • Google Docs documentation is deprecated and will be removed when the new documentation is fully caught up.

Pragma Engine 0.0.39 #

2021-10-12

Features #

  • Added new coAssertThrowsExtError and assertThrowsExtError methods for testing convenience. See platform/2-pragma/core/src/test/kotlin/pragma/utils/TestUtils.kt

Integration Notes #

  • AccountRpc.DisplayName is now AccountCommon.DisplayName
  • LobbyRpc.proto/LobbyPlayer.display_name and LobbyRpc.LobbyPlayer.ext fields have been removed. Use LobbyRpc.proto/LobbyPlayer.player_info.display_name and LobbyRpc.LobbyPlayer.player_info.ext instead.
  • MatchCapacityRpc.StartMatchV1Request, MatchLifecycleRpc.CreateMatchV1Request, MatchmakingRpc.EnterMatchmakingForPartyV1Request have been updated to use PlayerInfoV2
  • PlayerSession has been updated to use pragma.account.DisplayName
  • Removed GetContentSha256ChecksumsV1Request/Response that was not used
  • pragma.PragmaCoreTestFactory.playerInfo moved to pragma.MatchmakingTestFactory.playerInfo and will need to be reimported if used in tests

Deprecation #

  • ReportCapacityV1Request/Response deprecated in favor of ReportCapacityV2Request/Response
  • MatchReadyV1Request/Response deprecated in favor of MatchReadyV2Request/Response
  • types.proto/DisplayName deprecated in favor of accountCommon.proto/DisplayName
  • matchLifecycleRpc.proto/PlayerInfo deprecated in favor of matchLifecycleRpc.proto/PlayerInfoV2
  • matchLifecycleRpc.proto/MatchData deprecated in favor of matchLifecycleRpc.proto/MatchDataV2

Pragma Engine 0.0.38 #

2021-10-05

Features #

  • New operator RPC for portal to access Stores, Game and Rewards catalogs.
  • Custom identity provider support added
  • Rich Inventory in UnitySDK featuring client side cache.
  • JWT token now contains more information related to a player identity, the new tokens are not yet used to validate with server
  • {{% variable “Pragma” “postman-GetLoginDataV1-name” %}} now contains additional Catalog data (updateEntries and craftingEntries)

Integration Notes #

  • The configuration of Discord authentication has changed very slightly. The block of configuration that used to live under serviceConfigs.DiscordIdProviderConfig now resides under pluginConfigs.AccountService.discordIdentityProvider. See 4-example-ext/config/CommonConfig.yml for an example.
  • New configuration is needed to enable Epic Online Services authentication.
social:
  pluginConfigs:
    AccountService.epicIdentityProvider:
      class: "EpicIdentityProvider"
  • New configuration is needed to enable Steam authentication.
social:
  pluginConfigs:
    AccountService.steamIdentityProvider:
      class: "SteamIdentityProvider"
      config: <-- configuration from old serviceConfigs.SteamIdProviderConfig -->

Deprecation #

  • InventoryV1Data field on LoginData has been deprecated. Use LoginData InventoryFullV1Data.
  • Removed InventoryV1Data inside LobbyPlayer. Affects LobbyStrategy plugin.
  • MatchLifecycleService.MatchEndV2Request deprecated in favor of MatchLifecycleService.MatchEndV3Request.
  • InventoryService.ItemUpdateV3 deprecated in favor of InventoryService.ItemUpdateV4.

Pragma Engine 0.0.37 #

2021-09-28

Features #

  • Rewards can be configured to return a ‘smooth’ distribution

Fixes #

  • Fixed intermittent test failures around the MatchLifecyleRpc.MatchEndV2/V3 endpoints

2021-09-28

Features #

  • UnrealSDK
    • Lobby Service
      • FPragmaLobbyData and FPragmaLobbyPlayer are now uobjects (names changed to U*) and can be accessed by blueprints.
      • Now keeps track of the most-recently-started GameId.
      • Now has overloads that return TFutures.
    • All Pragma struct members are now BlueprintReadOnly.
    • All Pragma structs have ==/!= operators generated.
    • Pragma::TComparison removed, use ==/!= operators.
  • A new operator RPC for creating UnsafeProvider (testing) accounts has been added

Integration Notes #

  • make run-with-config has been fully replaced by {{% variable “Pragma” “command-make-run” %}}
  • MatchProcessedV1Notification has been removed in favor of MatchProcessedV2Notification.
  • PlayerMatchEndProcessor.generateUpdatesForPlayer has been removed in favor of PlayerMatchEndProcessor.buildUpdatesForPlayer.
  • All settings files, including integration test settings files, must have their settings within the game: or social: nodes
  • The portal resources have been moved back into the engine jar; as a result, any pom.xml files generated for 5-ext will have to be manually updated.

Deprecation #

- None

Pragma Engine 0.0.36 #

2021-09-21

Features #

  • Integration tests can now specify a content directory
    • Specify the path in the call to BaseServerIT constructor. e.g. BaseServerIT(contentPath = "relative/path/to/content/from/ext/project")

Integration Notes #

  • Use {{% variable “Pragma” “command-make-protos” %}} instead of these removed aliases:
    • proto protobuf protobufs

Deprecation #

Pragma Engine - CatalogStackableEntries.json and CatalogInstancedEntries.json have been removed in 0.0.36.

Pragma Engine 0.0.35 #

2021-09-14

Features #

  • Default location for content is 5-ext/content
  • Default location for config is 5-ext/config
  • Run configs are checked in to help make debugging in IntelliJ more simple, and assume the new default locations for content and config.
    • Click on the Add Configuration… button in the IntelliJ toolbar, under Kotlin choose MainKt - LocalConfigured and click OK.
  • UnrealSDK:
    • Generated proto enum fields now have default initialized values.
    • Moved most Pragma tests out of the SDK itself to fix compilation failure with 4-example generated types.

Integration Notes #

  • Rename CatalogStackableEntries.json and CatalogInstancedEntries.json to StackableItemSpecs.json and InstancedItemSpecs.json, respectively.
  • Integration test default config files were renamed from InMemGame.yml to InMemGameIT.yml and InMemSocial.yml to InMemSocialIT.yml
    • If you use these yml files, ensure that the rename has been applied platform/5-ext/ext/src/test/resources/localDevelopmentShardConfig/ and preserves any custom settings
  • make run-with-config
  • 5-ext pom templates have changed. Merge template pom-xmls.templates into 5-ext/**/pom.xmls. The process for this will be:
    • Delete all the 5-ext/**/pom.xml files
    • Run make update-template
    • Use a diff tool like the one built into IntelliJ to restore local changes

Deprecation #

Pragma Engine - CatalogStackableEntries.json and CatalogInstancedEntries.json will be removed in 0.0.36 Pragma Engine - make run-with-config will be removed in 0.0.37

Pragma Engine 0.0.34 #

2021-09-07

Integration Notes #

  • Removed command line arguments social-configuration-filepaths and game-configuration-filepaths. These have been replaced with configuration-filepaths which support a unified configuration file format with a game: section and a social: section. Please refer to platform/TemplatePragmaConfig.yml as an example of the new unified format.
  • Need to merge template pom-xmls.templates into 5-ext/**/pom.xmls. The process for this will be to delete all the 5-ext/**/pom.xml and run make update-template, then use a diff tool like the one built into IntelliJ to restore local changes.

Pragma Engine 0.0.33 #

2021-08-31

Features #

  • Fixed a bug with the Multiplay Capacity Provider building the uuid parameter incorrectly
  • Fixed a bug where in a rare case, the platform would stop processing all incoming messages.
  • UnitySDK: Fixed a bug where the SDK was sending an extra character in the auth header that was ignored by previous versions of ktor.

Integration Notes #

  • Intellij IDE must be updated to at least 2021.2.1, and the Intellij Kotlin plugin updated to at least 1.5.21 (kotlin release notes)
  • The version of Kotlin has been updated to 1.5.21. This introduces a few deprecations:
    • toLowerCase() → lowercase()
    • toUpperCase() → uppercase()
    • capitalize() → .replaceFirstChar { it.uppercase() }
    • uncapitalize() → .replaceFirstChar { it.lowercase() }
    • .sumBy() → .sumOf()
  • The version of kotlinx-coroutines has been updated to 1.5.1. This introduces a few deprecations:
    • Channel.poll() -> Channel.tryReceive().onClosed { result -> if (result != null) throw result }.getOrNull()
  • The version of Ktor has been updated to 1.6.2. This introduces a few deprecations:
    • @KtorExperimentalAPI can be removed
    • httpClient calls will now throw a ClientRequestException exception when the request is not a 200 OK
  • Any references to KTor HeaderBuilder will need a suppression annotation added:
    • @Suppress("EXPERIMENTAL_API_USAGE_FUTURE_ERROR")

Deprecation #

  • generateAnyProto() has been removed from the test factory helpers. Use generateProto() instead (or create a tailored test factory for your proto)
  • The command line arguments social-configuration-filepaths and game-configuration-filepaths will be removed. Use configuration-filepaths instead. See platform/TemplatePragmaConfig.yml for an example of the new config file format.
  • The 3-apps/server module will be removed August 7.

Pragma Engine 0.0.32 #

2021-08-24

Features #

  • Content Data is now available to all plugins. This requires an update to the constructors of all plugins to conform to the new interface.
  • GetStoresV0 returns store data annotated with eligibility for the calling player. Eligibility considers both Store Entry requirements and consults a plugin that can access the player’s progression data.
  • UnitySDK: now supports automatic websocket reconnection with backoff. See new SdkConfig values for more info.
  • Bug fix: Match End now correctly enforces stackable costs of catalog updates.
  • Game and Social config file format have been merged into a single config format, see platform/TemplatePragmaConfig.yml for an example.

Integration Notes #

  • 3-extensions have been removed and 4-apps have been renamed to 3-apps. All custom and …ext proto files as well as any extensions defined in 3-extensions should now be defined in the 5-ext module.
  • Customers should continue to use make ext run can be used to just build and run changes in 5-ext
  • Due to the change in project structure, there may be some issues running within Intellij. After making the changes you may need to clear out your m2 directory and use the Invalidate Caches… option in the IDE (under File). Please reach out if you run into additional issues with the IDE.

Deprecation #

  • The command line arguments social-configuration-filepaths and game-configuration-filepaths will be removed. Use configuration-filepaths instead. See platform/TemplatePragmaConfig.yml for an example of the new config file format.

Pragma Engine 0.0.31 #

2021-08-17

Features #

  • Introduced InventoryRpc.ItemUpdateV4 and MatchendLifecycleRpc.MatchEndV3
  • MatchEndPlugin can be authored to enable rpc calls to arbitrary services on match end.
  • UnrealSDK
    • Update PragmaInventoryService to return full inventory snapshot on StorePurchaseV4, UpdateItemsV0, UpdateItemV3, UpdateItemV4
    • Oneofs allow nothing to be set for serialization or deserialization.
    • Code gen: Fix out of order dependencies when using maps.

Integration Notes #

  • UpdateItemsV0Request was updated to use inventoryRpc.ItemUpdateV2
  • MatchEndV0Request was updated to use matchlifecycle.MatchEndV2

Architecture Change #

  • 3-extensions will be removed and 4-apps will be renamed to 3-apps. All custom and …ext proto files as well as any extensions defined in 3-extensions will soon be defined in the 5-ext module.

Pragma Engine 0.0.30 #

2021-08-10

Features #

  • Login data includes purchase eligibility for store catalog that checks players’ payable and recipe requirements.
  • Unreal and Unity/C# SDKs
  • Rich LobbyService now handles and forwards MatchFailureV1Notification and GameStartFailureV1Notification.
  • Exposed LobbyServiceRaw::GameStartFailureV1Notification event.

Deprecation #

  • Removed storePurchaseV3 from inventoryRpc.proto should use storePurchaseV4.
  • Removed GetInventoryV1 from inventoryRpc.proto should use GetInventoryV2.
  • Removed ServiceGetInventoryV1 from inventoryRpc.proto should use ServiceGetInventoryV2.

Pragma Engine 0.0.29 #

2021-08-04

Features #

  • Authentication will now return information about error conditions specific to Discord auth failures.
  • LobbyService correctly sets ExtPlayerInfo on respondToLobbyInvite and createAndJoinLobby calls using the LobbyStrategy.setExtPlayerInfo

2021-08-03

Features #

  • UnitySDK: Fixed an issue where Connection.Connect() would fail after disconnection due to error.

Integration Notes #

  • ExtEnterMatchmakingV1Request no longer has a player_info in it. Instead use PlayerInfo in matchLifecycleRpc.proto.
  • StoreEntry has replaced requirements and catalog_ids_required_in_inventory with a new PurchaseRequirements that includes a new store.ExtPurchaseRequirements field.
  • This will be a breaking change to store content if entries reference the old fields
  • InventoryCommon.ItemUpdateV2 and InventoryCommon.ItemGrantV2 has been changed so internal instanced and stackable fields is a oneof

Deprecation #

  • Removed player_info from ExtEnterMatchmakingV1Request in matchmakingExt.proto.

Removed #

  • InventoryRpc.UpdateItemV2
    • Use InventoryRpc.UpdateItemV3
    • If using UE4 SDK, please use PragmaInventoryService.UpdateItemV3

Pragma Engine 0.0.28 #

2021-07-27

Features #

  • Unreal SDK
    • Now comes with a Rich Inventory SDK (PragmaInventoryService.h/cpp) that implements client side caching. Please see Inventory documentation to learn how to use the Rich Inventory implementation.
    • Fixed LogIn OnComplete never called if there’s an error in getting info/types data.
    • uint64 serializes to/from json string without losing precision.

Integration Notes #

  • MatchmakingStrategy.buildMatchmakingKey has been deleted; remove from strategy implementations
  • MatchmakingStrategy.buildExtPlayerInfo has been deleted; remove from strategy implementations
  • MatchmakingRpc.EnterMatchmakingV1 has been deleted; use MatchmakingRpc.EnterMatchmakingForPartyV1 instead
  • Proto Renames for Store
    • Store.UpgradeEntryStore.UpdateEntry
    • Store.ExtUpgradeEntryStore.ExtUpdateEntry
    • Rename CatalogUpgradeEntries.jsonCatalogUpdateEntries.json
  • All implementations of PlayerMatchEndProcessor must now implement buildUpdatesForPlayer, which provides a builder that exposes stats and ext fields

Deprecation #

Pragma Engine - DEPRECATED this release (Scheduled for removal in 0.0.30):

  • InventoryRpc.UpdateItemV2
    • Use InventoryRpc.UpdateItemV3
    • If using UE4 SDK, please use PragmaInventoryService.UpdateItemV3
  • InventoryRpc.StorePurchaseV3
    • Use InventoryRpc.StorePurchaseV4
    • If using UE4 SDK, please use PragmaInventoryService.StorePurchaseV4
  • InventoryRpc.GetInventoryV1
    • Use InventoryRpc.GetInventoryV2
    • If using UE4 SDK, please use PragmaInventoryService.GetInstancedItemsV1, PragmaInventoryService.GetStackableItemsV1
  • InventoryRpc.ServiceGetInventoryV1
    • Use InventoryRpc.ServiceGetInventoryV2

Removed #

  • InventoryRpc.SimulateRewardsV1
    • Use InventoryRpc.SimulateRewardsV2

Pragma Engine 0.0.27 #

2021-07-13

Features #

  • Unreal SDK now supports protobuf oneofs.
  • Service Name, Node ID and Instance ID are no longer part of metrics tags
    • Datadog charges per combination of unique tags. This scales down the total number of combinations
  • Healthcheck endpoint now available on the operator gateway at /v1/healthcheck
    • Will respond with a 503 until the services are initialized, then a 200 forever thereafter

Integration Notes #

  • SDK generated files are no longer included in the Pragma release.
    • You should be running the make gen-sdk-types-unreal4/unity after integrating release anyway so this probably won’t affect you except that you should no longer see useless merge conflicts in the generated files.

Pragma Engine 0.0.26 #

2021-07-06

Features #

  • Now supports OAuth PKCE security when authenticating with Discord. Pragma now accepts the code_verifier and passes it along to Discord to obtain a token.
  • MatchEndMetrics now accept optional as a list
    • Tags list expects format of key, value pairs. Compatible with datadog tags. Expects even number of entries
    • Example - [ "region", "na", "server", "1.2.3" ]
    • Note for datadog users: each unique combination of tags are indexed separately and therefore billed separately, so be judicious with your tag usages.
  • Unreal SDK Code Gen:
    • Fixed an issue causing some messages with the same name as a message in another package to not be included in the final output.

Pragma Engine 0.0.25 #

2021-06-29

Features #

  • C# SDK supports Promise/Futures (non-yieldable).
  • Unity/C#
    • Added rich lobby implementation in LobbyService. We recommend using this instead of the Raw API!
    • DisplayName and Discriminator are available in AccountService after logging in.
    • Added MatchFailureV1Notification Raw event.

Integration Notes #

  • UnrealSDK LobbyService:
    • Fixed crash when sending notification that player joined lobby.
    • Fix debug server adding a stray requestId to the types response that showed up as a missing type warning.

Deprecation #

Pragma Engine - DEPRECATED this release (Scheduled for 0.0.27):

  • InventoryRpc.ServiceGrantRewardsV1Request/Response
    • Use InventoryRpc.ServiceGrantRewardsV2Request/Response
    • InventoryDeltaV2Data is now used instead in the new response

Pragma Engine 0.0.24 #

2021-06-22

Improvements #

  • Fixed a bug where Players were getting invites from “Unknown”

Pragma Engine 0.0.23 #

2021-06-15

Pragma Engine Heads up! We’re landing the big Pragma package rename and several deprecations in version 0.0.23. Not to fear; a Pragma engineer will help you with this migration. We will schedule time to help you with this.


Features #

  • Converted match making strategy into plugin to provide greater configuration support and extensibility
  • Improved error messages when authenticating Discord Unverified users
  • Added support for stackable item grants to match end payload
  • Unity SDK
    • New yield-able Promise/Future interface for RPCs. No more callback hell!
  • Unity/C# SDKs
    • Raw services can now be accessed directly from Session.GetService()
    • [Protocol] logs now print with more info e.g. [Game WebSocket]
    • Added MatchCapacity and MatchLifecycle Raw services.
    • Fixed128s now print as UUID strings in logs instead of msb/lsb json objects.

Improvements #

Pragma Package Rename!

  • Old convention:
    • Inconsistent file names and object locations
    • Frequently repeat names in multiple places such as:
      • pragma.lobby.lobbyServicePB.proto
      • pragma.lobby.CreateAndJoinLobbyV1Request
      • Note lobby in package, file name, and method name.
    • Inconsistent location
  • New Standard:
    • PingRpc.proto
      • Eg. PingRpc.PingV1Request
      • rpcs go here
      • Includes factored out / shared types
      • It’s okay to reference content protos
    • PingRpcExt.proto (java separate files mode)
      • PingRpcExt.ExtPingRequest
      • use Ext on the front of the name
    • PingContent.proto
      • content data goes here
    • PingContentExt.proto
      • PingContentExt.ExtSomePingContentDataType
    • Ping.proto
      • Live data related protos go here (eg. custom player data types, inventory types)
    • Proto package namespacing should match the service namespacing
      • Eg. pragma.ping
      • No group services into subpackages
        • Except for example
        • The ‘match’ subpackage will be flattened
    • Preserve (or refactor) current pragma.core
      • Eg. types.proto is good as-is

Integration Notes #

Pragma Package Rename

  • any protos using gg.pragma.core.Fixed128 type should use import "pragma/types.proto";
  • and replace message types from gg.pragma.core.Fixed128 example_proto = 3; to Fixed128 example_proto = 3;
  • the folder structure no longer is using /gg/pragma/*. All files should be moved to a /pragma namespace/folder instead
  • change all imports from using gg.pragma.* to use pragma instead
  • Will need to close the Intellij IDE, delete the maven .m2 repo cache for /gg/pragma, run a make clean build and restart the IDE and reload Maven Projects
  • gg.pragma.game, gg.pragma.core, gg.pragma.social, gg.pragma.protobuf and gg.pragma have all been combined into pragma
  • pragma.match.lifecycle has been combined into pragma.matchlifecycle
  • pragma.match.capacity has been combined into pragma.matchcapacity
  • Folder structures match package structure much more closely
  • Unity SDK replaces Pragma.Core, Pragma.Game, Pragma.Social with Pragma
  • Unreal4 SDK replaces EPragma_Core_* with EPragma_*

Deprecation #

Pragma Engine - REMOVED in 0.0.23:

  • Inventory.upgradeItemV1
    • Use Inventory.updateItemV2
  • Inventory.updateItemV1
    • Use Inventory.updateItemV2
  • Inventory.storePurchaseV2
    • Use Inventory.storePurchaseV3
  • PlayerMatchEnd.stackable_updates
    • Use item_updates
  • MatchEndPlayerData.instancedGrants
    • Now included in Inventory.ItemGrants
  • MatchLifeCycleServicePB.MatchFoundV1Notification
    • Should already be using MatchLifeCycleRpc.MatchConnectionDetailsV1Notification

Pragma Engine 0.0.22 #

2021-06-08

Features #

  • Multiplay capacity provider support
  • UnrealSDK
    • LobbyService
      • Fixed an issue where accepting an invite would ignore the next details update.
      • Fixed an issue where after creating a lobby the first details update would not fire events.
      • Non-packaged builds could crash after exiting play mode when using the rich LobbyService impl.
      • Cleaned up disconnect messaging so it only prints once, and only as an error if it’s actually an error.
      • Fixed an issue where LobbyData was not cleaned up on disconnect.
  • Unity/C#
    • We now have a non-unity C# SDK!
    • Fixed a bug where failed UpdateBackendConfig would never call OnComplete callback (e.g. on Logging in).
    • Fixed a bug where failed Http message responses would never fire the response callback.
    • Can now opt-into using Http for all platform calls such as on a game server with no websocket connection. (Note: notifications not supported in this mode)
      • Set SdkConfig.protocolType to ProtocolType.Http
  • Logged in users metric is now more accurate
    • HTTP sessions are expired are a configurable timeout, therefore will no longer permanently pollute the logged in users metric

Improvements and Fixes #

  • CLI command for standalone db migration functionality is restored

New or Updated RPCs #

  • MatchEndV2Request
    • PlayerMatchEnd.itemUpdates - update stackables and instanced items
  • MatchProcessedV1Notification - Inventory Delta tags field is now populated for all inventory types (previously only populated for stackables)
  • UpdateItemV2
    • Replaces upgradeItemV1 and updateItemV1
    • Uses the same list of ItemUpdate objects from MatchEnd
  • UpdateItemsV0 - plural form of UpdateItemV2 to update items in bulk.
  • OperatorGrantRewardsV0 - operator endpoint that directly grants RewardGrant(s) to a playerId for testing and player support
  • StorePurchaseV3 - uses new standard formatted params comparable to UpdateItemV2 etc.

Integration Notes #

  • LobbyStrategy.buildExtensionMatchmakingRequest (returns a pair of values, an ExtensionEnterMatchmakingV1Request and a MatchmakingKey) has been deleted, in favor of the following two functions:
    • LobbyStrategy.buildExtensionEnterMatchmakingV1Request
    • LobbyStrategy.buildMatchmakingKey
    • Note: extLobbyInfo (the parameter for the previous call) is available from lobbyModel.extLobbyInfo
  • InstancedDataProviderPlugin.newInstanced() was updated to take the full Catalog.InstancedEntry instead of just the catalogId for the new instanced item.

Deprecations #

  • Inventory.upgradeItemV1
    • Use updateItemV2
  • Inventory.updateItemV1
    • Use updateItemV2
  • MatchFoundV1Notification
    • Use MatchConnectionDetailsV1Notification
  • PlayerMatchEnd.stackable_updates
    • Use item_updates

Removed #

  • Catalog.InstancedEntry.instance_defaults replaced by ExtensionInstancedEntry.ext
  • Removed (were unused)
    • StackableEntryUpdate
    • InstancedEntryUpdate
    • InventoryUpdateV1Notification
  • Removed in favor of new variants
    • MatchEndV1Request
      • Use MatchEndV2Request
    • MatchEndV1Notification
      • Use MatchEndV2Notification
  • UnrealSDK
    • UPragmaConnection::OnDisconnected
      • Use UPragmaConnection::OnDisconnectedV2.
    • TPragmaResult::UnknownErrorCode.
      • Use FPragmaError::UnknownError.

Pragma Engine 0.0.21 #

2021-06-04

Features #

  • Expose extension data on MatchEndNotification

2021-06-01

Features #

  • Add ability to update instanced inventory on match end.
    • See InstancedItemUpdate and InstancedDataProviderPlugin.update

Deprecation #

Pragma Engine - Scheduled for REMOVAL in 0.0.22:

  • Protos to be deleted since they are unused
    • StackableEntryUpdate
    • InstancedEntryUpdate
    • InventoryUpdateV1Notification
  • Protos deprecated because a new version is available
    • MatchEndV1Request
    • MatchEndV1Response
    • MatchEndV1Notification
    • MatchEndPayload
    • PragmaMatchEndData
    • PragmaPlayerMatchEndData
  • UnrealSDK
    • UPragmaConnection::OnDisconnected. Please use UPragmaConnection::OnDisconnectedV2. Pragma Engine - DEPRECATED this release (Scheduled for removal in 0.0.23):

    • TPragmaResult::UnknownErrorCode. Please use FPragmaError::UnknownError.

  • StorePurchaseV2 deprecated
  • PlayerMatchEnd.stackable_updates to be replaced by PlayerMatchEnd.item_updates

Pragma Engine 0.0.20 #

2021-05-26

Features #

  • Unity SDK
    • All Game Data Service Player RPCs and Notifications
      • MatchProcessedV1Notification
    • All Inventory Player RPCs - can be found in inventoryServicePb.proto
  • Matchmaking
    • Added basic warm body matchmaking strategies
      • OneVsOneWarmBodyMatchmakingStrategy
      • FreeForAllWarmBodyMatchmakingStrategy
      • ThreePlayerCooperativeWarmBodyMatchmakingStrategy
      • ThreeVsThreeWarmBodyMatchmakingStrategy

Pragma Engine 0.0.19 #

2021-05-25

Features #

  • Game server metrics support
    • MatchEndV2 supports new metrics field
    • MatchEndV2 has improved names and structure
  • Instanced Items run initialization plugin in all cases, including
    • Match End Grants
    • Rewards
    • Store Purchase
  • Unity SDK
    • All RPCs defined in the Lobby service are now available through the Raw API.
  • Unreal SDK
    • Added a full, stateful Lobby implementation accessible via Session().LobbyService()
      • Enable by adding the following to your DefaultGame.ini:
        • [/Script/PragmaSDK.PragmaLobbyService]<br />bEnabled=true
    • Raw api services can now be accessed directly via Session::GetService() (Session.Account().Raw() style is still available though).
    • PragmaResult now has an Error() method that gets the error (if IsFailure is true) as a new type FPragmaError which encompasses new platform & sdk error enums.
    • Protocol internals now use TUniqueFunction instead of TFunction (Can now MoveTemp into Raw methods lambda captures).
      • Eliminated an excess copy when passing delegates to Raw methods.
      • TPromise/TFuture can be used more cleanly with Raw methods as you can now MoveTemp(TPromise) into a Raw method lambda.
    • Add SessionService which contains logic for logout and session attributes.
      • SessionService().DisconnectV1() method.
        • The method will call RequestLogoutV1 on both connections.
        • Calls callback once both connections have closed.
      • SessionService().GetAttribute
        • Used to retrieve current Session attributes.
      • SessionService().GetAttributeChangedDelegate
        • Used to watch for SessionAttribute changes.
      • Currently the only Session Attribute is the Game LobbyId.
    • Added opt-in compile-time deprecation warnings
      • To enable, in your Project.Build.cs add PrivateDefinitions.Add("PRAGMASDK_ENABLE_DEPRECATION_WARNINGS");

Deprecation #

  • REMOVED this release: Pragma Engine - Scheduled for REMOVAL in 0.0.21:

    • N/A Pragma Engine - DEPRECATED this release (Scheduled for 0.0.22):

    • InstancedEntry.instance_defaults to be replaced by ExtensionInstancedEntry.ext

    • Protos to be deleted since they are unused

      • StackableEntryUpdate
      • InstancedEntryUpdate
      • InventoryUpdateV1Notification
    • Protos deprecated because a new version is available

      • MatchEndV1Request
      • MatchEndV1Response
      • MatchEndV1Notification
      • MatchEndPayload
      • PragmaMatchEndData
      • PragmaPlayerMatchEndData
    • UnrealSDK

      • UPragmaConnection::OnDisconnected. Please use UPragmaConnection::OnDisconnectedV2.
      • TPragmaResult::UnknownErrorCode. Please use FPragmaError::UnknownError.

Pragma Engine 0.0.18 #

2021-05-18

Deprecation #

  • REMOVED this release:
    • make.ps1 script removed

    • Content Data is no longer loadable as an embedded artifact Pragma Engine - Scheduled for REMOVAL in 0.0.19:

    • storePurchaseV1 RPC is removed Pragma Engine - DEPRECATED this release (Scheduled for 0.0.20):

    • N/A

    • InstancedEntry.instance_defaults to be replaced by ExtensionInstancedEntry ext

Pragma Engine 0.0.17 #

2021-05-11

Features #

  • Steam Identity Provider
    • Platform support for Steam identity provider
    • Unreal SDK support for Steam provider
    • Steam ID Provider

Deprecation #

  • REMOVED this release:

    • None Pragma Engine - Scheduled 0.0.18
  • Will be REMOVED next release:

    • make.ps1 script
    • `storePurchaseV1 RPC Pragma Engine - Scheduled 0.0.19
  • DEPRECATED this release:

    • Content Data will no longer be loadable as embedded artifact

Pragma Engine 0.0.16 #

2021-05-04

Features #

  • Unreal SDK
    • Extension services should now live outside of the SDK and register with Session::RegisterService instead of being added to PragmaExtensionServices.h.
    • New SDK update script: sdk/unreal4/update-pragma-sdk.sh.
      • See script for configuration details.
    • UPragmaConnection::ConnectionError renamed to UPragmaConnection::FConnectionError
    • PragmaSdkConfig has a UserData field that can be used to pass arbitrary data using the existing Pragma.ini flow at deploy-time.
  • Infrastructure
    • Support for deploying game server binary to a shard.
      • New buildkite pipeline that pulls from an s3 bucket.
      • dev-shard-deploy.sh updated to use a local binary.
      • New script upload-game-server.sh which simplifies uploading a game server to the s3 bucket.

Deprecation #

Pragma Engine - DEPRECATED this release (will be removed in release 0.0.18):

  • make.ps1 script
  • storePurchaseV1 RPC

Pragma Engine 0.0.15 #

2021-04-27

Features #

  • Content data is now exclusively loaded externally from the jar from a supplied folder
    • See the Execution section in README.md
    • For the most up-to-date command-line arguments, you can look in: platform/4-apps/server/src/main/kotlin/gg/pragma/LocalApplication.kt
  • Unreal SDK
    • UPragmaMatchCapacityService has a new method ReportCapacityUntilMatchAllocated for use in the Local Process and Multiplay server flows.
    • New helper object UPragmaMultiplayConfig which can be used to automatically scan for Multiplay-specific server.json configuration.

Improvements #

  • UpgradeItemV1
    • Returns full inventory snapshot in response rather than partial
  • New service error provided when gateway is unable to route a request
    • Client will receive FailedToRoute error instead of UNKNOWN_ERROR
  • Unreal Game Server
    • Unreal Example project includes support for packaging a game server stub that reports capacity and simulates a match loop.
    • This provides an example that demonstrates an end-to-end game loop.

Pragma Engine 0.0.13 #

2021-04-20

Improvements #

  • Reduced log output on build and run by default to reduce noise
    • Existing logs are still available under the Debug logger, which can be enabled through the log config

Infrastructure #

  • Build / CI
    • Buildkite pipeline will conditionally perform build steps based on whether changes were made for a particular step. These are:
      • Platform code
      • Content data (produces independently versioned artifact)
      • Web Portal

Pragma Engine 0.0.7-0.0.12 #

2021-04-13

Features #

  • StorePurchaseV2
    • Support instanced item initialization w/ plugin
  • UpgradeItemV1
    • Support instanced item exchange + mutation w/ plugin
  • Load Content Data externally
  • Service supports shutdownService hook for graceful shutdown steps

Improvements #

  • Docker dev env support
  • Adding build flags to make build (clean vs incremental, run-tests vs skip-tests, verify vs install)

Infrastructure #

  • Pragma build + versioned artifacts
  • Platform artifact version convention
    • WIP between releases
    • Git hash in the version string
  • Platform deploy to shard

Pragma Engine 0.0.5 #

2021-03-23

Features #

  • Plugin support
    • Configurable
    • Plugin Config printed in startup summary
  • DataDog metrics provider
    • Expose metrics that can be picked up and graphed in datadog
  • Retrieve logs directly from Pragma service endpoint
    • Pass in number of lines to retrieve
  • Standard Game Loop
    • Full support for Lobby → Matchmaking → Match Allocation → Match End

Improvements #

  • Removed kotlin test and junit packages in favor of junit 5.
  • Reduced output from build logs
  • Inventory and Rewards service load content data during startup, which will cause Pragma to fail to startup if they are missing or incorrectly formatted.
  • Parameterized user for logging into ec2 hosts

Pragma Engine 0.0.3 #

2021-03-09

Features #

  • GameData service
    • Serves aggregated login data
    • Serves aggregated player match results
  • Terraform aws environment
    • Bootstrap
  • Linux automated dev env setup
  • Makefile
    • Shows help by default
    • Help has descriptions and is formatted nicely

Pragma Engine 0.0.2 #

2021-03-02

Features #

  • Platform startup summary

    • Human readable startup summary Pragma Engine - format is 0.0.0-githash
  • New Platform version property

    • The patch version will be incremented during each Pragma weekly release
    • Version can be retrieved in the following locations:
      • Web Portal
      • /v1/info (on all gateways)
  • Postman collection updates

    • /v1/Info calls available for all gateways
    • /v1/types endpoint now filters only relevant rpc calls
  • SDK Disconnect

    • Disconnect events now include an Error Enum
  • GetContentSha256ChecksumsV1Request

    • Retrieve OS aware sha256 hash of content data that can be used to quickly check content versions