March 2, 2023

Features #

[Game Flow] New Matchmaking Plugin method endLoop allows for custom code to be injected after each matchmaking loop. #

Description: The new Matchmaking Plugin method endLoop is now invoked after each matchmaking loop. This makes it possible to add custom logic, such as the functionality to start a Potential Match early even if it fails to make an ideal match.

Related note: See docs note on endLoop.

[Game Flow] Leaving a party or kicking a player from a party removes the entire party from matchmaking. #

Description: This change was made to keep matchmaking and party player membership in sync.

[Game Flow] Match reconnect can now be set as optional for players. #

Description: Operators can now configure game flows to allow for optional match reconnect. If configured, game clients can invoke DeclineReconnect to leave the existing match when they disconnect.

Details:

• New Player endpoint: DeclineReconnectV1

  Unreal

  bool UPragmaPartyService::CanDeclineReconnectV1() const
  
  bool UPragmaPartyService::CanDeclineReconnectV1(FPragmaError& OutError) const
  
  TFuture<TPragmaResult<>> UPragmaPartyService::DeclineReconnectV1()
  
  void UPragmaPartyService::DeclineReconnectV1(const FOnCompleteDelegate& OnComplete)
  

  Unity

  public bool CanDeclineReconnectV1()
  
  public bool CanDeclineReconnectV1(out Error? error)
  
  public Future DeclineReconnectV1()
  
  public void DeclineReconnectV1(CompleteDelegate onComplete)
  

• New Partner notification that can be subscripted via engine-specific events: PlayerDeclinedReconnectV1Notification

  Unreal

  FPlayerDeclinedReconnectEvent UPragmaMatchLifecycleService.OnPlayerDeclinedReconnectEvent;
  

  Unity

  public event Action<PragmaId, PragmaId> MatchLifecycleService.OnPlayerDeclinedReconnect;
  

• New Match Lifecycle service configuration option: matchReconnect can have the values OFF, OPTIONAL, or REQUIRED.

[Player Data] UpdateEntryId is now an optional field when making instanced item update calls. #

Description: You can now call instanced item update without needing a placeholder for the update entry. ServerInstancedItemUpdate and InstancedItemUpdate no longer require you to assign an UpdateEntryId.

Examples: The following are examples of instanced item update calls without UpdateEntryId:

FPragma_Inventory_InstancedItemUpdate{*InstanceId}

var instancedItemUpdate = new InstancedItemUpdate {InstanceId = instancedId}};

"payload": {
        "itemUpdate": {
            "instanced":
            {
                "instanceId": "<items-instance-id>"
            }
        }
    }

[Player Data] Items that do not correspond to a valid catalogId will no longer show up in a player’s inventory. #

Description: The Inventory service now filters out items that do not have a corresponding catalogId defined by instanced and stackable content specs. This filtering prevents runtime errors that occurred on retrieval when a catalogId check was happening.

If you want to load items in the database with invalid catalogId, assign and set legacyItemLoadBehavior: true in the Inventory service config, though this may result in runtime errors.

[Player Data] The Instanced Item Plugin’s newInstanced() and update() functions can now access a player’s inventory before and during an RPC call. #

Description: The Instanced Item Plugin’s functions have been updated with one new and one renamed parameter. This enables player inventory access for instanced item modifications before the call runs, as well as a view into the item logic that would be committed to the database once the engine processes the call’s request.

Related note: See integration note to update the Instanced Item Plugin.

[Infra & Tooling] New configuration validation process checks configs and outputs errors. #

Description: Pragma Engine now validates configuration files and provides detailed explanations of any issues. This new config validation process means the engine will catch issues, prevent bad configs from being used, and provide meaningful guidance for resolving errors. This validation runs both when you build, and when you dynamically change a config for an actively running backend.

Related note: See integration note for config validation.

[Infra & Tooling] Version information on all gateways can now be viewed using the new /v1/healthcheck. #

Description: /v1/healthcheck can be used to monitor nodes that don’t necessarily run frontend gateways. The following are /v1/healthcheck responses and their associated JSON payloads:

• 200: Health of node is ideal.

{"isHealthy":true,"version":"DEFAULT-0.0.91-WIP-a5bb265-dirty","platformVersion":"local-dev","portalVersion":"local-dev","contentVersion":"local-dev","configVersion":"local-dev"}

• 503: Health of node is not ideal. Note that "isHealthy": false is currently used during startup to indicate that not all services are running yet.

{"isHealthy":false,"version":"DEFAULT-0.0.91-WIP-a5bb265-dirty","platformVersion":"local-dev","portalVersion":"local-dev","contentVersion":"local-dev","configVersion":"local-dev"}

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

[SDKs] Added rich bindings for PlayerLeave. #

Description: The rich Match Lifecycle service on the PragmaSession now has PlayerLeave functions for both Unity and Unreal.

[SDKs] SDK code generation now supports the proto3 optional field attribute. #

Description: The proto3 optional field is now supported. This allows the SDK to support messages that recursively reference themselves. You can also now check for the existence of optional fields.

Example:

// Given a MyData field called "Data"
bool b = Data.SomeInt.HasValue(); // Check that the field has a value set.
Int x = Data.SomeInt.Value(); // Get the value.
Data.SomeInt.SetValue(42); // Set the value.

// Given a MyData field called "Data"
bool b = Data.SomeInt.HasSomeInt; // Check that the field has a value set.
int x = Data.SomeInt; // Get the value. Note this will return default if not set.
Data.SomeInt = 42; // Set the value.

message MyData {
  optional int32 some_int = 1;
}

[SDKs] SDK code generation now supports messages that recursively reference themselves. #

