Pragma Engine 0.0.91 #

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

    bool UPragmaPartyService::CanDeclineReconnectV1() const
    
    bool UPragmaPartyService::CanDeclineReconnectV1(FPragmaError& OutError) const
    
    TFuture<TPragmaResult<>> UPragmaPartyService::DeclineReconnectV1()
    
    void UPragmaPartyService::DeclineReconnectV1(const FOnCompleteDelegate& OnComplete)
    
    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

    FPlayerDeclinedReconnectEvent UPragmaMatchLifecycleService.OnPlayerDeclinedReconnectEvent;
    
    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 PortalServices menu → Game Title ManagementShardsSelect 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:

originalreplacementremoval release
enableMatchReconnect: truematchReconnect: "REQUIRED"0.0.92
enableMatchReconnect: falsematchReconnect: "OFF"0.0.92

[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.

originalreplacement
matchCapacity_partyStartMatchV1RequestmatchCapacity_startMatchV1Request()

[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.

originalreplacement
enableInProgressMatchTimeoutenableMatchAbsoluteTimeout
inProgressMatchTimeoutMillismatchAbsoluteTimeoutMillis
missedKeepAlivesBeforeCleanupkeepAliveMissesLimit

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:

originalreplacement
SessionServicePBPlayerSessionRpc
SessionSessionCommon

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

originalreplacement
Party.getPartyParty.getPartyProto
Party.getBroadcastPartyParty.getBroadcastPartyProto

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

originalreplacement
UPragmaConnection::FConnectionErrorFPragmaConnectionError
EProtocolErrorEPragmaProtocolError

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

originalreplacement
Init(UPragmaSession* InSession)Init(IPragmaShimSession* InSession, IPragmaShimConnection* InConnection)

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

originalreplacement
Init(PragmaSession session)Init(ISession session, IConnection connection)

[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.

Pragma Engine 0.0.90 #

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.

originalreplacementremoval release
GrantItemsPartnerV1GrantItemsPartnerV20.0.91
DestroyItemsPartnerV1DestroyItemsPartnerV20.0.91
DestroyItemsServiceV1DestroyItemsServiceV20.0.91
GetInventoryPartnerV1GetInventoryPartnerV20.0.91

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.

originalreplacementremoval release
InventoryService.GetInventoryV2InventoryService.GetInventory0.0.91

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.

originalreplacement
versionplatformVersion

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.

originalreplacement
UPragmaInventoryService::GetInstancedItemsV1 UPragmaInventoryService::GetStackableItemsV1UPragmaInventoryService::GetInventory: You can see the instanced and stackable items within the response of this call.
UPragmaInventoryService::GetInventoryV1UPragmaInventoryService::GetInventory
UPragmaInventoryService::DeletePlayerInventoryV2UPragmaInventoryService::DeletePlayerInventory

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 #

Pragma Engine 0.0.88 #

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()
GameDataService’s 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.

Note: Make sure the game server config overwrites the PragmaProtocolType to Http with PragmaProtocolType={Http,WebSocket}.

  • PragmaInventoryServiceRaw.GetInventoryPartnerV1()
  • PragmaInventoryServiceRaw.GrantItemsPartnerV1()
  • PragmaInventoryServiceRaw.DestroyItemsPartnerV1()
  • PragmaInventoryServiceRaw.UpdateItemsPartnerV2()
  • Inventory.Raw.GetInventoryPartnerV1()
  • Inventory.Raw.GrantItemsPartnerV1()
  • Inventory.Raw.DestroyItemsPartnerV1()
  • Inventory.Raw.UpdateItemsPartnerV2()
  • GetInventoryPartnerV1()
  • GrantItemsPartnerV1()
  • DestroyItemsPartnerV1()
  • UpdateItemsPartnerV2()

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.

originalreplacementremoval release
versionplatformVersion0.0.89

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.
originalreplacementremoval release
UPragmaInventoryService::GetInstancedItemsV1, UPragmaInventoryService::GetStackableItemsV1UPragmaInventoryService::GetInventory

You can see the instanced and stackable items within the response of this call.
0.0.89
UPragmaInventoryService::GetInventoryV1UPragmaInventoryService::GetInventory0.0.89
UPragmaInventoryService::DeletePlayerInventoryV2UPragmaInventoryService::DeletePlayerInventory0.0.89

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.

    originalreplacement
    CommonConfig.ymlcommon.yml
    LocalConfig.ymllocal-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.
  1. If you have unit tests that connect to the database (not ITs), replace any config creation to match the following example:
OriginalReplacement
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")
  1. Update shard .env files to export the correct ENV_CONFIG paths to match the following example:
OriginalReplacement

In ./platform/5-ext/config/test.env:

export ENV_CONFIG="config/CommonConfig.yml,config/shard/test.yml"

In: ./platform/5-ext/config/test.env

export ENV_CONFIG="config/common.yml,config/shard/test.yml"

  1. 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.

  1. 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.

In DefaultGame.ini

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

In Pragma.json:

{
...
"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.

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

originalreplacement
LinkIdentityProviderAccountV1RequestLinkIdentityProviderAccountServiceV1Request
LinkIdentityProviderAccountV1ResponseLinkIdentityProviderAccountServiceV1Response

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.

originalreplacement
class: "pragma.account.EpicIdentityProvider"class: "pragma.account.EpicIdentityProviderPlugin"
class: "pragma.account.SteamIdentityProvider"class: "pragma.account.SteamIdentityProviderPlugin"

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.

Raw: PragmaInventoryServiceRaw.DeletePlayerInventoryV3() Rich: PragmaInventoryService.DeletePlayerInventory() *rich wrapper
Raw: InventoryServiceRaw.DeletePlayerInventoryV3() Rich: InventoryService.DeletePlayerInventory()

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.

originalreplacement
LocalNode1.pragma_environment.jsonLocalhost.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.

originalreplacement
matchCapacity_partyStartMatchV1RequestmatchCapacity_startMatchV1Request

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:

FUpdateClientVersionEvent OnGameClientVersionUpdateRequired;
public event Action OnGameClientVersionUpdateRequired;
fun getValidGameClientVersions(): List<String>

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.

OriginalReplacement
LocalConfig.ymllocal-dev.yml
CommonConfig.ymlcommon.yml
  • [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.

Pragma Engine 0.0.87 #

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.

originalreplacementremoval release
linkIdentityProviderAccountV1linkIdentityProviderAccountServiceV10.0.88

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.

originalreplacementremoval release
Raw Wrapper: PragmaInventoryServiceRaw.DeletePlayerInventoryV2()Raw Wrapper: PragmaInventoryServiceRaw.DeletePlayerInventoryV3()0.0.88
Rich Wrapper: PragmaInventoryService.DeletePlayerInventoryV2()Rich Wrapper: PragmaInventoryService.DeletePlayerInventory()0.0.88
originalreplacementremoval release
Raw Wrapper: InventoryServiceRaw.DeletePlayerInventoryV2()Raw Wrapper: InventoryServiceRaw.DeletePlayerInventoryV3()0.0.88
Rich Wrapper: InventoryService.DeletePlayerInventoryV2()Rich Wrapper: InventoryService.DeletePlayerInventory()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.

originalreplacement
PragmaGameDataServiceRaw.GetLoginDataV1PragmaGameDataServiceRaw.GetLoginDataV2
originalreplacement
GameData.Raw.GetLoginDataGameData.Raw.GetLoginDataV2
originalreplacement
GetLoginDataV1RequestGetLoginDataV2Request

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.

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

originalreplacement
pragmaGameToken()gameToken()
pragmaSocialToken()socialToken()
pragmaEmailToken()emailToken()

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.

Pragma Engine 0.0.86 #

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:

OriginalReplacementRemoval release
GameData.Raw.GetLoginDataGameData.Raw.GetLoginDataV20.0.87

Unreal:

OriginalReplacementRemoval release
PragmaGameDataServiceRaw.GetLoginDataV1PragmaGameDataServiceRaw.GetLoginDataV20.0.87

Direct calls to RPC endpoints:

OriginalReplacementRemoval release
GetLoginDataV1RequestGetLoginDataV2Request0.0.87

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.

OriginalReplacementRemoval release
LoginDataPlugin.getLoginDataJobsLoginDataPlugin.getLoginDataJobsV20.0.87

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.

OriginalReplacement
AbstractDaoNodeService::getHostPortMapDatabaseConfig::hostPortSchemas

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 #

Pragma Engine 0.0.85 #

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.

Pragma Engine 0.0.84 #

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.
OriginalReplacementRemoval Patch
AbstractDaoNodeService::getHostPortMapDatabaseConfig::hostPortSchemas0.0.85

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:
OriginalReplacement
bool UPragmaPartyService::UpdatePlayerSelectionsV1() constbool UPragmaPartyService::CanUpdatePlayerSelectionsV1() const
bool UPragmaPartyService::UpdatePlayerSelectionsV1(FPragmaError& OutError) constbool UPragmaPartyService::CanUpdatePlayerSelectionsV1(FPragmaError& OutError) const

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.

Pragma Engine 0.0.82 #

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.

Pragma Engine 0.0.81 #

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.
      originalreplacement
      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.

Pragma Engine 0.0.80 #

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).
      originalreplacement
      partnerSessionAuthTokenpartnerSessionGameAuthToken
    • 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.
    originalreplacement
    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.
      originalreplacement
      recreatereturnFromMatchmaking & 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.

Pragma Engine 0.0.79 #

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.
OriginalReplacement
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:
      originalreplacement
      columnNameOfpropertyToConsistentHashcolumnNameOfPropertyToConsistentHash

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:
    originalreplacement
    ShutdownV1NotificationRemovedNotification

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.
      originalreplacement
      authenticateOrCreateV1authenticateOrCreateV2
      pragma_player_tokenpragma_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.
    originalreplacement
    UpdateDisplayNameV1RequestUpdateDisplayNameOperatorV1Request
  • 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"

Pragma Engine 0.0.78 #

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.
    OriginalReplacementRemoval 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.
      originalreplacementremoval 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).
      originalreplacementremoval patch
      partnerSessionAuthTokenpartnerSessionGameAuthToken0.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.
        originalreplacement
        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:
OriginalReplacement

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:
      originalreplacement
      UPragmaCustomServiceRawUGameCustomServiceRaw

Docs #

Pragma Engine 0.0.77 #

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.
      OriginalReplacementRemoval Patch
      ShutdownV1NotificationRemovedV1Notification0.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.
        OriginalReplacement
        TestFactoryUtils.generateList2TestFactoryUtils.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.
      OriginalReplacement
      OnMatchStartFailureV1NotificationOnMatchFailureV1Notification
  • 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.
        OriginalReplacement
        PartyServiceRaw.OnMatchReadyV1NotificationMatchLifecycleServiceRaw.OnMatchReadyV1Notification
        PartyServiceRaw.OnMatchFailedV1NotificationMatchLifecycleServiceRaw.OnMatchFailedV1Notification
        PartyServiceRaw.OnMatchReconnectV1NotificationMatchLifecycleServiceRaw.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.
        OriginalReplacement
        InventoryContent.CostEntryInventoryCommon.CostEntry
        InventoryContent.PurchaseRequirementsInventoryCommon.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.
      OriginalReplacement
      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.
        OriginalReplacement
        ReportCapacityUntilMatchAllocatedStartReportCapacityPolling

Docs #

Pragma Engine 0.0.76 #

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.
        originalreplacement
        GameDataStrategyPluginLoginDataPlugin

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.

Pragma Engine 0.0.75 #

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.
      OriginalReplacementRemoval Patch
      ReportCapacityUntilMatchAllocatedStartReportCapacityPolling0.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.

Pragma Engine 0.0.74 #

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.

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

          OriginalReplacement
          MatchEndV2MatchEndV4
          PlayerMatchEndV2PlayerMatchEndV4
        • 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.

Pragma Engine 0.0.73 #

June 28th, 2022

Features #

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

Integrations #

  • Modify your custom services by following the provided directions.

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

    • Integration steps:

      • Make the following changes in your custom service.
      OriginalReplacement
      launchscope.launch
      asyncscope.async
      coroutineContextscope.coroutineContext
      • If you rely on PragmaNode being a CoroutineScope in your custom service, or if your service does not appear to run in Pragma Engine 0.0.73, please contact us to assess the best solution for your specific usage.
  • Remove the ProgressionData parameter from your implementations of StorePlugin and CraftingPlugin.

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

    • Description: To prepare for the deletion of ProgressionService, we are disabling support for MatchProcessedV2Notification in order to remove progression-related data.
    • Integration steps:
      • Replace usage of MatchProcessedV2Notification with MatchProcessedV3Notification.
      OriginalReplacement
      MatchProcessedV2NotificationMatchProcessedV3Notification
  • Add new inventoryData parameter to update() method in custom implementations of InstancedItemPlugin.

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

    • Integration steps:

      • Change the InstancedItemPlugin.update() method to include the new inventoryData parameter.
      OriginalReplacement
      fun update(
        initialInstancedItem: InstancedItem,
        instancedSpec:      InventoryContent.InstancedSpec,
        updateEntry: InventoryContent.UpdateEntry,
        inventoryContent: InventoryServiceContent,
        clientRequestExt: ExtInstancedItemUpdate?,
        serverRequestExt: ExtInstancedItemServerUpdate?
      ): UpdateResult
      
      fun update(
        initialInstancedItem: InstancedItem,
        instancedSpec:      InventoryContent.InstancedSpec,
        updateEntry: InventoryContent.UpdateEntry,
        inventoryContent: InventoryServiceContent,
        inventoryData: InventoryData,
        clientRequestExt: ExtInstancedItemUpdate?,
        serverRequestExt: ExtInstancedItemServerUpdate?
      ): UpdateResult
      
      • Note that the data class UpdateResult has also been updated with a new parameter, but as it has a default value, no integration steps are required.
  • You may need to create your own test factory if you use certain InventoryProtoTestFactory methods.

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

    • Integration steps:

      • If you use any of the below InventoryProtoTestFactory methods, create your own test factory with the provided replacement or an appropriate equivalent.
      OriginalReplacement
      InventoryProtoTestFactory.extStackableSpec()
      
      fun extStackableSpec(i: Int) = generateProto(ExtStackableSpec::class, i)
      
      InventoryProtoTestFactory.extInstancedItemServerGrant(I:Int)
      
      
      fun extInstancedItemServerGrant(i: Int) = generateProto(ExtInstancedItemServerGrant::class, i)
      

Bugs and Fixes #

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

Pragma Engine 0.0.72 #

June 14th, 2022

Features #

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

Deprecations #

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

Integrations #

  • Rename methods and objects in implementations of MatchEndPlugin.

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

    • Integration steps:

      • Rename the following items:
      OriginalReplacement
      MatchEndPlugin.getMatchEndBuildersMatchEndPlugin.getMatchEndJobs
      MatchEndContextDependentJobContext
      ConcurrentNotificationBuilderThreadsafeMutable
      MatchEndBuilderMatchEndDependentJob
      • Access DependentJobContext and ThreadsafeMutable via the methods on MatchEndDependentJob.
  • Add canChangeReady implementation to Party plugin.

    • Description: Implementing this function is required for the new ready state feature.
    • Integration step: Add this function to Party plugin implementations to compile.
    • Related notes: See ready state feature note and docs note.
  • Update references to Inventory service’s matchEndV1 and matchEndV2 endpoints to matchEndV4.

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

    • Integration steps:

      • Update references to the following:
      OriginalReplacement

      InventoryService.matchEndV1
      InventoryService.matchEndV2

      InventoryService.matchEndV4

      InventoryRpc.MatchEndV1Request
      InventoryRpc.MatchEndV1Response
      InventoryRpc.MatchEndV2Request
      InventoryRpc.MatchEndV2Response

      InventoryRpc.MatchEndV4Request
      InventoryRpc.MatchEndV4Response

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

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

    • Integration steps:

      • Update references to the following:
      OriginalReplacement

      InventoryService.deletePlayerInventoryV1

      InventoryService.deletePlayerInventoryV2

      InventoryRpc.DeletePlayerInventoryV1

      InventoryRpc.DeletePlayerInventoryV2

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

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

    • Integration step:

      • Update references to the following:
      OriginalReplacement

      LobbyService.lockV1

      LobbyService.lockV2

      LobbyRpc.LockV1Request LobbyRpc.LockV1Response

      LobbyRpc.LockV2Request LobbyRpc.LockV2Response

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

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

    • Integration step:

      • Update references to the following:
      OriginalReplacement

      MatchlifecycleService.matchEndV3

      MatchlifecycleService.matchEndV4

      MatchlifecycleRpc.MatchEndV3Request MatchlifecycleRpc.MatchEndV3Response

      MatchlifecycleRpc.MatchEndV4Request MatchlifecycleRpc.MatchEndV4Response

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

    • Description: The validate function in IdentityProviderPlugins has been changed to either return an IdProviderAccount on success or to throw a PragmaException otherwise.
    • Integration step:
      • Modify any custom IdentityProviders to return an IdProviderAccount where they would return a PragmaResult containing the IdProviderAccount, and to throw a PragmaException when they would return a PragmaResult containing an error.
      OriginalReplacement
      PragmaResult<IdProviderAccount, PragmaError> containing an IdProviderAccountIdProviderAccount
      PragmaResult<IdProviderAccount, PragmaError> containing a PragmaErrorThrow a PragmaException
  • Unreal: Update references to UpdateLoadout in Party service to UpdatePlayerSelections.

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

Docs #

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

Pragma Engine 0.0.71 #

June 7th, 2022

Deprecations #

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

    • Description: To support the new hidden inventory feature, the following InventoryRpc calls have been updated to partition data into player and hidden sections.
    OriginalReplacementRemoval Patch
    InventoryRpc.UpdateItemsPartnerV1InventoryRpc.UpdateItemsPartnerV20.0.73
    InventoryRpc.UpdateItemsServiceV1InventoryRpc.UpdateItemsServiceV20.0.73
    InventoryRpc.ServiceGetInventoryV1InventoryRpc.ServiceGetInventoryV20.0.73
    InventoryRpc.GrantItemsServiceV1InventoryRpc.GrantItemsServiceV20.0.73
  • Upgrade to MatchProcessedV3Notifications to prepare for the removal of the Progression service.

    • Description: In preparation for the removal of Progression service, MatchProcessedV2Notifications are being deprecated. By release 0.0.73, you must have updated to the MatchProcessedV3Notifications.
    OriginalReplacementRemoval Patch
    Unity: OnMatchProcessedV2NotificationUnity: OnMatchProcessedV3Notification0.0.73
    Unreal: OnMatchProcessedV2Unreal: OnMatchProcessedV30.0.73
    • Integration steps:

      • A feature toggle in MatchLifecycleService can be configured to switch to V3 once you’re ready:
      game:
        serviceConfigs:
          MatchLifecycleServiceConfig:
            sendMatchProcessedV3Notification: true
      
      • Once you’ve successfully switched over to V3, be sure to update any references to the new version.

Integrations #

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

Bugs and Fixes #

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

Docs #

Pragma Engine 0.0.70 #

June 1st, 2022

Features #

  • Inventory items can now be hidden from players.

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

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

    Service callDescription
    craftV1, storePurchaseV4, updateItemV4, and updateItemsV0returned segments/deltas won’t contain items with tags that match the configuration
    getStoresV0return stores will not contain store entries with tags that match the configuration
    getInventoryV2returned inventory will not contain instanced and stackables whose corresponding content specs contain tags that match the configuration
    GameDataService.GetLoginDataV1 which uses InventoryService.GetLoginDatareturned player inventory and content items (stores, update entries, item catalog, crafting entries, etc) are all filtered based on the tags in the configuration
    GetInventoryServiceV3inventory data split by hidden and player visible items
    UpdateItemsPartnerV2, UpdateItemsServiceV2, and GrantItemsServiceV2segments/deltas split by hidden and player visible items
  • Game server hostname and port information can now be provided as part of the MatchReadyV1Notification.

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

    • Description: Added Operator endpoint for ClearAllInventoryCacheOperatorV1Request. This already existed as a Service endpoint, and is now available for Operator.
  • Partners can now get filtered Pragma account overviews.

    • Description: Added Partner endpoint for GetPragmaAccountOverviewsPartnerV1Request. This already existed as an Operator endpoint, and is now available via Partner.
  • Partners can now get full inventory for a player.

    • Description: Added Partner endpoint for GetInventoryPartnerV1Request. This already existed as an Operator endpoint, and is now available via Partner.
  • [Portal] The content catalog is now shown in a more readable format by default with JSON rendering of ext data.

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

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

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

Deprecations #

  • Remove any references to LeaderClientVersion field.
    • Description: The LeaderClientVersion field of EnterMatchmakingV2Request RPC and MatchmakingParty Kotlin object is being removed as it is unnecessary.
      OriginalReplacementRemoval Patch
      LeaderClientVersion field of EnterMatchmakingV2Request RPC and MatchmakingParty objectNo replacement needed0.0.71
  • Update deletePlayerInventory endpoints to new versions to remove Progression service data.
OriginalReplacementRemoval Patch

InventoryService.deletePlayerInventoryV1

  • InventoryRpc.DeletePlayerInventoryV1Request
  • InventoryRpc.DeletePlayerInventoryV1Response

InventoryService.deletePlayerInventoryV2

  • InventoryRpc.DeletePlayerInventoryV2Request
  • InventoryRpc.DeletePlayerInventoryV2Response
0.0.71
  • Update endpoints to new versions to capture Progression service removals.
    • Description: Endpoints that currently return progression-related data are being versioned to no longer include the progression data fields.

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

OriginalReplacementRemoval Patch

InventoryService.matchEndV2

  • InventoryRpc.MatchEndV2Request
  • InventoryRpc.MatchEndV2Response

InventoryService.matchEndV4

  • InventoryRpc.MatchEndV4Request
  • InventoryRpc.MatchEndV4Response
0.0.72

LobbyService.lockV1

  • LobbyRpc.LockV1Request
  • LobbyRpc.LockV1Response

LobbyService.lockV2

  • LobbyRpc.LockV2Request
  • LobbyRpc.LockV2Response
0.0.72

MatchLifecycleService.matchEndV3

  • MatchLifecycleRpc.MatchEndV3Request
  • MatchLifecycleRpc.MatchEndV3Response

MatchLifecycleService.matchEndV4

  • MatchLifecycleRpc.MatchEndV4Request
  • MatchLifecycleRpc.MatchEndV4Response
0.0.72

Integrations #

  • Create a new recreateParty function definition.

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

    • Description: We’ve completed the move from the listed protos and are now removing the old ones.
    • Integration step: Replace the listed InventoryRpc protos.
      OriginalReplacement
      InstancedDeltaInstancedDeltaV2
      InventoryDeltaV1DataInstancedDeltaV2
  • Move over from the Progression service to the Inventory service.

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

    • Description: Ktor defaults create thread pools of the appropriate size, so this configuration is not needed.
    • Integration step: Remove gatewayWorkerThreadpoolSize value in config YAML files.
  • Add required Maven dependency to 5-ext/ext/pom.xml.

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

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

      <dependency>
          <groupId>pragma</groupId>
          <artifactId>core</artifactId>
          <version>${pragma.mvn.version}</version>
          <type>test-jar</type>
          <scope>test</scope>
      </dependency>
      
  • Create a new local configuration file to continue using custom portlets.

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

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

        module.exports = {
            default: {
                'portlets.extraSrcDirs': ['5-ext']
            },
            deploy: {
                target: ['5-ext/portal']
            }
        }
        
  • Make the following changes for project structure improvements.

    • Description: To enable the recent project structure improvements, make the following changes, which are listed by file.
    • Integration steps:
      • In 5-ext/pom.xml:

        • Remove <module>ext-protos</module> from <modules>.
        • Add <groupid>[studio_name]</groupid> above <artifactId> tag.
        • Add the following properties block:
        <properties>
          <revision>[project_name]-LOCAL-SNAPSHOT</revision>
          <company>[project_name]</company>
          <pragma.version>LOCAL</pragma.version>
          <pragma.mvn.version>PRAGMA-LOCAL-SNAPSHOT</pragma.mvn.version>
        </properties>
        
      • In 5-ext/ext/pom.xml:

        • Change <parent><groupId>pragma</groupId></parent> to <parent><groupId>[studio_name]</groupId></parent> with your studio’s name in the brackets.
        • Change the following dependency block:
        OriginalReplacement
        <dependency>
            <groupId>pragma</groupId>
            <artifactId>ext-protos</artifactId>
            <version>${revision}</version>
        </dependency>
        <dependency>
            <groupId>pragma</groupId>
            <artifactId>ext-protos</artifactId>
            <version>${revision}</version>
            <type>test-jar</type>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>[studio_name]</groupId>
            <artifactId>ext-protos</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>[studio_name]</groupId>
            <artifactId>ext-protos</artifactId>
            <version>${project.version}</version>
            <type>test-jar</type>
            <scope>test</scope>
        </dependency>
        
        • Change the following dependency block:
        OriginalReplacement
        <dependency>
            <groupId>pragma</groupId>
            <artifactId>core</artifactId>
            <version>${revision}</version>
        </dependency>
        
        <dependency>
            <groupId>pragma</groupId>
            <artifactId>core</artifactId>
            <version>${pragma.mvn.version}</version>
        </dependency>
        
      • For each of the dependencies listed, update ${revision} to ${pragma.mvn.version}. Be sure to check for and update two dependency blocks, one default, and one with <type>test-jar</type>:

        • pragma.core
        • pragma.server-base
        • pragma.social
        • pragma.game
        • pragma.game-common
        • Pragma.social-common
      • In 5-ext/ext-protos/pom.xml:

        • Make the following parent change:
        OriginalReplacement
        <parent>
            <groupId>pragma</groupId>
            <artifactId>5-ext</artifactId>
            <version>${revision}</version>
        </parent>
        
        <parent>
            <groupId>pragma</groupId>
            <artifactId>engine-settings</artifactId>
            <version>PRAGMA-LOCAL-SNAPSHOT</version>
            <relativePath>../../engine-settings.xml</relativePath>
        </parent>
        
        • Add <groupId>[studio_name]</groupId> above the <artifactId> tag.
        • Add <version>[studio_name]-LOCAL-SNAPSHOT</version> below the <artifactId> tag.
        • For each of the dependencies listed, update ${revision} to ${pragma.mvn.version}:
          • pragma.proto-defs
          • pragma.proto-defs (<type>test-jar</type>)
      • In 5-ext/ext-server/pom.xml:

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

Bugs and Fixes #

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

Pragma Engine 0.0.69 #

May 24th, 2022

Features #

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

Deprecations #

  • Replace listed InventoryRpc protos by release 0.0.70.
    OriginalReplacementRemoval Patch
    InstancedDeltaInstancedDeltaV20.0.70
    InventoryDeltaV1DataInstancedDeltaV20.0.70

Integrations #

  • Update custom MatchEndBuilders to MatchEndV2 to support hidden inventory.
    • Description: To support hidden inventory, we’ve updated the Inventory service MatchEnd endpoint and InventoryMatchEndBuilder. You will need to update custom MatchEndBuilders to look for the new MatchEndV2Response.
    • The contents of the MatchEnd response have also changed. If you currently inspect the UpdateSummaries that come back from InventoryService in custom MatchEndBuilder, the new response contains a ServiceUpdateSummary, which is composed of two UpdateSummary objects.
    • Until you start using hidden inventory, the player UpdateSummary field is equivalent to what was there before.
    • Integration steps:
      • If you have custom MatchEndBuilders inspecting context, you will need to update what they look for:
        OriginalReplacement
        InventoryRpc.MatchEndV1Response::classInventoryRpc.MatchEndV2Response::class
  • Update references to the Party plugin’s PartyPlayer inventory field.
    • Description: The Party plugin’s PartyPlayer inventory field has a new type. This new class contains two InventoryDatas with content split using the new hidden inventory system.
    • Integration steps:
      • Update references using inventory and underlying fields on a PartyPlayer. Until hidden inventory is configured, use the player InventoryData object as the equivalent of the old inventory field.
        OriginalReplacement
        InventoryFullV1DataServiceInventoryData

Docs #

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

Pragma Engine 0.0.68 #

May 17th, 2022

Features #

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

Deprecations #

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

Integrations #

  • Move and rename Party service protos.
    • Description: Some ext protos have been moved and renamed in preparation for Party service release.
    • Integration steps:
      • In the /platform/5-ext/ext-protos/src/main/proto/shared/ directory:
        • Delete partyExt.proto.
        • In the partyRpcExt.proto file, create the following protos. Remove the import relating to partyExt.proto if found.
// ext field for party state
message ExtPartySelections {
}
// ext field for player selection state within a party
message ExtPlayerSelections {
}
// ext field for private player selection state within a party
message ExtPrivatePlayerSelections {
}
// request ext field for creating a party
message ExtCreateRequest {
}
// request ext field for adding a player to a party
message ExtPlayerJoinRequest {
}
// request ext field for updating a player selection
message ExtUpdatePlayerSelectionsRequest {
}
// request ext field for updating a party selection
message ExtUpdatePartySelectionsRequest {
}
  • Use InventoryService.MatchEndV1 instead of InventoryService.MatchEndV0.
    • Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to MatchLifecycleService.matchEndV3.
    • Integration step:
      • Make the following changes: InventoryRpc protos:
        OriginalReplacement
        MatchEndV0RequestMatchEndV1Request
        MatchEndV0ResponseMatchEndV1Response
        Inventory RPC service route:
        OriginalReplacement
        ———–——————
        matchEndV0matchEndV1

Bugs and Fixes #

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

Docs: #

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

Pragma Engine 0.0.67 #

May 10th, 2022

Features #

  • Cross-content validation for Inventory Service content available.

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

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

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

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

  • Upgraded Portal now live!

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

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

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

Integrations #

  • Update Portal build directory and update custom modules if necessary.
    • Description: The new Portal is now available at platform/web/portal. If you don’t have custom modules, the Portal is backwards compatible, and can still be found at platform/web/portal-base. If you do have custom modules, you’ll need to follow the integration steps.
    • Integration steps:
      • You may need to update the build directory if you have a custom build step.
      • Custom Portal modules may need to be individually integrated. Contact us if you have custom Portal development and have not yet received help with integration.
    • Related note: see feature announcement for more information on the new Portal.
  • Update the ContentDataProxy class primary constructor if necessary.
    • Description: The kClass param has been removed from the ContentDataProxy class’s primary constructor.
    • Integration steps:
      • If you are using this class with custom content, you will need to remove the kClass param as shown below. No action is required otherwise.
OriginalReplacement
class ContentDataProxy<ContentProto : GeneratedMessageV3>(
    private val kClass: KClass<ContentProto>,
    private val resourcePath: String,
) : ContentData<ContentProto>
class ContentDataProxy<ContentProto : GeneratedMessageV3>(
      private val resourcePath: String,
) : ContentData<ContentProto>
  • Rename InMemSocialIT.yml and InMemGameIT.yml.
    • Description: Certain files have been renamed due to the removal of the in-memory database driver.
    • Integration steps:
      • The Makefile has been updated to copy InMemSocialIT.yml and InMemGameIT.yml over. If you are using a custom Makefile, please update it.
      • Merge the contents of your existing InMemSocialIT.yml and InMemGameIT.yml files into the new files.
OriginalReplacement
ext/src/test/resources/localDevelopmentShardConfig/InMemSocialIT.ymlext/src/test/resources/localDevelopmentShardConfig/SocialIT.yml
ext/src/test/resources/localDevelopmentShardConfig/InMemGameIT.ymlext/src/test/resources/localDevelopmentShardConfig/GameIT.yml
  • Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.
    • Description: TokenUtils::createPragmaJWT has been replaced by PragmaJwtSigner.
    • Integration steps:
      • Use PragmaJwtSigner instead of TokenUtils::createPragmaJWT.
OriginalReplacement
TokenUtils::createPragmaJWTPragmaJwtSigner
  • Update the Makefile to reflect changes to the relevant gen-sdk-types-<ENGINE> targets.
    • Description: The SDK type generation targets have been fixed to also build Pragma protos.
    • Integration steps:
      • If you have your own copy of the Makefile, ensure that the relevant gen-sdk-types-<ENGINE> also depends on the protos step.
OriginalReplacement
gen-sdk-types-unreal4: ext-protosgen-sdk-types-unreal4: protos ext-protos

Bugs and Fixes #

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

Docs #

Pragma Engine 0.0.66 #

May 3rd, 2022

Features #

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

Deprecations #

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

    • Description: The scheme and wsScheme fields in the <protocol>://<host>:<port>/v1/info endpoint are being deprecated, and will be replaced with protocol and webSocketProtocol.
      OriginalReplacementRemoval Patch
      schemeprotocol0.0.68
      wsSchemewebSocketProtocol0.0.68
  • Inventory MatchEndV0 RPC and protos are being renamed to MatchEndV1.

    • Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to MatchLifecycleService.matchEndV3.
    • InventoryRpc protos:
      OriginalReplacementRemoval Patch
      MatchEndV0RequestMatchEndV1Request0.0.68
      MatchEndV0ResponseMatchEndV1Response0.0.68
    • Inventory RPC service route:
      OriginalReplacementRemoval Patch
      matchEndV0matchEndV10.0.68

Integrations #

  • Change from MariaDB to MySQL.
    • Description: Beginning in release 0.0.66, Pragma Engine will no longer have an in-memory option for databases. Your platform and infrastructure will not load until you have completed this change. All data that is not migrated to MySQL will be lost.
    • Integration step: A guide has been provided for affected customers. Follow the guide for instructions for both local and non-local environments.
  • Update partnerConnectionInfo config in configuration YAML files.
    • Description: The url config property is being deprecated. Provide the appropriate values for the host, port, and protocol fields instead. Note that protocol defaults to http in development mode, but a protocol must be specified in production mode in order for the platform to successfully start up.
    • Integration step: Update partnerConnectionInfo config as specified below.
OriginalReplacement
partnerConnectionInfo:
  url: "http://localhost"
  host: "localhost"
  port: 10106
partnerConnectionInfo:
  protocol: "http"
  host: "localhost"
  port: 10106
  • Update InstancedItemPlugin code that uses UpdateResult.
    • Description: instancedItemGrants has been renamed to instancedItemServerGrants.
    • Integration steps: Update all plugins that return a InstancedItemPlugin.UpdateResult by renaming instancedItemGrants to instancedItemServerGrants.
OriginalReplacement
return InstancedItemPlugin.UpdateResult(
  extInstancedItem
  instancedItemGrants
  stackableItemGrants
)
return InstancedItemPlugin.UpdateResult(
  extInstancedItem
  instancedItemServerGrants
  stackableItemGrants
)
  • Change ContentDataNodeService.getHandler method.
    • Description: The ContentDataNodeService.getHandler method with kclass parameter has been removed, and you’ll need to confirm you’re using the recommended, functional method.
    • Integration step: Use the ContentDataNodeService.getHandler method without the kclass parameter.
OriginalReplacement
fun <ContentProto : GeneratedMessageV3> getHandler(
  kClass: KClass<ContentProto>,
  resourcePath: String
): ContentData<ContentProto>
fun <ContentProto : GeneratedMessageV3> getHandler(
  resourcePath: String
): ContentData<ContentProto>
  • Update the following functions as mentioned in release 0.0.64.

    • Description: Session and WebSocket cleanup changes.
    • Integration step: Make the following changes:
      OriginalReplacement
      JumpData::longClassNameToShortName()ProtoUtils.protoShortName()
      TokenUtils.createPragmaJWTuse PragmaJwtSigner methods
  • Update server configuration for listed gateway config fields.

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

Bugs and Fixes #

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

Docs #

Pragma Engine 0.0.65 #

April 26th, 2022

Features #

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

Integrations #

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

      Bugs and Fixes #

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

Pragma Engine 0.0.64 #

April 19th, 2022

Features #

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

Deprecations #

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

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

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

Integrations #

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

Bugs and Fixes #

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

Docs #

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

Pragma Engine 0.0.63 #

April 12th, 2022

Features #

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

Bugs and Fixes #

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

Pragma Engine 0.0.62 #

April 5th, 2022

Features #

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

Deprecations #

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

Integrations #

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

Bugs and Fixes #

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

Pragma Engine 0.0.61 #

March 29nd, 2022

Features #

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

Deprecations #

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

Integrations #

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

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

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

Bugs and Fixes #

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

Pragma Engine 0.0.60 #

March 22nd, 2022

Features: #

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

Integrations #

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

Bugs and Fixes #

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

Pragma Engine 0.0.59 #

March 15th, 2022

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

Integrations: #

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

    • Integration step:

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

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

Pragma Engine 0.0.58 #

March 8th, 2022

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

Features:

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

Deprecations: #

  • LeaveMatchmakingV1 has been updated to V2.

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

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

    Integrations: #

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

    Bugs and Fixes: #

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

Pragma Engine 0.0.57 #

March 1st, 2022

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

Integrations: #

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

runBlockingTestWithTimeout

runTest for unit tests

runIntegrationTest for integration tests

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

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

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

Features: #

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

Bugs and fixes: #

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

Pragma Engine 0.0.56 #

February 22nd, 2022

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

Features: #

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

Integrations: #

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

Pragma Engine 0.0.55 #

February 15th, 2022

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

Features: #

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

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

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

Integrations #

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

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

    • Integration step:

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

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

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

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

Bug fix #

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

Deprecations #

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

Pragma Engine 0.0.54 #

February 8th, 2022

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

Features #

  • Added bulk action account plugin.

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

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

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

Integrations #

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

    • Integration step:

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

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

Deprecations #

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

Pragma Engine 0.0.53 #

February 1st, 2022

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

Features #

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

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

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

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

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

Integrations #

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

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

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

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

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

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

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

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

Bugfix #

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

Deprecations #

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

Pragma Engine 0.0.52 #

January 25th, 2022

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

Integrations #

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

    • Steps:

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

      $ cd platform
      $ make ci-portal-ext
      

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

      npm run start
      

      For more information, read the README_PORTAL.md file.

Deprecations #

  • none

Pragma Engine 0.0.51 #

January 18th, 2022

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

Integrations #

  • You must define message ExtEnterMatchmakingV2Request in matchmakingExt.proto to successfully compile.
    • Description: The new proto message ExtEnterMatchmakingV2Request must be defined. This is to prepare for the new party service currently being built.
      message ExtEnterMatchmakingV2Request {
      }
      
    • Path:5-ext/ext-protos/src/main/proto/shared/matchmakingExt.proto

Pragma Engine 0.0.50 #

January 12th, 2022

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

Features #

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

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

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

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

Integrations #

  • You must define exts in implementation types to successfully compile. This change is to prepare for the new party service currently being built.
    • Description: Add the following lines to partyExt.proto.
      message ExtPartyDetails {
      }
      
      message ExtPartyPlayer {
      }
      
    • Path:5-ext/ext-protos/src/main/proto/shared/partyExt.proto

Bugs and Fixes #

  • Order changed in Service.shutdown().

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

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

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

Deprecations #

  • none

Pragma Engine 0.0.49 #

January 4th, 2022

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

Features #

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

Integration Steps #

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

Deprecations #

The following endpoints have been changed:

OriginalReplacement
authenticateOrCreateV1authenticateOrCreateV2
AccountService.getPragmaPlayerIdsForProviderIdsV1AccountService.getPragmaPlayerIdsForProviderIdsV2
InventoryServiceContent getter methods have been updatedSee integration notes above

Pragma Engine 0.0.48 #

December 14th, 2021

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

Features #

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

Integration Steps #

  • New GameDataStrategy interface to increase cohesion between plugins.

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

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

Deprecations #

  • None

Pragma Engine 0.0.47 #

November 30th, 2021

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

Features #

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

Integration Steps #

  • None

Deprecations #

  • None

Pragma Engine 0.0.46 #

November 23rd, 2021

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

Features #

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

Integration Steps #

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

Deprecations #

The following endpoints have been changed:

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

Pragma Engine 0.0.45 #

2021-11-16

Features #

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

Integration Notes #

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

Pragma Engine 0.0.44 #

2021-11-09

Features:

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

Integration Notes #

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

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

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

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

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

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

  • Migrate existing InstancedDataProviderPlugin implementations to new name InstancedItemPlugin

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

Deprecations #

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

Pragma Engine 0.0.43 #

2021-11-02

Features #

  • Players can now invite others using Lobby Invite Codes.

Deprecations #

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

Pragma Engine 0.0.42 #

2021-10-26

Features #

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

Integration Notes #

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

Pragma Engine 0.0.41 #

2021-10-19

Integration Notes #

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

Pragma Engine 0.0.40 #

2021-10-19

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.39 #

2021-10-12

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.38 #

2021-10-05

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.37 #

2021-09-28

Features #

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

Fixes #

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

2021-09-28

Features #

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

Integration Notes #

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

Deprecation #

- None

Pragma Engine 0.0.36 #

2021-09-21

Features #

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

Integration Notes #

  • Use make protos instead of these removed aliases:
    • proto protobuf protobufs

Deprecation #

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

Pragma Engine 0.0.35 #

2021-09-14

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.34 #

2021-09-07

Integration Notes #

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

Pragma Engine 0.0.33 #

2021-08-31

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.32 #

2021-08-24

Features #

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

Integration Notes #

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

Deprecation #

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

Pragma Engine 0.0.31 #

2021-08-17

Features #

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

Integration Notes #

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

Architecture Change #

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

Pragma Engine 0.0.30 #

2021-08-10

Features #

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

Deprecation #

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

Pragma Engine 0.0.29 #

2021-08-04

Features #

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

2021-08-03

Features #

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

Integration Notes #

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

Deprecation #

  • Removed player_info from ExtEnterMatchmakingV1Request in matchmakingExt.proto.

Removed #

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

Pragma Engine 0.0.28 #

2021-07-27

Features #

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

Integration Notes #

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

Deprecation #

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

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

Removed #

  • InventoryRpc.SimulateRewardsV1
    • Use InventoryRpc.SimulateRewardsV2

Pragma Engine 0.0.27 #

2021-07-13

Features #

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

Integration Notes #

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

Pragma Engine 0.0.26 #

2021-07-06

Features #

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

Pragma Engine 0.0.25 #

2021-06-29

Features #

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

Integration Notes #

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

Deprecation #

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

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

Pragma Engine 0.0.24 #

2021-06-22

Improvements #

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

Pragma Engine 0.0.23 #

2021-06-15

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


Features #

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

Improvements #

Pragma Package Rename!

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

Integration Notes #

Pragma Package Rename

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

Deprecation #

Pragma Engine - REMOVED in 0.0.23:

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

Pragma Engine 0.0.22 #

2021-06-08

Features #

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

Improvements and Fixes #

  • CLI command for standalone db migration functionality is restored

New or Updated RPCs #

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

Integration Notes #

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

Deprecations #

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

Removed #

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

Pragma Engine 0.0.21 #

2021-06-04

Features #

  • Expose extension data on MatchEndNotification

2021-06-01

Features #

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

Deprecation #

Pragma Engine - Scheduled for REMOVAL in 0.0.22:

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

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

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

Pragma Engine 0.0.20 #

2021-05-26

Features #

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

Pragma Engine 0.0.19 #

2021-05-25

Features #

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

Deprecation #

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

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

    • InstancedEntry.instance_defaults to be replaced by ExtensionInstancedEntry.ext

    • Protos to be deleted since they are unused

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

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

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

Pragma Engine 0.0.18 #

2021-05-18

Deprecation #

  • REMOVED this release:
    • make.ps1 script removed

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

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

    • N/A

    • InstancedEntry.instance_defaults to be replaced by ExtensionInstancedEntry ext

Pragma Engine 0.0.17 #

2021-05-11

Features #

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

Deprecation #

  • REMOVED this release:

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

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

    • Content Data will no longer be loadable as embedded artifact

Pragma Engine 0.0.16 #

2021-05-04

Features #

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

Deprecation #

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

  • make.ps1 script
  • storePurchaseV1 RPC

Pragma Engine 0.0.15 #

2021-04-27

Features #

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

Improvements #

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

Pragma Engine 0.0.13 #

2021-04-20

Improvements #

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

Infrastructure #

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

Pragma Engine 0.0.7-0.0.12 #

2021-04-13

Features #

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

Improvements #

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

Infrastructure #

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

Pragma Engine 0.0.5 #

2021-03-23

Features #

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

Improvements #

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

Pragma Engine 0.0.3 #

2021-03-09

Features #

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

Pragma Engine 0.0.2 #

2021-03-02

Features #

  • Platform startup summary

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

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

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

    • Disconnect events now include an Error Enum
  • GetContentSha256ChecksumsV1Request

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