Description: Messages can reference themselves in their own fields or in sub-message fields. Fields involved in cyclic references must be marked optional or repeated.

Example: The following code block shows message A referencing itself both in its own field and in message B, which is a sub-message of A.

message A {
  optional A = 1;
  optional B = 2;
}

message B {
  repeated A = 1;
}

[SDKs] BackendAddress and ProtocolType can now be specified separately for client and server. #

Description: Pragma SDK running on a game server now uses the new config fields PartnerBackendAddress and PartnerProtocolType. These fields can be overridden via command line parameters: -PragmaPartnerBackendAddress="http://127.0.0.1:10100" -PragmaPartnerProtocolType="Http". If the PartnerBackendAddress field is empty, BackendAddress will be used instead.

[SDKs] The Inventory service now supports item lookups by catalogId and instanceId. #

Description: You can now look up items by catalogId and instanceId instead of iterating through the list on InventoryResults.InventoryFull using the two new functions GetInstancedItemsByCatalogId and GetStackableItemsByCatalsogId.

Example: The following are the two new item lookup functions in PragmaInventory.Service:

var itemsWithCatalogIdLookup = PragmaInventory.Service.GetInstancedItemsByCatalogId("<<catalog-id>>");

var itemWithInstanceIdLookup = PragmaInventory.Service.GetInstancedItemByInstanceId("<<instance-id>>");

[SDKs] Game servers now connect to Pragma Engine over WebSocket by default. #

Description: The default PartnerProtocolType for Pragma SDKs is now WebSocket instead of HTTP. If you prefer HTTP, you can override this behavior with the command line parameter -PragmaPartnerProtocolType="Http" or via the config field PartnerProtocolType according to your engine.

[Portal] The new Portal is now available! #

Description: The new Portal has better extensibility, clearer separation of customer data, and a simplified configuration. New capabilities include:

• Update and extend existing pages and portlets with components, pages, and actions.
• Use flags to toggle features with the featureToggles option.
• Define custom rendering components for ext data in content and inventory.
• Use the <Icon /> component to access 400+ new icons and add custom icons.
• Leverage the new Less support across the entire Portal; all .less files are loaded and compiled automatically.

Related note: See integration note about custom content in Portal.

[Portal] Portal shows how much time remains before an event begins or ends. #

Description: You can now see the amount of time remaining before events start or end when viewing scheduled events in the Portal. This information is shown in a new Status column.

The Events table can be seen in the Social Portal → Services menu → Game Title Management → Shards → Select a shard, then scroll down to the Events table.

Deprecations #

[Game Flow] The MatchLifecycleServiceConfig.enableMatchReconnect boolean config has been deprecated in favor of the MatchLifecycleServiceConfig.matchReconnect enum config. #

Description: The MatchLifecycleServiceConfig.matchReconnect config will support an upcoming feature. The existing enableMatchReconnect config is scheduled to be removed in Pragma Engine release 0.0.92. To migrate early, make the following replacement in your config file:

[SDKs] Sessions are changing. #

Description: PragmaSession has been split into Player and Server objects that provide a more relevant subset of the API based on their respective use cases.

• See the Unreal and Unity SDK API v2 migration guide in the shared Google Drive for more details.
• The existing implementation of PragmaSession is now deprecated and will be removed in a future release.

Integrations #

[Game Flow] Move the Match Reconnect config to its new location in the MatchLifecycleServiceConfig. #

Description: Match Reconnect now handles connections that were forcibly disconnected on the client side. The configuration for turning on Match Reconnect has been moved to the MatchLifecycleServiceConfig.

Integration step: Move the Match Reconnect config to its new location. Be sure to remove it from the existing location.

• Before:

game:
  core:
    session:
      enableMatchReconnect: true

• After:

game:
  serviceConfigs:
    MatchLifecycleServiceConfig:
      enableMatchReconnect: true

Related note: See bugfix note on client reconnects.

[Game Flow] Replace usages of the partyStartMatch Test Factory method with startMatch. #

Description: This helper has been removed as part of the post-Lobby service cleanup.

Integration step: Replace usages of the following Test Factory method in Game Loop.

[Game Flow] If you’re using the listed MatchLifecycleServiceConfig properties, you’ll need to update references to reflect their renames. #

Description: We’ve renamed several config properties for the Match Lifecycle service to be more clear. Note that these are optional properties, so if you’re not using them, no action is required.

Integration step: Update references to the following renamed config properties.

Example: Below is an example of the new Match Lifecycle service config using all the new property names.

game:
  serviceConfigs:
    MatchLifecycleServiceConfig:
      enableMatchAbsoluteTimeout: true
      matchAbsoluteTimeoutMillis: 10000000
      enableKeepAlive: true
      keepAliveIntervalMillis: 30000
      keepAliveMissesLimit: 3

[Game Flow] If you have custom code referencing SessionServicePB or Session, update them to their new names. #

Description: To improve the structure of Pragma Engine and to keep components understandable, we’ve renamed a few Session-related protos and services.

Integration step: After rebuilding protos and sdk-types, check custom code for references to the following Session calls and update them to their replacements:

[Game Flow] If your game server implementation uses the MatchReady call, generate an ExtPlayerMatchDetails object for each player. #

Description: Game server implementations that use the MatchReady call must provide ExtPlayerMatchDetails for each player. This change was made to detect missing ExtPlayerMatchDetails. If the game server provides fewer ExtPlayerMatchDetails than the required number of players as defined by the ReportCapacity response, it will throw a MatchLifecycle_MissingPlayerExt error.

Integration step: In your game server’s response handling for MatchCapacity::StartReportCapacityPolling, while creating the MatchReady request, an ExtPlayerMatchDetails object must be generated with the playerId for each player. These objects must then be put on the MatchReady request before calling MatchLifecycle.MatchReadyV2.

[Game Flow] If you’re using the listed Party service helper functions, update them to their new names. #

Description: We’ve renamed the getParty and getBroadcastParty proto helpers on the Party service to be more accurate.

Integration step:

[Game Flow] If you have a custom implementation of the Matchmaking Plugin, update references to PotentialMatch, ActiveMatch, and MatchableParties to be consistent with new locations and names. #

Description: Studios using custom implementations of the Matchmaking Plugin will need to update the class references, as the interface for the plugin has been changed with new types. These changes were made to be more readable and prevent the usage of restricted properties and functions. Changes have been made to the locations of ActiveMatch and PotentialMatch, and to the name of MatchableParties.

Integration steps: If you have a custom implementation of the Matchmaking Plugin, you will need to complete the following steps.

• Change the MatchableParties type to Matchable, and update any related imports as necessary.
• Update any references to PotentialMatch and ActiveMatch, as they’ve been moved into a new folder.
• If you were using a function or property that is now unavailable, reach out to your Pragma support representative to find alternate strategies using approved functions.

[Player Data] If you’re using the Instanced Item Plugin, update newInstanced()’s and update()’s parameters. #

Description: We’ve added in a new parameter called pendingInventory and renamed an existing parameter initialInventory in the Instanced Item Plugin’s newInstanced() and update() functions.

Integration steps:

• Add the parameter pendingInventory to both newInstanced() and update().
• Rename the parameter initialInventory with startingInventory to both newInstanced() and update().

Example: Below is an example of the Instanced Item Plugin with the updated parameters:

interface InstancedItemPlugin {

fun newInstanced(
    instancedSpec: InventoryContent.InstancedSpec,
    inventoryContent: InventoryServiceContent,
    startingInventory: InventoryData, // RENAMED from initialInventory
    pendingInventory: InventoryData, // NEW parameter
    clientRequestExt: ExtPurchaseRequest?,
    serverRequestExt: ExtInstancedItemServerGrant?
): InstancedItemPluginResult

fun update(
    initialInstancedItem: InstancedItem,
    instancedSpec: InventoryContent.InstancedSpec,
    updateEntry: InventoryContent.UpdateEntry,
    inventoryContent: InventoryServiceContent,
    startingInventory: InventoryData, // RENAMED from initialInventory
    pendingInventory: InventoryData, // NEW parameter
    clientRequestExt: ExtInstancedItemUpdate?,
    serverRequestExt: ExtInstancedItemServerUpdate?
): InstancedItemPluginResult
}

Related note: See feature note on updates to the Instanced Item Plugin.

[Infra & Tooling] Replace usages of /v1/info version information with /v1/healthcheck. #

Description: Version information is no longer available on /v1/info, as it has been moved to the new /v1/healthcheck.

Integration step: Replace any dependency on /v1/info version data with /v1/healthcheck.

[Infra & Tooling] You may need to check your config files for stale or unused configs to successfully pass the new config validation step. #

Description: As part of the new config validation feature, stale or broken configs that were previously ignored will now cause the engine to prevent startup and generate an error.

Integration step: Check your config files for stale, unused configurations from before Pragma Engine began validating. These will need to be removed.

Related note: See feature note on config validation.

[Infra & Tooling] If you’re using the SystemProxy class, reimplement it as it’s been deleted. #

Description: The old SystemProxy class is no longer in use by Pragma Engine and has been deleted. If you’re using this class in custom code, you’ll need to reimplement it.

Integration step: Please contact us for support for reimplementing the SystemProxy class.

[SDKs] Unreal: If you had manual HTTP implementations for game servers in any custom services, replace these with the new macros. #

Description: The Unreal game server now supports WebSocket connections. Any custom service that previously utilized manually created functions for the Http() handler can now make use of the prebuilt macros.

Integration steps:

• Locate custom service code that directly invokes HTTP connections to Pragma.
• Replace code with usage of an appropriate binding of the correct IMPL_PRAGMA_[BACKEND]_METHOD macro, where [BACKEND] should be replaced with SOCIAL or GAME.

Example:

• Before:

void UPragmaMatchLifecycleServiceRaw::MatchReadyV2(
 const FPragma_MatchLifecycle_MatchReadyV2Request& Request,
 TUniqueFunction<void(TPragmaResult<FPragma_MatchLifecycle_MatchReadyV2Response>, const FPragmaMessageMetadata&)>
 Callback) const
{
 Connection().Http(EPragmaBackendType::Game).SendMessage(Request, MoveTemp(Callback));
}

• After:

IMPL_PRAGMA_GAME_METHOD(UPragmaMatchLifecycleServiceRaw, MatchReadyV2, FPragma_MatchLifecycle_MatchReadyV2Request,
FPragma_MatchLifecycle_MatchReadyV2Response, FMatchReadyDelegate);

[SDKs] Unreal: Rename the listed types. #

Description: As part of Core SDK cleanup, some type names have changed.

Integration step: Find and rename the following types:

[SDKs] Unreal: Update your Init method in custom services to take new parameters. #

Description: As part of Core SDK cleanup, the Init method of custom services now takes new parameters.

Integration step: Make the following replacement:

[SDKs] Unreal: Complete the listed integration steps to enable a workaround for packaging standalone Unreal game builds. #

Description: To enable packaging standalone Unreal game builds, you must complete the integration steps.

Integration steps:

1. Open the pragma-engine/sdk folder.
2. Find PragmaInventoryCache.cpp and remove #include "BehaviorTree/BTCompositeNode.h".
3. Find PragmaCore.cpp and comment out PRAGMA_LOG(Error, "Failed to load Pragma Core shared library.");.
4. Run the update-pragma-sdk.sh script.
5. Rebuild your Unreal game project to enable packaging projects from Unreal Editor.

[SDKs] Unity: Update your Init method in custom services to take new parameters. #

Description: As part of Core SDK cleanup, the Init method of custom services now takes new parameters.

Integration step: Make the following replacement:

[Portal] Complete the provided Portal integration guide. #

Description: To support the new Portal workflow, you’ll need to upgrade portlets and deployment systems so they work properly with the new Portal.

Integration step: Check out the Portal Integration Guide in the shared Google Drive for integration steps and a changelist.

Related note: See feature note about the new Portal.

Bugs and Fixes #

• [Game Flow] Pragma Engine now properly clears party and matchmaking states when a client crashes and restarts.

  • Description: New client connections are treated as fresh sessions, unless enableMatchReconnect is configured, in which case the players are automatically reconnected to the match.

  • Related note: See integration note on Match Reconnect.

• [Game Flow] We’ve fixed an issue where sessions would prematurely time out if connected with HTTP and WebSocket.

Docs #

• [Updated Docs] Updated SDK docs across the site to reflect the API V2 changes.

• [Updated Concepts] Added a new section on Keep Alive Heartbeats in the Match End page, which explains the behavior regarding the Match Lifecycle service.

• [Updated Concepts] Added new information on disabling Unsafe Providers and the related config to the Identity Providers page.

• [Updated Concepts] Updated the Provider Entitlement page with new information and clarification.

• [Updated Concepts] Added new information on match reconnect on the Game Server Management page.

  • Related note: See feature note about match reconnect.

• [Updated Concepts] Added a new section Add Custom Behavior After Complete Loop to the Matchmaking page.

  • Related note: See feature note on the new Matchmaking Plugin method endLoop.

• [Updated Concepts] Added a new section on Configuring Protocols for HTTP and WebSocket connection on the Game Server Management page.

• [Tech Blog] The Tech Blog has migrated from the docs site to Pragma’s main site, with a new landing page which includes new locations for articles.

• [New Tech Blog Articles] Two new Content Data articles are live! Learn about the Content Data system with Part 1 and Part 2 of the Content Data article series.

January 13, 2023

Changes from 0.0.89 have been integrated into this release.

Features #

The updated Matchmaking service is live! #

Description: Our new version of the Matchmaking service currently supports the same features as the previous iteration, but with easier ways to write core matchmaking logic in the plugin, and improved implementation for custom games and other game types that don’t require matching with incoming parties. We’ll continue to add new functionality to this service.

Related note: See Docs note on the new Matchmaking page.

You can now send an idempotency key on the Apply Inventory Operations endpoints to ensure the data operations are applied only once. #

Description: These Apply Inventory Operations endpoints include:

• InventoryRpc.ApplyInventoryOperationsOperatorV1Request
• InventoryRpc.ApplyInventoryOperationsPartnerV1Request
• InventoryRpc.ApplyInventoryOperationsServiceV1Request If you assign an idempotency key, all Apply Inventory Operations’ requests with DataOperations will only be applied to the player one time. All following requests with the same idempotency key will do nothing and return an empty response.

You can now return a null ExtInstancedItem in the InstancedItemPluginResult. #

Description: The update to InstancedItemPluginResult now allows you to return a null on the ExtInstancedItem field. This allows for a lot more flexibility and control of instanced item creation and updating.

You can now set a time window on limited grants. #

Description: This allows you to define a limited grant that will only be granted to a player within a specified time window.

Related note: See related Docs note on the Limited Grant tutorial.

Game client inventory is now updated automatically when player inventory is changed. #

Description: Game client inventory is now updated automatically when player inventory is changed using Operator, Partner, or Service inventory endpoints. The existing Pragma Engine InventoryService.OnInventoryUpdated notifications on both Unreal and Unity SDKs are broadcast when updates are received.

Added a new Service endpoint for deleting a player’s inventory. #

Description: Services can now delete player inventories by using the new endpoint DeletePlayerInventoryServiceV1Request. Note that this functionality already existed as a Player endpoint, and is now additionally available as a Service endpoint.

Added a new annotate command to output fully resolved Pragma Engine configurations. #

Description: A new annotate command has been added to the pragma.jar to enable viewing the fully resolved configuration.

For more information, run the following command:

java -jar 5-ext/target/pragma.jar config annotate --help

Example: The following command returns a full output of the configurations annotated with the source file that the values originated from.

java -jar 5-ext/target/pragma.jar config annotate --backend-type game --configuration-filepaths config/dev-defaults.yml,5-ext/config/dev.yml,5-ext/config/common.yml,5-ext/config/local-dev.yml

SDKs: You can now specify Partner Session Authentication Tokens via an SDK’s command line. #

Description: Specifying Partner Session Authentication Tokens for game servers can now be done during your SDK app startup. Before this feature, users had to put partner tokens into a config file. Users can now specify those tokens via the SDK command line.

PragmaPartnerSessionSocialAuthToken="<social token>"
PragmaPartnerSessionGameAuthToken="<game token>"

Jobs in the Dependent Job Incoming Queue Length graph in Grafana are now split into subsets of jobs. #

Description: In the Dependent Job Incoming Queue Length graph in Grafana, jobs are now split into subsets of jobs specified by a group identifier. This new group argument can be added to pragma.jobs.runAsDependentJobs; existing usages can be updated to use this feature.

SDKs: You can now reuse a game server for multiple matches by releasing the capacity of the MatchCapacityService after match completion. #

Description: When calling ReleaseCapacity, the MatchCapacity service sets the used capacity to 0, which is then reported to Pragma Engine in the ReportCapacity poll. To reuse this game server state, pass in the OnComplete handler that was used in the StartReportCapacityPolling call.

void UPragmaMatchCapacityService::ReleaseCapacity(const FMatchAllocatedDelegate& OnComplete)

TFuture<TPragmaResult<FPragma_MatchLifecycle_MatchDataV2>> UPragmaMatchCapacityService::ReleaseCapacity()

public void ReleaseCapacity(MatchAllocatedDelegate onComplete)

public void ReleaseCapacity(MatchAllocatedDelegate onComplete)

Unreal SDK: You can now override Pragma.ini’s location via the Unreal SDK’s command line. #

Description: The Pragma.ini configuration file can now be specified in a command line instead of hardcoded to its specific destination. Make sure that you specify a filename and include the .ini extension when changing the file’s location.

PragmaIni="path/to/pragma.ini"

Unreal SDK: Added future version to the StartReportCapacityPolling function. #

Description: To maintain consistency with SDKs having both callback and future versions of async functions, we’ve added a version of the StartReportCapacityPolling function that returns a future alongside the existing version of the function that takes in a callback.

Example: UPragmaMatchCapacityService:

TFuture<TPragmaResult<FPragma_MatchLifecycle_MatchDataV2>> UPragmaMatchCapacityService::StartReportCapacityPolling(FString ServerId, FString GameVersion, FString GameServerZone, float Timeout)

Unreal SDK: New HasSession() method added to Pragma Subsystems. #

Description: You can now check if Pragma Engine has been initialized without needing to hit the assert inside GetSession(). Use the new HasSession() method on Pragma LocalPlayer and GameServer Subsystems instead.

Unreal SDK: Program type Unreal apps can now be used without an engine dependency. #

Description: The PragmaSDK module no longer has an engine module dependency, which means it can be built by Unreal apps that don’t depend on it. Engine-dependent functionality is now in PragmaSDKAux, so if you’re using Subsystems or are planning on future engine-dependent code, you’ll need to include that module in your dependency list. Related note: See related Integration note about the PragmaSDKAux dependency.

Portal: Added Tree view alongside Rich and Raw views in Content Catalogs. #

Description: We’ve added a structured JSON editor under the Tree tab on the Content Catalogs page. This editor includes several formatting tools, such as sort, transform, and duplicate.

Portal: Content Catalogs Editor now enabled by default. #

Description: The Content Catalogs Editor portlet is now enabled by default. Adding 4: null to your config will disable this portlet.

game:
  pluginConfigs:
    GameOperatorGatewayNodeService.portalPlugin:
      class: "pragma.gateway.FilePortalModulePlugin"
      config:
        modules:
          4: null

Deprecations #

Replace GrantItemsPartnerV1, DestroyItemsPartnerV1, DestroyItemsServiceV1, and GetInventoryPartnerV1 with their newer versions. #

Description: The GrantItemsPartnerV1, DestroyItemsPartnerV1, DestroyItemsServiceV1, and GetInventoryPartnerV1 endpoints weren’t filtering content into hidden vs player-facing inventory items, which meant game servers could be sent hidden inventory. The responses for these endpoints are now filtered into a ServiceUpdateItemsResponse with two UpdateItemsResponses, one for hidden inventory and one for player-visible items.

Replace the request and response calls for the following endpoints with their newer versions by release 0.0.90. Note that you can use the separate updates.hidden and updates.player to access filtered data.

Unity SDK: Switch to using the cached inventory returned by InventoryService.GetInventory. #

Description: Unity SDK developers need to switch to using cached inventory returned by InventoryService.GetInventory, or force the cache to update and use the result returned to the callback provided to the new InventoryServiceForceGetInventory. To find stackable and instanced inventory within this data, you can subscribe an event handler to InventoryService.OnInventoryUpdated.

Replace usages of InventoryService.GetInventoryV2 with InventoryService.GetInventory. If you require the client to forcibly refresh itself, you can use InventoryService.ForceGetInventory.

Integrations #

Update unit tests to be compatible with the JUnit upgrade. #

Description: We’ve upgraded JUnit from version 5.6.2 to 5.9.1 to take advantage of some new test parallelization features. As a result, you may need to make changes to some of your unit tests.

Integration steps:

• Remove the private modifier from @BeforeEach/@AfterEach/@BeforeAll/@AfterAll methods in your unit tests.
• If you’re using @BeforeEach/@AfterEach/@BeforeAll/@AfterAll methods with inheritance, you may need to make some changes to preserve intended behavior due to a bugfix.

Update unit tests because they now run in parallel. #

Description: Tests now run in parallel by default in order to shorten build times. This affects tests running via make/mvn and IntelliJ.

Integration steps: Some tests may not be compatible with parallelization.

• Use @ResourceLock to prevent multiple tests from using a particular resource simultaneously.
  • Example: Tests that use Ktor’s withTestApplication do not interact well with parallelization and should use a @ResourceLock(Resources.KTOR_TEST) annotation to ensure only one is run at a time.
• Use @Isolated to ensure a test runs entirely alone.
  • Example: Any tests that use mockkStatic should use @Isolated.
• Using delays in integration tests is more dangerous with parallelization. Use the new TestUtils.repeatUntilSuccess function instead of hardcoded sleeps to make your tests more robust.
• maven-surefire-plugin often reports incorrect numbers of tests run in each class (this is a known issue).

Update your usage of the PartyTestFactory. #

Description: The party() and partyWithPlayers() methods have been combined. The new method is named party() and preserves the functionality of both methods.

Integration steps:

• Replace usages of partyWithPlayers() with party().
• If you’re using party() and want a party with zero players, pass in numPlayers = 0.

Copy your Social node’s configuration for TokenSignerConfig into the Game node configuration. #

Description: Pragma Engine can now send Partner game tokens to Nomad game servers on startup. To enable this, Game node configurations now require a TokenSignerConfig.

Integration step: Copy the existing configuration from social.serviceConfigs.TokenSignerConfig and create a new entry at game.serviceConfigs.TokenSignerConfig.

game:
    serviceConfigs:
        TokenSignerConfig:
            jwtPrivateKey: "myPrivateKey"

If you’re using Nomad as a capacity provider, the config for the PragmaNomadCapacityProvider needs to be updated to use jobDatacenter instead of jobName. #

Description: To support the Nomad changes that improve the capacity provider flow, you need to update the config as we move towards a simpler pattern for spawning jobs.

Integration step: If you’re using Nomad as a capacity provider, the config for the matchcapacity.PragmaNomadCapacityProvider needs to be updated to use jobDatacenter instead of jobName. You’ll also need to remove -exec from the config value.

Self-hosted customers will need to upgrade their environments using the following Terraform module: internal-shard-with-nomad-v5. Managed customers should reach out to Pragma for support for this change. #

Description: Partner tokens no longer need to be encoded into Nomad game binaries, because the Nomad capacity provider now sends them automatically on addCapacity calls–this change requires an update to the Nomad infrastructure. The game server shell invocation script is invoked by Nomad with the following command line parameters: PragmaPartnerSessionSocialAuthToken and PragmaPartnerSessionGameAuthToken. The SDK prioritizes these over values set in Pragma.ini files.

Integration step: Terraform environments must be upgraded using the following shared Terraform module: internal-shard-with-nomad-v5. You won’t be able to use your Nomad provider until this integration is complete. Managed customers should reach out to their Pragma support team to have this work completed.

If you’re using the token refresh feature for the Discord ID provider, reach out to your support representative. #

Description: To simplify the extra features on supported ID providers, we’ve removed the following endpoints: /v1/account/discord-token-refresh & discordTokenRefreshV1.

Integration step: If you’re using the token refresh feature for the Discord ID provider, reach out to your support representative.

If your game is integrated with the Inventory service, you need to assign a value to InventoryCacheConfig. #

Description: The Inventory service now runs a sweep of the cache in the background to help with the eviction logic for the Inventory service cache. We have added configurations around the frequency and requirements to evict.

Integration steps:

• Assign an InventoryCacheConfig under InventoryServiceConfig for all deployed environments. The following parameters must be assigned values: sizeBeforeExpirationEnforced, maxTimeBetweenAccessMillis, and sweepIntervalMillis. We have provided local/dev defaults under pragma-engine/platform/config/dev-defaults.yml, but must be manually set for all other environments.
• We recommend using the values in the example below. If you’re currently integrated with the Inventory service and running playtests with over 10,000 players, please reach out to Pragma for support.

Example: Config under game:

InventoryServiceConfig:
	inventoryCacheConfig:
		sizeBeforeExpirationEnforced: 10000
		maxTimeBetweenAccessMillis: 720000
		sweepIntervalMillis: 900000

If you’re returning instancedItemGrants from InventoryOperationsPlugin.InventoryOperations, you need to update server type. #

Description: The return result from InventoryOperationsPlugin.getInventoryOperationsFromMatchEnd() no longer has a field for InstancedItemGrants.

Integration step: Convert from InstancedItemGrant to InstancedItemServerGrant in your plugin implementation.

If you’re not using Pragma Engine’s SDK’s game servers and you’re using the Keep Alive feature, you must configure the Keep Alive interval. #

Description: The Keep Alive feature is now enabled by default, so a Keep Alive interval must be set. Game servers using Pragma Engine’s SDKs will do this automatically.

Integration step: If MatchReadyV2Response.enable_keep_alive is set to true, a MatchKeepAliveV1Request must be sent from the game server on an interval defined by MatchReadyV2Response.keep_alive_interval_millis.

Related note: See Docs note on the Keep Alive feature.

If you want to use match reconnect, you must set SessionConfig.enableMatchReconnect to true. #

Description: To simplify the basic match loop setup, the default value for enableMatchReconnect has been changed to false. If you had match connect implemented already, you will need to reenable it in the config.

**Integration step:**To enable match reconnect, make sure match reconnect SDK handlers are implemented, and then enable match reconnect functionality in your configuration for that environment.

game:
  core:
    session:
      enableMatchReconnect: true

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

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

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

Unreal SDK: If you use the ErrorCode result of the LogIn method, you’ll need to update your code to reference enum errors instead of the previous strings. #

Description: The LogIn method was originally written before the SDK began using enum errors, and therefore used arbitrary strings. With this change, UAccountService::LogIn uses EPragma_SdkError enum values like Unauthorized, PlatformUnavailable, and AlreadyLoggedIn instead of those strings.

Integration step: If you use the ErrorCode result of UAccountService::LogIn, the string value has changed. See the EPragma_SdkError enum for possible errors–UAccountService::LoginError_* strings have been removed.

New strings will look like: EPragma_SdkError::PlatformUnavailable. You can also use the enum itself by using Result.Error() instead of Result.ErrorCode().

Unreal SDK: Update references to PartyService.ResetParty to expect a return value of void instead of a boolean. #

Description: The ResetParty function no longer returns a boolean indicating whether the function actually reset the party. This change was made to simplify some internal code around changing party state. The function still guarantees that the party state is reset every time it is called. Note that the corresponding ForceReset function was changed to return void instead of a boolean, but this was for internal code and should not cause errors, so please let us know if this change impacts you.

Integration step: Update references to PartyService.ResetParty to expect a return value of void instead of a boolean.

Unreal SDK: Update references to the listed renamed Inventory service calls. See included table for details. #

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

Integration step: Update references to the listed renamed Inventory service calls.

Unreal SDK: Add the PragmaSDKAux dependency to any [ProjectName].Build.cs files that depend on PragmaSDK. #

Description: The Unreal SDK has been split into two modules so you will need to add the new module to project dependencies.

Integration step: Add the PragmaSDKAux dependency to any [ProjectName].Build.cs files that depend on PragmaSDK.

Example:

• Before: PrivateDependencyModuleNames.AddRange(new string[] { "PragmaSDK"});
• After: PrivateDependencyModuleNames.AddRange(new string[] { "PragmaSDK", "PragmaSDKAux" });

Related note: See related Feature note about Program type apps.

Portal: Add the previously hard-coded authentication config values into your YAML file. #

Description: The Portal plugin FilePortalModulePlugin previously used hard-coded Pragma-specific app information used by Portal for authentication, for the Google, Discord, and Twitch client IDs. These have been moved to dev-defaults.yml. This means anyone running Pragma Engine locally will still be able to authenticate to the Portal using Pragma Engine apps, but production environments will need to separately specify these config values.

Integration step: Add in the proper config values for authentication in your shard- or common.yml files. An example can be found below or in the platform/config/dev-defaults.yml file.

If you’re using your own app credentials for Portal authentication, you should be unaffected.

Example:

game:
  pluginConfigs:
    GameOperatorGatewayNodeService.portalPlugin:
      class: "pragma.gateway.FilePortalModulePlugin"
      config:
        authenticationIdProviders:
          1: UNSAFE
        discordClientId: ""
        googleClientId: ""
        twitchClientId: ""
...

social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.portalPlugin:
      class: "pragma.gateway.FilePortalModulePlugin"
      config:
        authenticationIdProviders:
          1: UNSAFE
        discordClientId: ""
        googleClientId: ""
        twitchClientId: ""
...

Bugs and Fixes #

• Stopped onComplete callbacks for various functions being executed before inventory update events are fired in the Inventory SDK.

• Unreal SDK: Fixed a bug where the Disconnect event would not be fired when both sockets were considered Degraded and the full disconnect timer had elapsed.

Docs #

• [Updated Concepts Section] The Monetization section has been updated with a new Overview and new pages on Provider Entitlement and the Payment service.

• [New Concepts Guide] Added a new page on Viewing and Editing Content in the Portal section.

• [New Concepts Guide] Added a new page on Grants and Entitlements in the Player Data section.

• [Updated Concepts Guide] The Matchmaking guide has been completely rewritten! This new page contains detailed and comprehensive information on our updated matchmaking service.

• [Updated Concepts Guide] Updated the Match End guide to capture the Match Keep Alive Heartbeats default being changed to true.

• [Updated Concepts Guides] The Game Server Management and Match End pages under Game Flow have been edited for clarity and accuracy.

• [Updated Tutorial] Updated the Limited Grants tutorial to include information on time windows.

• [New Tutorial] Added a new Tutorial on creating a Battlepass.

• [Updated SDK Guide] The Unreal SDK guide has been updated to be clearer and more accurate.

• [New Tech Blog Video] A new video on Creating a Crafting System Using Stores has been posted.

• [New Tech Blog Article] The Instanced Item series is now live! Learn how to create instanced items, custom content, and plugins.

  • Creating Custom Content for Instanced Items
  • Building Unique Instanced Items with Plugins
  • Upgrading Instanced Items

November 8th, 2022

Features #

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

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

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

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

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

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

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

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

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

Purchasing and entitlement catalogs are now retrieved by GetLoginData. #

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

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

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

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

UPragmaGameDataService::GetLoginData()

GameDataService.GetLoginData()

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

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

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

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

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

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

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

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

option (external_visibility) = HIDE;

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

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

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

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

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

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

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

Deprecations #

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

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

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

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

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

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

Integrations #

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

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

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

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

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

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

Integration step:

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

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

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

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

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

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

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

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

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

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

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

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

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

Example:

• Original

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

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

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

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

• Replacement

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

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

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

• dev.yml entry

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

Related note: See Docs note on the config renames.

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

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

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

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

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

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

Delete remaining Lobby service files. #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• LobbyService_NotEnabled
• LobbyService_MatchAlreadyFound
• LobbyService_NoPlayAgainId

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

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

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

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

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

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

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

Related note: See Features note about OnGameClientVersionUpdateRequired.

Bugs and Fixes #

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

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

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

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

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

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

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

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

Docs #

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

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

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

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

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

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

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

October 11th, 2022

Features #

Parties now remain active when a party leader leaves. #

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

Related note: See integration note about party disbandment.

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

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

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

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

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

New player session endpoint for linking additional accounts. #

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

Deprecations #

Use linkIdentityProviderAccountServiceV1 instead of linkIdentityProviderAccountV1. #

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

Partner Game Tokens will now require a gameShardId. #

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

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

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

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

Update usages of DeletePlayerInventoryV2 to DeletePlayerInventoryV3. #

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

Integrations #

Remove references to the expirationDays config value. #

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

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

Use GameDataRPC.GetLoginDataV2 instead of GameDataRPC.GetLoginDataV1. #

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

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

Update the config sections for TokenValidatorNodeService to the TokenDecoderNodeService. #

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

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

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

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

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

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

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

Related note: See feature note about party disbandment.

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

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

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

Bugs and Fixes #

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

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

Docs #

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

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

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

September 27th, 2022

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

Features #

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

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

Deprecations #

Use GameDataRPC.GetLoginDataV2 instead of GameDataRPC.GetLoginDataV1. #

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

Unity:

Unreal:

Direct calls to RPC endpoints:

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

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

Integrations #

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

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

Integration steps:

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

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

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

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

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

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

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

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

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

  Default configuration should look like this:

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

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

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

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

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

Define columnNameOfPropertyToConsistentHash on all custom instances of PartitionDatabaseConfig. #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Integration step:

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

Bugs and Fixes #

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

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

Docs #

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

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

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

September 20th, 2022

Features #

Added support for Playstation authentication.

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

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

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

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

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

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

Bugs and Fixes #

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

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

Docs #

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

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

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

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

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

September 13th, 2022

Features #

Twitch authentication now available.

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

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

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

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

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

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

• Unity SDK:

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

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

• Unreal SDK:

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

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

Deprecations #

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

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

Integrations #

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

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

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

• Integration step:

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

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

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

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

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

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

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

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

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

  {
  "plugin_version": "0.0.43"
  }
  

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

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

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

Bugs and Fixes #

Improved error messaging when linking accounts to other identity providers.

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

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

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

Docs #

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

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

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

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

August 30th, 2022

Features #

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

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

Integrations #

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

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

Bugs and Fixes #

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

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

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

Docs #

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

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

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

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

August 23rd, 2022

Features #

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

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

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

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

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

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

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

Integrations #

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

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

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

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

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

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

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

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

Bugs and Fixes #

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

Docs #

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

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

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

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

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

August 16th, 2022

Features #

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

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

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

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

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

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

Added RPC endpoints for applying inventory operations.

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

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

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

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

  • InventoryOperationsPlugin.InventoryOperations is returned by InventoryOperations.getInventoryOperationsFromMatchEnd.

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

Integrations #

Update SDK configuration with new authorization tokens.

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

    original	replacement
    partnerSessionAuthToken	partnerSessionGameAuthToken

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

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

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

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

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

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

    original	replacement
    recreate	returnFromMatchmaking & returnFromMatch

Bugs and Fixes #

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

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

Docs #

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

[New Introduction Page] Added a generated configuration table.

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

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

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

August 9th, 2022

Features #

Added requestingPlayer parameter to limit access to party detail changes.

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

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

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

Integrations #

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

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

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

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

• Related note: See related feature note.

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

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

    original	replacement
    columnNameOfpropertyToConsistentHash	columnNameOfPropertyToConsistentHash

Migrate all instances of ShutdownV1Notification to the new RemovedV1Notification.

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

  original	replacement
  ShutdownV1Notification	RemovedNotification

Replace all uses of authenticateOrCreateV1 with authenticateOrCreateV2.

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

    original	replacement
    authenticateOrCreateV1	authenticateOrCreateV2
    pragma_player_token	pragma_game_token and pragma_social_token

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

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

Update all references to UpdateDisplayNameV1Request to UpdateDisplayNameOperatorV1Request.

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

  original	replacement
  UpdateDisplayNameV1Request	UpdateDisplayNameOperatorV1Request

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

Add configuration for PaymentDaoNodeService to prepare for upcoming payments functionality.

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

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

August 2nd, 2022

Features #

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

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

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

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

Deprecations #

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

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

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

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

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

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

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

• Update SDK configuration with new authorization tokens.

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

    original	replacement	removal patch
    partnerSessionAuthToken	partnerSessionGameAuthToken	0.0.80

Integrations #

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

      original	replacement
      ExtCreateMatchV1Request?	Pair<ExtCreateMatchV1Request, String>?

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

    message ExtHiddenPartyData {
    }
    message ExtHiddenPlayerData {
    }
    

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

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

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

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

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

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

    original	replacement
    UPragmaCustomServiceRaw	UGameCustomServiceRaw

Docs #

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

July 26th, 2022

Deprecations #

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

    Original	Replacement	Removal Patch
    ShutdownV1Notification	RemovedV1Notification	0.0.78

Integrations #

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

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

      Original	Replacement
      TestFactoryUtils.generateList2	TestFactoryUtils.generateList

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

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

    Original	Replacement
    OnMatchStartFailureV1Notification	OnMatchFailureV1Notification

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

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

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

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

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

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

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

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

  • Integration step:

    • Update the onRemovePlayer function with the new RemovalReason field.

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

• Unreal: Replace ReportCapacityUntilMatchAllocated with StartReportCapacityPolling.

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

      Original	Replacement
      ReportCapacityUntilMatchAllocated	StartReportCapacityPolling

Docs #

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

July 19th, 2022

Features #

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

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

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

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

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

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

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

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

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

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

Integrations #

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

      original	replacement
      GameDataStrategyPlugin	LoginDataPlugin

Bugs and Fixes #

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

Docs #

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

July 12th, 2022

Features #

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

Deprecations #

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

    Original	Replacement	Removal Patch
    ReportCapacityUntilMatchAllocated	StartReportCapacityPolling	0.0.77

Integrations #

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

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

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

Bugs and Fixes #

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

Docs #

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

July 5th, 2022

Features #

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

Integrations #

• Update your InstancedItemPlugin to match the new interface.

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

  • Integration steps:

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

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

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

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

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

      • Rename the following service calls:

        Original	Replacement
        MatchEndV2	MatchEndV4
        PlayerMatchEndV2	PlayerMatchEndV4

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

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

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

Bugs and Fixes #

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

June 28th, 2022

Features #

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

Integrations #

• Modify your custom services by following the provided directions.

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

  • Integration steps:

    • Make the following changes in your custom service.

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

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

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

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

• Replace usage of MatchProcessedV2Notification with MatchProcessedV3Notification.

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

    Original	Replacement
    MatchProcessedV2Notification	MatchProcessedV3Notification

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

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

  • Integration steps:

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

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

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

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

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

  • Integration steps:

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

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

Bugs and Fixes #

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