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 valuesOFF
,OPTIONAL
, orREQUIRED
.
[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
andInstancedItemUpdate
no longer require you to assign anUpdateEntryId
.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 setlegacyItemLoadBehavior: true
in the Inventory service config, though this may result in runtime errors.[Player Data] The Instanced Item Plugin’s
newInstanced()
andupdate()
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 hasPlayerLeave
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 ofoptional
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
orrepeated
.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
andProtocolType
can now be specified separately for client and server. #Description: Pragma SDK running on a game server now uses the new config fields
PartnerBackendAddress
andPartnerProtocolType
. These fields can be overridden via command line parameters:-PragmaPartnerBackendAddress="http://127.0.0.1:10100" -PragmaPartnerProtocolType="Http"
. If thePartnerBackendAddress
field is empty,BackendAddress
will be used instead.[SDKs] The Inventory service now supports item lookups by
catalogId
andinstanceId
. #Description: You can now look up items by
catalogId
andinstanceId
instead of iterating through the list onInventoryResults.InventoryFull
using the two new functionsGetInstancedItemsByCatalogId
andGetStackableItemsByCatalsogId
.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 fieldPartnerProtocolType
according to your engine.[Portal] The new Portal is now available! #
Description: The new Portal has better extensibility, clearer separation of customer data, and a simplified configuration. New capabilities include:
- Update and extend existing pages and portlets with components, pages, and actions.
- Use flags to toggle features with the
featureToggles
option. - Define custom rendering components for ext data in content and inventory.
- Use the
<Icon />
component to access 400+ new icons and add custom icons. - Leverage the new Less support across the entire Portal; all
.less
files are loaded and compiled automatically.
Related note: See integration note about custom content in Portal.
[Portal] Portal shows how much time remains before an event begins or ends. #
Description: You can now see the amount of time remaining before events start or end when viewing scheduled events in the Portal. This information is shown in a new
Status
column.The
Events
table can be seen in the Social Portal → Services menu → Game Title Management → Shards → Select a shard, then scroll down to theEvents
table.Deprecations #
[Game Flow] The
MatchLifecycleServiceConfig.enableMatchReconnect
boolean config has been deprecated in favor of theMatchLifecycleServiceConfig.matchReconnect
enum config. #Description: The
MatchLifecycleServiceConfig.matchReconnect
config will support an upcoming feature. The existingenableMatchReconnect
config is scheduled to be removed in Pragma Engine release 0.0.92. To migrate early, make the following replacement in your config file:original replacement removal release enableMatchReconnect: true
matchReconnect: "REQUIRED"
0.0.92 enableMatchReconnect: false
matchReconnect: "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 withstartMatch
. #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.
original replacement matchCapacity_partyStartMatchV1Request
matchCapacity_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.
original replacement enableInProgressMatchTimeout
enableMatchAbsoluteTimeout
inProgressMatchTimeoutMillis
matchAbsoluteTimeoutMillis
missedKeepAlivesBeforeCleanup
keepAliveMissesLimit
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
orSession
, 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
andsdk-types
, check custom code for references to the following Session calls and update them to their replacements:original replacement SessionServicePB
PlayerSessionRpc
Session
SessionCommon
[Game Flow] If your game server implementation uses the
MatchReady
call, generate anExtPlayerMatchDetails
object for each player. #Description: Game server implementations that use the
MatchReady
call must provideExtPlayerMatchDetails
for each player. This change was made to detect missingExtPlayerMatchDetails
. If the game server provides fewerExtPlayerMatchDetails
than the required number of players as defined by the ReportCapacity response, it will throw aMatchLifecycle_MissingPlayerExt
error.Integration step: In your game server’s response handling for
MatchCapacity::StartReportCapacityPolling
, while creating theMatchReady
request, anExtPlayerMatchDetails
object must be generated with theplayerId
for each player. These objects must then be put on theMatchReady
request before callingMatchLifecycle.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
andgetBroadcastParty
proto helpers on the Party service to be more accurate.Integration step:
original replacement Party.getParty
Party.getPartyProto
Party.getBroadcastParty
Party.getBroadcastPartyProto
[Game Flow] If you have a custom implementation of the Matchmaking Plugin, update references to
PotentialMatch
,ActiveMatch
, andMatchableParties
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
andPotentialMatch
, and to the name ofMatchableParties
.Integration steps: If you have a custom implementation of the Matchmaking Plugin, you will need to complete the following steps.
- Change the
MatchableParties
type toMatchable
, and update any related imports as necessary. - Update any references to
PotentialMatch
andActiveMatch
, 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 andupdate()
’s parameters. #Description: We’ve added in a new parameter called
pendingInventory
and renamed an existing parameterinitialInventory
in the Instanced Item Plugin’snewInstanced()
andupdate()
functions.Integration steps:
- Add the parameter
pendingInventory
to bothnewInstanced()
andupdate()
. - Rename the parameter
initialInventory
withstartingInventory
to bothnewInstanced()
andupdate()
.
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 withSOCIAL
orGAME
.
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:
original replacement UPragmaConnection::FConnectionError
FPragmaConnectionError
EProtocolError
EPragmaProtocolError
[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:
original replacement 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:
- Open the
pragma-engine/sdk
folder. - Find
PragmaInventoryCache.cpp
and remove#include "BehaviorTree/BTCompositeNode.h"
. - Find
PragmaCore.cpp
and comment outPRAGMA_LOG(Error, "Failed to load Pragma Core shared library.");
. - Run the
update-pragma-sdk.sh
script. - 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:
original replacement 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
.
- Related note: See feature note on the new Matchmaking Plugin method
[Updated Concepts] Added a new section on Configuring Protocols for HTTP and WebSocket connection on the Game Server Management page.
[Tech Blog] The Tech Blog has migrated from the docs site to Pragma’s main site, with a new landing page which includes new locations for articles.
[New Tech Blog Articles] Two new Content Data articles are live! Learn about the Content Data system with Part 1 and Part 2 of the Content Data article series.
January 13, 2023
Changes from 0.0.89 have been integrated into this release.
Features #
The updated Matchmaking service is live! #
Description: Our new version of the Matchmaking service currently supports the same features as the previous iteration, but with easier ways to write core matchmaking logic in the plugin, and improved implementation for custom games and other game types that don’t require matching with incoming parties. We’ll continue to add new functionality to this service.
Related note: See Docs note on the new Matchmaking page.
You can now send an idempotency key on the Apply Inventory Operations endpoints to ensure the data operations are applied only once. #
Description: These Apply Inventory Operations endpoints include:
InventoryRpc.ApplyInventoryOperationsOperatorV1Request
InventoryRpc.ApplyInventoryOperationsPartnerV1Request
InventoryRpc.ApplyInventoryOperationsServiceV1Request
If you assign an idempotency key, all Apply Inventory Operations’ requests withDataOperations
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 theInstancedItemPluginResult
. #Description: The update to
InstancedItemPluginResult
now allows you to return a null on theExtInstancedItem
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
, theMatchCapacity
service sets the used capacity to0
, which is then reported to Pragma Engine in theReportCapacity
poll. To reuse this game server state, pass in theOnComplete
handler that was used in theStartReportCapacityPolling
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 theStartReportCapacityPolling
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 afuture
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 PragmaSubsystems
. #Description: You can now check if Pragma Engine has been initialized without needing to hit the
assert
insideGetSession()
. Use the newHasSession()
method on PragmaLocalPlayer
andGameServer
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 inPragmaSDKAux
, 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 thePragmaSDKAux
dependency.Portal: Added
Tree
view alongsideRich
andRaw
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
, andGetInventoryPartnerV1
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 aServiceUpdateItemsResponse
with twoUpdateItemsResponse
s, 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
andupdates.player
to access filtered data.original replacement removal release GrantItemsPartnerV1
GrantItemsPartnerV2
0.0.91 DestroyItemsPartnerV1
DestroyItemsPartnerV2
0.0.91 DestroyItemsServiceV1
DestroyItemsServiceV2
0.0.91 GetInventoryPartnerV1
GetInventoryPartnerV2
0.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 newInventoryServiceForceGetInventory
. To find stackable and instanced inventory within this data, you can subscribe an event handler toInventoryService.OnInventoryUpdated
.Replace usages of
InventoryService.GetInventoryV2
withInventoryService.GetInventory
. If you require the client to forcibly refresh itself, you can useInventoryService.ForceGetInventory
.original replacement removal release InventoryService.GetInventoryV2
InventoryService.GetInventory
0.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.
- Example: Tests that use Ktor’s
- Use
@Isolated
to ensure a test runs entirely alone.- Example: Any tests that use
mockkStatic
should use@Isolated
.
- Example: Any tests that use
- 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()
andpartyWithPlayers()
methods have been combined. The new method is namedparty()
and preserves the functionality of both methods.Integration steps:
- Replace usages of
partyWithPlayers()
withparty()
. - If you’re using
party()
and want a party with zero players, pass innumPlayers = 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 atgame.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 usejobDatacenter
instead ofjobName
. #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 usejobDatacenter
instead ofjobName
. 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
andPragmaPartnerSessionGameAuthToken
. The SDK prioritizes these over values set inPragma.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
underInventoryServiceConfig
for all deployed environments. The following parameters must be assigned values:sizeBeforeExpirationEnforced,
maxTimeBetweenAccessMillis
, andsweepIntervalMillis
. We have provided local/dev defaults underpragma-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
fromInventoryOperationsPlugin.InventoryOperations
, you need to update server type. #Description: The return result from
InventoryOperationsPlugin.getInventoryOperationsFromMatchEnd()
no longer has a field forInstancedItemGrants
.Integration step: Convert from
InstancedItemGrant
toInstancedItemServerGrant
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 totrue
, aMatchKeepAliveV1Request
must be sent from the game server on an interval defined byMatchReadyV2Response.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
totrue
. #Description: To simplify the basic match loop setup, the default value for
enableMatchReconnect
has been changed tofalse
. 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 toplatformVersion
. #Description: We’ve added
version
properties to/v1/info
for each artifact type (platformVersion
,portalVersion
,contentVersion
, andconfigVersion
).Integration step: If you’re using the
version
properties endpoint in/v1/info
, you need to update it toplatformVersion
.original replacement version
platformVersion
Unreal SDK: If you use the
ErrorCode
result of theLogIn
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
usesEPragma_SdkError
enum values likeUnauthorized
,PlatformUnavailable
, andAlreadyLoggedIn
instead of those strings.Integration step: If you use the
ErrorCode
result ofUAccountService::LogIn
, the string value has changed. See theEPragma_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 usingResult.Error()
instead ofResult.ErrorCode()
.Unreal SDK: Update references to
PartyService.ResetParty
to expect a return value ofvoid
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 correspondingForceReset
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 ofvoid
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.
original replacement UPragmaInventoryService::GetInstancedItemsV1
UPragmaInventoryService::GetStackableItemsV1
UPragmaInventoryService::GetInventory
: You can see the instanced and stackable items within the response of this call.UPragmaInventoryService::GetInventoryV1
UPragmaInventoryService::GetInventory
UPragmaInventoryService::DeletePlayerInventoryV2
UPragmaInventoryService::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 todev-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-
orcommon.yml
files. An example can be found below or in theplatform/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 consideredDegraded
and the full disconnect timer had elapsed.
Docs #
[Updated Concepts Section] The Monetization section has been updated with a new Overview and new pages on Provider Entitlement and the Payment service.
[New Concepts Guide] Added a new page on Viewing and Editing Content in the Portal section.
[New Concepts Guide] Added a new page on Grants and Entitlements in the Player Data section.
[Updated Concepts Guide] The Matchmaking guide has been completely rewritten! This new page contains detailed and comprehensive information on our updated matchmaking service.
[Updated Concepts Guide] Updated the Match End guide to capture the Match Keep Alive Heartbeats default being changed to
true
.[Updated Concepts Guides] The Game Server Management and Match End pages under Game Flow have been edited for clarity and accuracy.
[Updated Tutorial] Updated the Limited Grants tutorial to include information on time windows.
[New Tutorial] Added a new Tutorial on creating a Battlepass.
[Updated SDK Guide] The Unreal SDK guide has been updated to be clearer and more accurate.
[New Tech Blog Video] A new video on Creating a Crafting System Using Stores has been posted.
[New Tech Blog Article] The Instanced Item series is now live! Learn how to create instanced items, custom content, and plugins.
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
, andconfigVersion
).Related note: See Integrations note about
/v1/info
.Purchasing and entitlement catalogs are now retrieved by
GetLoginData
. #Description:
GetLoginData
now includes the catalogs forItemBundles
andProviderEntitlementMappings
. Hidden item filtering is also supported forItemBundles
.You can now call
GetLoginData
through the SDK RichGameDataService
. #Description:
GameDataService
in the SDKs now propagates theGetLoginDataV2Response
. The client-side inventory cache of the RichInventoryService
will be updated through a new event calledOnGetLoginData
. We strongly recommend you use this new feature.To use this new endpoint, replace any uses of
GameDataServiceRaw
’sGetLoginData
with the new call:UPragmaGameDataService::GetLoginData()
GameDataService.GetLoginData()
GameDataService
’sGetLoginData
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
toHttp
withPragmaProtocolType={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 configuredGameServerVersions
.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 beforeUPragmaConnection::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 toplatformVersion
. #Description: We’re adding version properties to
/v1/info
for each artifact type (platformVersion
,portalVersion
,contentVersion
, and configVersion). You’ll need to useplatformVersion
instead ofversion
.original replacement removal release version platformVersion
0.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
andUPragmaInventoryService::GetStackableItemsV1
will be removed. UseUPragmaInventoryService::GetInventory
and you can see the instanced and stackable items within the response of this call.UPragmaInventoryService::GetInventoryV1
will be replaced withUPragmaInventoryService::GetInventory
.UPragmaInventoryService::DeletePlayerInventoryV2
will be replaced withUPragmaInventoryService::DeletePlayerInventory
.
original replacement removal release UPragmaInventoryService::GetInstancedItemsV1
,UPragmaInventoryService::GetStackableItemsV1
UPragmaInventoryService::GetInventory
You can see the instanced and stackable items within the response of this call.0.0.89 UPragmaInventoryService::GetInventoryV1
UPragmaInventoryService::GetInventory
0.0.89 UPragmaInventoryService::DeletePlayerInventoryV2
UPragmaInventoryService::DeletePlayerInventory
0.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:
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 thecommon.yml
andlocal-dev
files that were copied from our templates.original replacement CommonConfig.yml
common.yml
LocalConfig.yml
local-dev.yml
Update anything that extends a
ConfigObject
, such asServiceConfig
orPluginConfig
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.
- If you have unit tests that connect to the database (not ITs), replace any config creation to match the following example:
Original Replacement 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")
- Update shard
.env
files to export the correctENV_CONFIG
paths to match the following example:
Original Replacement 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"
- 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.- 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
gameShardId
s 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
andlobbyRpcExt.proto
inplatform\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.
Original Replacement 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.original replacement LinkIdentityProviderAccountV1Request
LinkIdentityProviderAccountServiceV1Request
LinkIdentityProviderAccountV1Response
LinkIdentityProviderAccountServiceV1Response
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.
original replacement class: "pragma.account.EpicIdentityProvider"
class: "pragma.account.EpicIdentityProviderPlugin"
class: "pragma.account.SteamIdentityProvider"
class: "pragma.account.SteamIdentityProviderPlugin"
Replace usages of
InventoryRpc.DeletePlayerInventoryV2()
withInventoryRpc.DeletePlayerInventoryV3()
. #Description: To complete the deprecation listed in release 0.0.87, we’ve removed this endpoint.
Integration step: Replace usages of
InventoryRpc.DeletePlayerInventoryV2()
withInventoryRpc.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 fileLocalhost.pragma_environment.json
. #Description: To be consistent with the Postman UI, we’ve renamed the
LocalNode1.pragma_environment.json
file toLocalhost.pragma_environment.json
.Integration step: To update your localhost environment, use the renamed file
Localhost.pragma_environment.json
.original replacement LocalNode1.pragma_environment.json
Localhost.pragma_environment.json
If you’re using the test helper method
matchCapacity_partyStartMatchV1Request
, replace it withmatchCapacity_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.
original replacement matchCapacity_partyStartMatchV1Request
matchCapacity_startMatchV1Request
If you have custom implementations of the
MatchmakingStrategy
interface, remove the functionsvalidateParty
andaddPartyToMatchAndBuildMatchmakingDetails
. #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 functionsvalidateParty
andaddPartyToMatchAndBuildMatchmakingDetails
.If you’re referencing SDK error enums by
int
(instead of byname
) update theint
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 byname
) update theint
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 anInstancedConcurrentMap
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 originalPARTY_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 aSessionChangedV1Notification
containing their match’sMATCH_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.
Original Replacement LocalConfig.yml local-dev.yml CommonConfig.yml common.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.
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 byMatchReconnectV1Notification
.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 oflinkIdentityProviderAccountV1
. #Description:
linkIdentityProviderAccountV1
is being renamed to conform to our current naming conventions. Replace all uses of it withlinkIdentityProviderAccountServiceV1
.original replacement removal release linkIdentityProviderAccountV1
linkIdentityProviderAccountServiceV1
0.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.
- Build the latest jar via
Update usages of
DeletePlayerInventoryV2
toDeletePlayerInventoryV3
. #Description: The RPCs for deleting player inventories now additionally remove all fulfillments. Update any usages of
DeletePlayerInventoryV2
toDeletePlayerInventoryV3
by release 0.0.88.original replacement removal release Raw Wrapper: PragmaInventoryServiceRaw.DeletePlayerInventoryV2()
Raw Wrapper: PragmaInventoryServiceRaw.DeletePlayerInventoryV3()
0.0.88 Rich Wrapper: PragmaInventoryService.DeletePlayerInventoryV2()
Rich Wrapper: PragmaInventoryService.DeletePlayerInventory()
0.0.88 original replacement removal 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
valueexpirationDays
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 ofGameDataRPC.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 theLoginData
payload. Note that this change only applies toGameDataRPC.GetLoginData
, asInventoryRpc.GetLoginData
has not been updated and should remain atV1
.Integration step: Update all usages of
GameDataRpc.GetLoginDataV1
toGameDataRpc.GetLoginDataV2
.original replacement PragmaGameDataServiceRaw.GetLoginDataV1
PragmaGameDataServiceRaw.GetLoginDataV2
original replacement GameData.Raw.GetLoginData
GameData.Raw.GetLoginDataV2
original replacement GetLoginDataV1Request
GetLoginDataV2Request
Update the config sections for
TokenValidatorNodeService
to theTokenDecoderNodeService
. #Description: The
TokenValidatorNodeService
has been renamed to theTokenDecoderNodeService
, due to the service no longer performing token validation and only performing token decoding. If you’ve used theTokenValidatorNodeService
directly in your code, update any references to the newTokenDecoderNodeService
. Note that the service’s Test FactorytokenValidatorConfig
was also renamed totokenDecoderConfig
.Integration step: Update the config sections for
TokenValidatorNodeService
to theTokenDecoderNodeService
.Original Replacement 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:original replacement 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.
- Game Operator Portal instructions:
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 ofGameDataRPC.GetLoginDataV1
. #Description:
GameDataRPC.GetLoginDataV1
is being deprecated due to changes toInventoryRPC.GetLoginDataV1
.GetLoginDataV2
brings necessary cleanup along with naming that more correctly aligns with inventory’s limited grant tracking ids as a part of theLoginData
payload.Unity:
Original Replacement Removal release GameData.Raw.GetLoginData
GameData.Raw.GetLoginDataV2
0.0.87 Unreal:
Original Replacement Removal release PragmaGameDataServiceRaw.GetLoginDataV1
PragmaGameDataServiceRaw.GetLoginDataV2
0.0.87 Direct calls to RPC endpoints:
Original Replacement Removal release GetLoginDataV1Request
GetLoginDataV2Request
0.0.87 Use
LoginDataPlugin.getLoginDataJobsV2
instead ofLoginDataPlugin.getLoginDataJobs
if you are not usingDefaultPragmaLoginDataPlugin
. #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 implementLoginDataPlugin.getLoginDataJobsV2
in custom implementations ofLoginDataPlugin
.Original Replacement Removal release LoginDataPlugin.getLoginDataJobs
LoginDataPlugin.getLoginDataJobsV2
0.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
withtrackingId
.
- Replace
- Remove all stackable specs for limited grant tracking in
content/src/StackableSpecs.json
. - Run the
contentdata apply
command.
- Delete
- If a custom service uses the
issuedLimitedGrantCatalogIds
field in theGetLoginData
call, it will need to be updated toissuedLimitedGrantTrackingIds
.
Clients must stop calling
matchReconnectV1
. Clients should instead listen for theMatchReconnectV1Notification
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 tomatchReconnectV1
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 theInventoryServiceConfig
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
orgetDisplayNameForPlayerIdPartnerV2
to include the new requiredgameShardId
parameter. #Description: To support a multigame (and therefore multishard) setup for Pragma Engine, we’ve added a requirement for the
gameShardId
parameter on thegetDisplayNameForPragmaPlayerIdV1
andgetDisplayNameForPlayerIdPartnerV2
requests.Integration step: Update usages of
getDisplayNameForPragmaPlayerIdV1
orgetDisplayNameForPlayerIdPartnerV2
from an SDK or any direct RPC call to includegameShardId
on the request. You can access thegameShardId
by calling a game shard’s<backendAddress>/v1/info
endpoint.Define
columnNameOfPropertyToConsistentHash
on all custom instances ofPartitionDatabaseConfig
. #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 customPartitionDatabaseConfigs
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()
onDaoNodeServices
prior to callingrun()
. #Description: Previously, you could call
run()
onDaoNodeServices
without callingonConfigChanged()
. However, this is no longer the case. You must callonConfigChanged()
beforerun()
in order for the service to start.Integration step: Ensure
onConfigChanged()
is called beforerun()
onDaoNodeServices
.If you’re using
getHostPortMap
onAbstractDaoNodeService
, switch tohostPortSchemas
inDatabaseConfig
. #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.Original Replacement AbstractDaoNodeService::getHostPortMap
DatabaseConfig::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 tolocal_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 theConnection
object. #Description: The Unreal and Unity SDKs have moved the
GameShardId
out of theSDKConfig
and onto theConnection
object.Integration step:
- Update references to the
GameShardId
so that it’s pulled from the new location on theConnection
object.- Unreal:
Connection()->GetGameShardId()
- Unity:
Connection.GameShardId
- Unreal:
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 newMatchLifecycleService.MatchReady
andMatchEnd
functions are used.
Docs #
[Updated User Guide] Removed stackable trackables from Limited Grants User Guide.
[Updated SDK Guides] Added details for completing Discord Role-based authentication to Unreal and Unity Guides.
[New Tech Blog Video] Purchasing Stackable Items in a Store video is now live and embedded in its corresponding tech blog article. It is also available via YouTube and the Pragma Blog.
- Drop all inventory databases for all environments. This is required to avoid duplicating limited grant fulfillment, and it will clear out all stackable trackables.
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
andOnMatchmakingFailed
SDK events improperly clearing cached party data.Docs #
[Updated SDK Guide] Added section on client-side authentication with Android to Unity Logging Into the Platform page.
[Updated Services Guide] Added section on game server selection based on player ping to the Matchmaking page.
[Updated Services Guide] Updated the description on the Game Flow Overview page.
[Updated Services Guide] Added section on secret encryption to the Configuration page in Customization.
[Updated Services Guide] Updated the Items page for clarity and accuracy.
September 13th, 2022
Features #
Twitch authentication now available.
- Description: You can now use
TwitchIdentityProviderPlugin
to configure Twitch login with Pragma Engine.
Added endpoint that returns a map of grouped content data for any given content type.
- Description: Added new
getContentSourceOperatorV1
endpoint in Inventory service that returns content data grouped by source file for a given content type.
Party leaders can now assign a new leader or add additional leaders.
Description: A party leader can assign another player to be party leader by calling
assignPartyLeaderV1
with thePragmaId
of the player to assign.When
PartyConfig
enableTransferPartyLeader
is true, the player that callsassignPartyLeaderV1
will lose leader privileges (default behavior). IfenableTransferPartyLeader
is set to false, theassignPartyLeaderV1
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()
- Helper to get the list of all leaders:
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
- Helper to get the list of all leaders:
Deprecations #
If you’re using
getHostPortMap
onAbstractDaoNodeService
, switch tohostPortSchemas
inDatabaseConfig
.- 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.
Original Replacement Removal Patch AbstractDaoNodeService::getHostPortMap
DatabaseConfig::hostPortSchemas
0.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 frompragma-engine
into the plugin. As of this release, the Buildkite-related scripts are being deleted frompragma-engine
, so you must ensure thepragma-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 aplugin-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 in4-demo/buildkite/config.json
.
- Confirm that
Unreal SDK: Rename
UpdatePlayerSelectionsV1
toCanUpdatePlayerSelectionsV1
to match naming patterns.- Description: This change was made to fix a naming inconsistency.
- Integration step: Update the following instances:
Original Replacement bool UPragmaPartyService::UpdatePlayerSelectionsV1() const
bool UPragmaPartyService::CanUpdatePlayerSelectionsV1() const
bool UPragmaPartyService::UpdatePlayerSelectionsV1(FPragmaError& OutError) const
bool 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 thePragmaError ID
and print out debug information when inDEVELOPMENT
.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.
- Description: You can now use
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
andUPragmaSessionGameServerSubsystem
no longer automatically initializeSdkConfig
with default values. - Integration step: If using
UPragmaSessionLocalPlayerSubsystem
orUPragmaSessionGameServerSubsystem
, you must call the respectiveInitSession
before callingGetSession
.
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 ofengine-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.
- Description: Unity and Unreal game clients can now listen for a new SDK event named
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
totrue
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
andMatchLifecycleService.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
andrefresh_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.
- Update configuration to not include
Migrate any usages of the
StartReportCapacityPolling
that does not take in aGameServerZone
to the newStartReportCapacityPolling
that does.- Description: The version of the
MatchCapacityService.StartReportCapacityPolling
function in the SDKs that does not take in aGameServerZone
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 aGameServerZone
.original replacement Unity: public void StartReportCapacityPolling(string serverId, string gameVersion, float timeout, MatchAllocatedDelegate onComplete)
Unity: public void StartReportCapacityPolling(string serverId, string gameVersion, string gameServerZone, float timeout, MatchAllocatedDelegate onComplete)
Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling(FString ServerId, FString GameVersion, float Timeout,const FMatchAllocatedDelegate& OnComplete)
Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling(FString ServerId, FString GameVersion, FString GameServerZone, float Timeout, const FMatchAllocatedDelegate& OnComplete)
- If you don’t use
GameServerZone
, you can pass an empty string into these methods.
- Migrate any usages to the
Unity: If your tests use any of the helpers listed below, update your
using
imports to include the newhelpers
folder.- Description: A few test helper files in the Unity SDK have been moved into a
helpers
directory for better organization. The new folder istests/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 newhelpers
folder (i.e.using test.helpers.AsyncTest
).
- If your tests were using any of the listed helpers, update your
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.
- Description: You can configure the Keep Alive loop by setting the
August 16th, 2022
Features #
Added a new
MatchLifecycleConfig
feature calledinProgressMatchTimeoutMillis
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) andInventoryOperationsPlugin.InventoryOperations
(on MatchEnd). - Details:
InstancedItemPluginResult
is returned byInstancedItemPlugin.newInstanced
andInstancedItemPlugin.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 byInventoryOperations.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 valuespartnerSessionGameAuthToken
andpartnerSessionSocialAuthToken
have been added to allow Partner sessions to designate specific tokens per backend. - Integration steps:
- In the Unreal/Unity SDK, update any configs with a Partner session auth token (such as in
pragma.json
).original replacement partnerSessionAuthToken
partnerSessionGameAuthToken
- Add a
partnerSessionSocialAuthToken
config option for situations where a Partner session needs to connect to the Social backend, and provide it with a Partner Social token.
- In the Unreal/Unity SDK, update any configs with a Partner session auth token (such as in
Replace the listed RPC request implementation calls with their replacements, as they are being removed.
- Description: This is part of our larger engine cleanup.
- Integration step: If you’re using any of these calls in plugins or custom services, replace them and apply transforms when necessary.
original replacement Service::requestRpcAndTransform()
Service::requestRpc()
RpcClient::requestRpcAsync()
async { requestRpc() }
Service::requestRpcAsync()
async { requestRpc() }
Service::requestRpcAsyncAndTransform()
async { Service::requestRpc() }
Update
PartyPlugin
implementation by migrating any logic fromrecreate
intoreturnFromMatchmaking
andreturnFromMatch
.- Description: The method
recreate
has been replaced by thereturnFromMatchmaking
&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 functionsreturnFromMatchmaking
andreturnFromMatch
. - Delete implementation of
recreate
from interface.original replacement recreate
returnFromMatchmaking
&returnFromMatch
- Open
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.
- Description: The new
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 accountsAccountService.AddAccountTagsPartnerV1(playerSocialIds, tagsToAdd)
: add tags to multiple accountsAccountService.removeAccountTagsPartnerV1(playerSocialIds, tagsToRemove)
: remove tags from multiple accounts
- New endpoint and SDK binding:
AccountService.viewTagsPartnerV1()
: retrieve all existing tags in the system
- New SDK bindings for the following existing Partner endpoints:
Integrations #
Add the
requestingPlayer
parameter to implementations ofPartyPlugin.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 thePartyPlugin.updateParty()
method. Update any references toUpdateDisplayNameV1Request
toUpdateDisplayNameOperatorV1Request
.
Original Replacement 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, correctcolumnNameOfpropertyToConsistentHash
inInventoryDaoConfig
by capitalizing the wordProperty
.- Description: We’ve adjusted this capitalization to more accurately follow naming standards.
- Integration step:
- Make the following change in
InventoryDaoConfig
:original replacement columnNameOfpropertyToConsistentHash
columnNameOfPropertyToConsistentHash
- Make the following change in
Migrate all instances of
ShutdownV1Notification
to the newRemovedV1Notification
.- Description: We’ve replaced
ShutdownV1Notification
with a more accurately named notification calledRemovedV1Notification
. This should be used to alert clients when a player is removed from a party. - Integration step: Complete the following migration:
original replacement ShutdownV1Notification
RemovedNotification
Replace all uses of
authenticateOrCreateV1
withauthenticateOrCreateV2
.- Description: The
authenticateOrCreateV1
http
endpoint and theAuthenticateOrCreateV1Request
andAuthenticateOrCreateV1Response
messages have been removed. - Integration steps:
- Update any usages of
authenticateOrCreateV1
endpoint to theauthenticateOrCreateV2
endpoint and use the correspondingAuthenticateOrCreateV2Request
andAuthenticateOrCreateV2Response
messages. - The
AuthenticateOrCreateV2Response
no longer contains thepragma_player_token
. Instead you should use thepragma_game_toke
n andpragma_social_token
depending on what service is being connected to.original replacement authenticateOrCreateV1
authenticateOrCreateV2
pragma_player_token
pragma_game_token
andpragma_social_token
- Update any usages of
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 theMatchFoundPlugin
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 frompragma.matchmaking.MatchFoundPlugin
topragma.matchlifecycle.MatchFoundPlugin
. - If your config uses the Pragma Engine-provided
pragma.matchmaking.DefaultMatchFoundPlugin
, update it topragma.matchlifecycle.DefaultMatchFoundPlugin
.
- If you’ve defined your own implementation of
Update all references to
UpdateDisplayNameV1Request
toUpdateDisplayNameOperatorV1Request
.- Description: We’ve renamed the
UpdateDisplayNameV1Request
Operator RPC to match our naming standards and avoid session-type collisions. - Integration step: Update references to
UpdateDisplayNameV1Request
to capture the rename.original replacement UpdateDisplayNameV1Request
UpdateDisplayNameOperatorV1Request
- Note that If you’ve built a Portal from
source
instead of using the packagedportal-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"
- Description: The
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 serviceCreatePartyV1
call and can be updated withSetPreferredGameServerZonesV1
. This list can then be used byMatchmakingStrategy.addToMatchAndBuildMatchmakingDetails
to select a singleGameServerZone
to be used in Matchmaking. Game servers should pass in theGameServerZone
toMatchCapacityService.StartReportCapacityPolling
. - Related notes: See related deprecation, feature, and integration notes for
GameServerZone
.
- Description: Party leaders specify a list of
- A
GameServerZone
can now be mapped to a Multiplay region using theMultiplayCapacityProvider
.- Description:
MultiplayCapacityProvider
can now take aGameServerZone
and map it to a Multiplay region. To use this, provide a new configuration to mapGameServerZones
to MultiplayRegionIds
and remove the oldregionId
field from the config.
If usingAllocateV2
,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’sMatchmakingService.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
.
- Description:
- 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 providedPlayerId
from a party, andCanKickPlayerV1
lets the client know if it’s able to execute a kick.
When a player is kicked, everyone in the party receives aPartyDetailsV1Notification
to update the party state, and the kicked player receives aRemovedV1Notification
with aKICKED
reason.
- Description: Players can be kicked from a party, which prevents them from rejoining the party unless they receive a new invitation.
- [Portal] All
config.json
data has been relocated toportalDevConfig.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. Theconfig.json
data can be found underapp.config
andapp.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"] } }, }
- Description: The
Deprecations #
Update
MatchCapacityService.StartReportCapacityPolling
to take the new parameterGameServerZone
.- Description: The
StartReportCapacityPolling
function in the MatchCapacity service takes the new parameterGameServerZone
. You will need to either update your code in the SDKs or pass in an empty string.
Original Replacement Removal Patch Unity: public void StartReportCapacityPolling( string serverId, string gameVersion, float timeout, MatchAllocatedDelegate onComplete )
Unity: public void StartReportCapacityPolling( string serverId, string gameVersion, string gameServerZone, float timeout, MatchAllocatedDelegate onComplete )
0.0.80 Unreal: void UPragmaMatchCapacityService::StartReportCapacityPolling( FString ServerId, FString GameVersion, float Timeout, const FMatchAllocatedDelegate& OnComplete )
Unreal: UPragmaMatchCapacityService::StartReportCapacityPolling( FString ServerId, FString GameVersion, FString GameServerZone, float Timeout, const FMatchAllocatedDelegate& OnComplete )
0.0.80 - Related notes: See related integration and feature notes for
GameServerZone
.
- Description: The
Replace the listed RPC request implementation calls with their replacements, as they are being removed.
- Description: This is part of our larger engine cleanup. If you’re using any of these calls in plugins or custom services, replace them and apply transforms when necessary.
original replacement removal patch Service::requestRpcAndTransform()
Service::requestRpc()
0.0.80 RpcClient::requestRpcAsync()
async { requestRpc() }
0.0.80 Service::requestRpcAsync()
async { requestRpc() }
0.0.80 Service::requestRpcAsyncAndTransform()
async { Service::requestRpc() }
0.0.80
- 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.
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 valuespartnerSessionGameAuthToken
andpartnerSessionSocialAuthToken
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 apartnerSessionSocialAuthToken
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 inpragma.json
).original replacement removal patch partnerSessionAuthToken
partnerSessionGameAuthToken
0.0.80
- Description: The original
Integrations #
- If you’ve customized your
CapacityTracker
orMatchmakingStrategy
, you will need to update your plugins for the newGameServerZone
features.- Description: Studios who have customized their own
CapacityTracker
orMatchmakingStrategy
will need to update their plugins. These two game loop plugins allow the user to set upGameServerZone
flows within their match loop. - Integration steps:
- Update implementations of the
CapacityTracker
add
function to receive a new parameter indicating whichGameServerZone
a game should be created in. - Update implementations of the
MatchmakingStrategy
functionaddToMatchAndBuildMatchmakingDetails
to return aPair<ExtCreateMatchV1Request, String>?
. The second new string return value allows the plugin to indicate whichGameServerZone
the match should be created in. If you don’t want to useGameServerZone
, use an empty string here.original replacement ExtCreateMatchV1Request?
Pair<ExtCreateMatchV1Request, String>?
- Update implementations of the
- Description: Studios who have customized their own
- Add new
ExtHiddenPartyData
andExtHiddenPlayerData
proto definitions topartyRpcExt.proto
.- Description: The new
ExtHiddenPartyData
andExtHiddenPlayerData
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 { }
- Description: The new
- If you’ve implemented your own MatchCapacity provider, remove the
coroutineScope
argument from theinit()
method.- Description: To increase product maintainability and reliability,
CapacityProvider.init()
no longer takescoroutineScope
as an argument. - Integration step: If you’ve implemented your own MatchCapacity provider from the ground up, remove
coroutineScope
from itsinit()
method. If you’ve extended an existing Pragma Engine MatchCapacity provider, no action is required.
If you still needcoroutineScope
support, please reach out to us directly.
- Description: To increase product maintainability and reliability,
- [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. TheattachPortalModule
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 anApplication
instead of aRouting
object. For example:
- Description: Anyone who has written a custom
Original Replacement override fun attachPortalRoutes( routing: Routing, pragmaNode: PragmaNode, infoEndpoint: Url ) { routing.route("config/config.json") { get { call.respondText( buildConfigJson(pragmaNode,infoEndpoint), ContentType.Application.Json ) } } routing.static { staticRootFolder = File(config.portalSource) files(".") default("index.html") } }
override fun attachPortalRoutes( application: Application, pragmaNode: PragmaNode, infoEndpoint: Url ) { application.apply { routing { options { call.respond(HttpStatusCode.OK) } route("config/config.json") { get { call.respondText( buildConfigJson( pragmaNode, infoEndpoint ), ContentType.Application.Json ) } } static { staticRootFolder = File(config.portalSource) files(".") default("index.html") } } } }
- [Unreal] Update C++ Raw Service class names from
Pragma
to the root of your proto package.- Description: For any generated raw services, the C++ class names have changed to use the root of your proto package instead of
Pragma
. - Integration step: Update generated custom raw service names:
original replacement UPragmaCustomServiceRaw
UGameCustomServiceRaw
- Description: For any generated raw services, the C++ class names have changed to use the root of your proto package instead of
Docs #
- [New Services Guide] Dependent Jobs services guide is now live!
- [Updated Services Guide] Updated Login & Session services guide with information about dependent jobs.
- [Updated Services Guide] Updated Party services guide with a quick guide on using local game servers with Party matchmaking.
- [New Services Guide] New Custom Services landing page is now live!
- Description: The brand new Custom Services landing page provides the information needed to get started with extending Pragma Engine using custom services.
- [API Reference] Third-level nesting of types within packages for API ref docs is now live.
- [Pragma Blog] Setting Up Pragma Engine video tutorial is now live!
- [Tech Blog] The Pragma Engine Tech Blog is now live!
- Description: The Tech Blog provides friendly, accessible articles about Pragma Engine’s features, functions, and capabilities.
- [New Tech Blog articles] The Stackables series is now live!
- 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.
July 26th, 2022
Deprecations #
- Migrate all instances of
ShutdownV1Notification
to the newRemovedV1Notification
.- Description: We’ve replaced
ShutdownV1Notification
with a more accurately named notification calledRemovedV1Notification
. This should be used to alert clients when a player is removed from a party.Original Replacement Removal Patch ShutdownV1Notification
RemovedV1Notification
0.0.78
- Description: We’ve replaced
Integrations #
Update any references from the
TestFactory
functiongenerateList2
togenerateList
.- 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
functiongenerateList2
togenerateList
.Original Replacement TestFactoryUtils.generateList2
TestFactoryUtils.generateList
- Update any references in test code from the
- Description: Two similar implementations of the
Update any references in SDK code from
OnMatchStartFailureV1Notification
toOnMatchFailureV1Notification
.- 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’sOnMatchStartFailureV1Notification
to the rawMatchLifecycle
service’sOnMatchFailureV1Notification
event.Original Replacement OnMatchStartFailureV1Notification
OnMatchFailureV1Notification
Update any references in SDK code for the listed match-related service handlers from
PartyServiceRaw
toMatchLifecycleServiceRaw
.- 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 inMatchLifecycleServiceRaw
.Original Replacement PartyServiceRaw.OnMatchReadyV1Notification
MatchLifecycleServiceRaw.OnMatchReadyV1Notification
PartyServiceRaw.OnMatchFailedV1Notification
MatchLifecycleServiceRaw.OnMatchFailedV1Notification
PartyServiceRaw.OnMatchReconnectV1Notification
MatchLifecycleServiceRaw.OnMatchReconnectV1Notification
- Update any references in SDK code for the following raw service handlers from
- 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
Update references to
CostEntry
andPurchaseRequirements
to their new locations inInventoryCommon
.- Description: To support the ongoing development of a microtransaction feature,
CostEntry
andPurchaseRequirements
needed more shareable access, so they’ve been moved toInventoryCommon
. - Integration step:
- Update references to
CostEntry
andPurchaseRequirements
from their old locations inInventoryContent
to their new locations inInventoryCommon
.Original Replacement InventoryContent.CostEntry
InventoryCommon.CostEntry
InventoryContent.PurchaseRequirements
InventoryCommon.PurchaseRequirements
- Update references to
- Description: To support the ongoing development of a microtransaction feature,
If you’ve implemented the
PartyPlugin
, update theonRemovePlayer
function with the newRemovalReason
field.Description:
PartyPlugin.onRemovePlayer
has a newRemovalReason
field which provides the reason for a player leaving a party. This change only impacts studios who have already implemented theirPartyPlugin
.Integration step:
- Update the
onRemovePlayer
function with the newRemovalReason
field.
Original Replacement override suspend fun onRemovePlayer( party: Party, removedPlayer: PartyPlayer ) { ... }
override suspend fun onRemovePlayer( party: Party, removedPlayer: PartyPlayer, removalReason: RemovalReason ) { ... }
- Update the
Unreal: Replace
ReportCapacityUntilMatchAllocated
withStartReportCapacityPolling
.- Description: This change will make sure that
ReportCapacity
continues to poll even after finding a match. Note that the order of theReportCapacityTimeout
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
withStartReportCapacityPolling
.Original Replacement ReportCapacityUntilMatchAllocated
StartReportCapacityPolling
- Replace
- Description: This change will make sure that
Docs #
- [New User Guide] New Custom Services User Guide is now live!
- [Updated SDKs & Tools Guides] Updated SDKs & Tools Guides to have third-level nesting for Steam and Discord tutorials.
- [Updated Services Guide] Updated Using Discord section of the Authentication Service Guide.
- Migrate all instances of
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 theMatchmakingParty.playerInfoList
list. When theteamNumber
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.
- 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
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 ofFString
by using theexport_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 ofFString
. This works for fields tagged with the custom optionexport_as_key
. Note that you may need to Reload All Maven Projects before the new option is recognized in Intellij.
- Description: To improve code performance by reducing string operations in some proto messages, you can now use Unreal code generation to generate
Unreal: Pragma-provided subsystems can now initialize their
PragmaSession
with a customSdkConfig
.- Description: You can now use the Pragma-provided
PragmaSessionLocalPlayerSubsystem
andPragmaSessionGameServerSubsystem
with custom runtime configurations instead of needing to manage your ownPragmaSession
pointer.
- Description: You can now use the Pragma-provided
Integrations #
- Migrate all
GameDataStrategyPlugin
logic in the newLoginDataPlugin
.- 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
intoLoginDataPlugin
. WhileGameDataStrategyPlugin
andLoginDataPlugin
are both designed to accomplish the same tasks, their structures are different, so you cannot simply copy your existing code over.original replacement GameDataStrategyPlugin
LoginDataPlugin
- Migrate all your custom logic from
- Description: The
Bugs and Fixes #
- Unity: Fixed race condition in WebSocket send causing silent disconnect with no reconnect.
Docs #
- [New Services Guide] New Portal Services section is now live!
- Description: A new Services section about the Portal has been added. This includes an overview, getting started steps, and customization using portlets.
July 12th, 2022
Features #
- New Operator endpoint added to list and filter player identities with an additional requirement for game shard ID.
- Description: We’ve added a new endpoint
GetPragmaPlayerOverviewsOperatorV1
. This has the same filtering capabilities as theGetPragmaAccountOverviewsOperatorV1
endpoint, but also requires a game shard ID. - Postman Path:
- Description: We’ve added a new endpoint
- 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 runningmake 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
- Description: Unreal raw service code is now automatically generated based on protobuf RPCs. These classes can be found under the generated
Deprecations #
- Replace
ReportCapacityUntilMatchAllocated
withStartReportCapacityPolling
. Note that the order of theReportCapacityTimeout
argument and callback (the last 2 arguments) needs to be reversed.- Description: This change will make sure that
ReportCapacity
continues to poll even after finding a match.Original Replacement Removal Patch ReportCapacityUntilMatchAllocated
StartReportCapacityPolling
0.0.77
- Description: This change will make sure that
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
tofalse
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
- Description: We’ve changed Portal’s default for
- 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
toHTTP
(defaults toWebSocket
). 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
;
- Game Server only: Change SDK config option
- Handwritten raw service integration:
- Confirm there are no conflicting file names with the new automatically generated files.
- Automatic generation setup:
- 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 inVeryVerbose
.
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.
- New Operator endpoint added to list and filter player identities with an additional requirement for game shard ID.
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.
- Description: You can now update or grant stackable and instanced items on a per-player basis at match end via the new
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 theInstancedItemPlugin
interface to support this new feature, so you will need to make updates to yourInstancedItemPlugin
.Integration steps:
UpdateResult
has been renamed toInstancedItemPluginResult
to reflect that this is the return type for bothInstancedItemPlugin.newInstanced()
andInstancedItemPlugin.update()
.
In addition to the new return type,
newInstanced()
has additional parameters.Original Replacement fun newInstanced( instancedSpec: InventoryContent.InstancedSpec, clientRequestExt: ExtPurchaseRequest?, serverRequestExt: ExtInstancedItemServerGrant? ): ExtInstancedItem
fun newInstanced( instancedSpec: InventoryContent.InstancedSpec, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtPurchaseRequest?, serverRequestExt: ExtInstancedItemServerGrant? ): InstancedItemPluginResult
fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult
fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): InstancedItemPluginResult
Follow the integration steps below to fully remove the Progression service. Note that steps are organized based on your Pragma Engine version.
- Description: The Progression service and all related protos, classes, and utils have finally been removed. The Progression service and all related protos, classes, and uils have finally been removed.
- Integration steps: Depending on the version of Pragma Engine you’re upgrading from, steps will vary.
- If you’re currently on Pragma Engine 0.0.70 or later:
Rename the following service calls:
Original Replacement MatchEndV2
MatchEndV4
PlayerMatchEndV2
PlayerMatchEndV4
After confirming that they do not contain any wanted data, manually drop the
player_progression
databases.If you’re using the Docker environment provided via
/pragma-engine/platform/devenv/docker-compose-devenv
for local development, you can also drop the following databases:ete_test_game_player_progression1
ete_test_game_player_progression2
lobby_match_ete_test_game_player_progression1
lobby_match_ete_test_game_player_progression2
local_game_player_progression1
local_game_player_progression2
test_local_game_player_progression1
Test_local_game_player_progression2
- If you’re currently on Pragma Engine 0.0.69 or earlier, update to Pragma Engine 0.0.73 first by following all required integrations listed in prior release notes, then update to Pragma Engine 0.0.74 by following the steps detailed in this release note.
- If you’re currently on Pragma Engine 0.0.70 or later:
- If you’re an early user of
PlayerDataUpdatesPlugin
, rename thePlayerDataUpdatesPlugin
toInventoryOperationsPlugin
.- 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 thePlayerInfoV2
payload that is sent to game servers inMatchDataV2
. This field will be populated with the team number the player was assigned in matchmaking.
- You can now trigger a variety of inventory operations on a per-player basis at match end via the new
June 28th, 2022
Features #
- New game loop configuration options available.
- Description: We’ve added the following new config options for match lifecycle:
SessionConfig.enableMatchReconnect
andMatchLifecycleServiceConfig.enablePartyRecreate
. These both default to true, so to switch off match reconnect and party recreation configs, you’ll need to switch them to false.
- Description: We’ve added the following new config options for match lifecycle:
- 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 theDefaultGameServerCompatibilityPlugin
.
- Description: To allow easy customization of a hardcoded game server version for CI/testing scenarios, we’ve introduced a
InventoryService
now supports multiple updates to a singleInstancedItem
through match end processing or the variousUpdateItem
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 fieldserverInstancedItemUpdates
which is aList<ServerInstancedItemUpdate>
.
Integrations #
Modify your custom services by following the provided directions.
Description: We have reduced the number of thread pools in Pragma Engine to make the overall system more monitorable and configurable. This may affect your custom services.
Integration steps:
- Make the following changes in your custom service.
Original Replacement launch
scope.launch
async
scope.async
coroutineContext
scope.coroutineContext
- If you rely on
PragmaNode
being aCoroutineScope
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 ofStorePlugin
andCraftingPlugin
.- 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
- Remove the
- Description: To prepare for the deletion of
Replace usage of
MatchProcessedV2Notification
withMatchProcessedV3Notification
.- Description: To prepare for the deletion of
ProgressionService
, we are disabling support forMatchProcessedV2Notification
in order to remove progression-related data. - Integration steps:
- Replace usage of
MatchProcessedV2Notification
withMatchProcessedV3Notification
.
Original Replacement MatchProcessedV2Notification
MatchProcessedV3Notification
- Replace usage of
- Description: To prepare for the deletion of
Add new
inventoryData
parameter toupdate()
method in custom implementations ofInstancedItemPlugin
.Description: The
InstancedItemPlugin
interface has been updated. Theupdate()
method now expectsinventoryData
to be passed in.inventoryData
contains a snapshot of the player’s inventory.Integration steps:
- Change the
InstancedItemPlugin.update()
method to include the newinventoryData
parameter.
Original Replacement fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult
fun update( initialInstancedItem: InstancedItem, instancedSpec: InventoryContent.InstancedSpec, updateEntry: InventoryContent.UpdateEntry, inventoryContent: InventoryServiceContent, inventoryData: InventoryData, clientRequestExt: ExtInstancedItemUpdate?, serverRequestExt: ExtInstancedItemServerUpdate? ): UpdateResult
- Note that the data class
UpdateResult
has also been updated with a new parameter, but as it has a default value, no integration steps are required.
- Change the
You may need to create your own test factory if you use certain
InventoryProtoTestFactory
methods.Description: Certain
InventoryProtoTestFactory
methods have been changed to return the default instance.Integration steps:
- If you use any of the below
InventoryProtoTestFactory
methods, create your own test factory with the provided replacement or an appropriate equivalent.
Original Replacement InventoryProtoTestFactory.extStackableSpec()
fun extStackableSpec(i: Int) = generateProto(ExtStackableSpec::class, i)
InventoryProtoTestFactory.extInstancedItemServerGrant(I:Int)
fun extInstancedItemServerGrant(i: Int) = generateProto(ExtInstancedItemServerGrant::class, i)
- If you use any of the below
Bugs and Fixes #
- Removed references to the
awsRegion
configuration in theMultiplayCapacityProvider
, as this value will always beeu-west-1
according to Multiplay.
- New game loop configuration options available.
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 newLoginDataPlugin
.- 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
intoLoginDataPlugin
. WhileGameDataStrategyPlugin
andLoginDataPlugin
are both designed to accomplish the same tasks, their structures are different, so you cannot simply copy your existing code over.Original Replacement Removal Patch GameDataStrategyPlugin
LoginDataPlugin
0.0.74
- Reimplement all your custom logic from
- Description: The
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 theDependentJobContext
(oldMatchEndContext
) and theThreadsafeMutable
(oldConcurrentNotificationBuilder
) are now provided on the method signature of theDependentJob
(oldMatchEndBuilder
) instead of injected on construction.Integration steps:
- Rename the following items:
Original Replacement MatchEndPlugin.getMatchEndBuilders
MatchEndPlugin.getMatchEndJobs
MatchEndContext
DependentJobContext
ConcurrentNotificationBuilder
ThreadsafeMutable
MatchEndBuilder
MatchEndDependentJob
- Access
DependentJobContext
andThreadsafeMutable
via the methods onMatchEndDependentJob
.
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
andmatchEndV2
endpoints tomatchEndV4
.Description: The Service endpoints
InventoryService.matchEndV1
andInventoryService.matchEndV2
have been replaced withInventoryService.matchEndV4
, along with related protos.
These calls only require integration if you’re calling them from a custom service. Pragma Engine handles all version bumps for Pragma-owned services.Integration steps:
- Update references to the following:
Original Replacement InventoryService.matchEndV1
InventoryService.matchEndV2
InventoryService.matchEndV4
InventoryRpc.MatchEndV1Request
InventoryRpc.MatchEndV1Response
InventoryRpc.MatchEndV2Request
InventoryRpc.MatchEndV2Response
InventoryRpc.MatchEndV4Request
InventoryRpc.MatchEndV4Response
Update references to Inventory service’s
deletePlayerInventoryV1
endpoint todeletePlayerInventoryV2
.Description: The dev-only endpoint Player endpoint
InventoryService.deletePlayerInventoryV1
has been replaced withInventoryService.deletePlayerInventoryV2
, along with related protos.Integration steps:
- Update references to the following:
Original Replacement InventoryService.deletePlayerInventoryV1
InventoryService.deletePlayerInventoryV2
InventoryRpc.DeletePlayerInventoryV1
InventoryRpc.DeletePlayerInventoryV2
Update references to Lobby service’s endpoint
lockV1
tolockV2
.Description: The Service endpoint
LobbyService.lockV1
has been replaced withLobbyService.lockV2
, along with related protos.
These calls only require integration if you’re calling them from a custom service. Pragma Engine handles all version bumps for Pragma-owned services.Integration step:
- Update references to the following:
Original Replacement LobbyService.lockV1
LobbyService.lockV2
LobbyRpc.LockV1Request
LobbyRpc.LockV1Response
LobbyRpc.LockV2Request
LobbyRpc.LockV2Response
Update references to Match Lifecycle service’s
matchendV3
tomatchEndV4
.Description: The Partner endpoint
MatchlifecycleService.matchEndV3
has been replaced withMatchlifecycleService.matchEndV4
, along with related protos.
The new endpoint does not include any Progression-related data fields on the payload.
Note thatmatchEndV4
can still sendMatchEndNotificationV2
messages, which have Progression-related fields, as theMatchEndNotificationV2
deprecation is still in progress.Integration step:
- Update references to the following:
Original Replacement MatchlifecycleService.matchEndV3
MatchlifecycleService.matchEndV4
MatchlifecycleRpc.MatchEndV3Request
MatchlifecycleRpc.MatchEndV3Response
MatchlifecycleRpc.MatchEndV4Request
MatchlifecycleRpc.MatchEndV4Response
Modify all custom
IdentityProviders
to returnIdProviderAccount
instead ofPragmaResult<IdProviderAccount, PragmaError>
.- Description: The validate function in
IdentityProviderPlugins
has been changed to either return anIdProviderAccount
on success or to throw aPragmaException
otherwise. - Integration step:
- Modify any custom
IdentityProviders
to return anIdProviderAccount
where they would return aPragmaResult
containing theIdProviderAccount
, and to throw aPragmaException
when they would return aPragmaResult
containing an error.
Original Replacement PragmaResult<IdProviderAccount, PragmaError>
containing anIdProviderAccount
IdProviderAccount
PragmaResult<IdProviderAccount, PragmaError>
containing aPragmaError
Throw a PragmaException
- Modify any custom
- Description: The validate function in
Unreal: Update references to
UpdateLoadout
in Party service toUpdatePlayerSelections
.- Description: These renames will make the SDK interfaces better conform to the RPC endpoints.
- Integration step:
- Update references in the Unreal SDK’s Party service to the following:
Original Replacement UpdateLoadoutV1
UpdatePlayerSelectionsV1
CanUpdateLoadoutV1
CanUpdatePlayerSelectionsV1
Docs #
- [New Services Guide] New Content Data landing page is now live!
- Description: The brand new Content Data landing page contains everything you need to understand the Content Data system, from adding content to accessing and leveraging that content.
- [Updated Services Guide] Hidden Inventory summary and related quick guide have been added to the Items Services page.
- [Updated Services Guide] Steam authentication quick guide has been updated on the Authentication Services page.
- [Updated Services Guide] Ready state quick guide has been updated on the Party Services page.
- Related notes: See ready state feature note and integration note.
- [Updated Getting Started Guide] Added Postman reminder to Initial Setup page.
- Description: Remember to occasionally pull the latest Postman collection after new releases to ensure you’re getting updated calls.
- New Party plugin function added to manage player ready states.
June 7th, 2022
Deprecations #
Upgrade the listed Inventory RPC calls to their new versions to support hidden inventory.
- Description: To support the new hidden inventory feature, the following
InventoryRpc
calls have been updated to partition data into player and hidden sections.
Original Replacement Removal Patch InventoryRpc.UpdateItemsPartnerV1
InventoryRpc.UpdateItemsPartnerV2
0.0.73 InventoryRpc.UpdateItemsServiceV1
InventoryRpc.UpdateItemsServiceV2
0.0.73 InventoryRpc.ServiceGetInventoryV1
InventoryRpc.ServiceGetInventoryV2
0.0.73 InventoryRpc.GrantItemsServiceV1
InventoryRpc.GrantItemsServiceV2
0.0.73 - Description: To support the new hidden inventory feature, the following
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 theMatchProcessedV3Notifications
.
Original Replacement Removal Patch Unity: OnMatchProcessedV2Notification
Unity: OnMatchProcessedV3Notification
0.0.73 Unreal: OnMatchProcessedV2
Unreal: OnMatchProcessedV3
0.0.73 Integration steps:
- A feature toggle in
MatchLifecycleService
can be configured to switch toV3
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.
- A feature toggle in
- Description: In preparation for the removal of Progression service,
Integrations #
- Remove all uses of
PartyPlayer.progression
in thePartyPlugin
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
- Audit your use of these functions to ensure that you are not using
- Update
MatchLifecycle.MatchEndV4Request
to use newitemServerGrants
field.- Description:
MatchLifecycle.MatchEndV4Request
is being changed to use theitemServerGrants
field instead ofitemGrants
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 theitemServerGrants
field.
Original Replacement itemGrants: List<inventory.ItemGrantV2>
itemServerGrants: List<inventory.ItemServerGrantV1>
- Assign any item grants in
- Description:
Bugs and Fixes #
- Unreal SDK: Fixed issue with core SDK always invalidating the
Makefile
. This should decrease build times by a few seconds.
Docs #
- [Updated Services Guide] New sections have been added to the Party Services Guide for custom Party behavior, along with a related Quick Guide.
June 1st, 2022
Features #
Inventory items can now be hidden from players.
Description: Player stats such as matchmaking ratings can be tracked as
ext
fields on instanced items. These items can now be hidden to avoid leaking data to players.The table below contains a list of affected service calls and their new behavior.
Service call Description craftV1
,storePurchaseV4
,updateItemV4
, andupdateItemsV0
returned segments/deltas won’t contain items with tags that match the configuration getStoresV0
return stores will not contain store entries with tags that match the configuration getInventoryV2
returned inventory will not contain instanced and stackables whose corresponding content specs contain tags that match the configuration GameDataService.GetLoginDataV1
which usesInventoryService.GetLoginData
returned player inventory and content items (stores, update entries, item catalog, crafting entries, etc) are all filtered based on the tags in the configuration GetInventoryServiceV3
inventory data split by hidden
andplayer
visible itemsUpdateItemsPartnerV2
,UpdateItemsServiceV2
, andGrantItemsServiceV2
segments/deltas split by hidden
andplayer
visible itemsGame server
hostname
andport
information can now be provided as part of theMatchReadyV1Notification
.- Description: Previously, game servers communicated
hostname
andport
information to game clients viaext
behavior. We’ve promoted this functionality into base Pragma. Game servers can now providehostname
andport
information through theMatchLifecycleService.MatchReadyV2
endpoint. However, if you’ve already implemented this functionality viaext
, you can keep using that implementation indefinitely.
- Description: Previously, game servers communicated
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.
- Description: Added Operator endpoint for
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.
- Description: Added Partner endpoint for
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.
- Description: Added Partner endpoint for
[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)
.
- Description: Datetimes are now shown in 24h format in the browser’s timezone. On hover, the UTC datetime is shown. Example:
Deprecations #
- Remove any references to
LeaderClientVersion
field.- Description: The
LeaderClientVersion
field ofEnterMatchmakingV2Request
RPC andMatchmakingParty
Kotlin object is being removed as it is unnecessary.Original Replacement Removal Patch LeaderClientVersion
field ofEnterMatchmakingV2Request
RPC andMatchmakingParty
objectNo replacement needed 0.0.71
- Description: The
- Update
deletePlayerInventory
endpoints to new versions to remove Progression service data.
Original Replacement Removal 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.
Original Replacement Removal 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 ofPartyPlugin
in order to compile.
- Add a new
- Description: We’ve added a new plugin flow to the
Replace listed
InventoryRpc
protos.- Description: We’ve completed the move from the listed protos and are now removing the old ones.
- Integration step: Replace the listed
InventoryRpc
protos.Original Replacement InstancedDelta
InstancedDeltaV2
InventoryDeltaV1Data
InstancedDeltaV2
Move over from the Progression service to the Inventory service.
- Description: The Progression service is being removed.
- Integration step: If you are currently using the Progression service, please contact us for help moving over to the Inventory service.
Remove
gatewayWorkerThreadpoolSize
value in config YAML files.- Description: Ktor defaults create thread pools of the appropriate size, so this configuration is not needed.
- Integration step: Remove
gatewayWorkerThreadpoolSize
value in config YAML files.
Add required Maven dependency to
5-ext/ext/pom.xml
.Description: We’re moving Test Factory classes into the core engine to better separate the proto auto generated code steps from the rest of the engine build. In the future, generated code will be embedded directly into the engine library, rather than linked through a library dependency. This will streamline incremental builds and make the overall engine project structure simpler.
Integration step:
Add the following Maven dependency to5-ext/ext/pom.xml
if it is not already here. Ifpragma.mvn.version
is undefined, match whatever version you are using for other engine dependencies (eg.${revision}
, orPRAGMA-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 aportlets/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 toportalDevConfig.default.js
).Add the following contents to
portalDevConfig.local.js
:module.exports = { default: { 'portlets.extraSrcDirs': ['5-ext'] }, deploy: { target: ['5-ext/portal'] } }
- Description: Custom portlets can now be loaded from any custom directory under
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>
- Remove
In
5-ext/ext/pom.xml
:- Change
<parent><groupId>pragma</groupId></parent>
to<parent><groupId>[studio_name]</groupId></parent>
with your studio’s name in the brackets. - Change the following dependency block:
Original Replacement <dependency> <groupId>pragma</groupId> <artifactId>ext-protos</artifactId> <version>${revision}</version> </dependency> <dependency> <groupId>pragma</groupId> <artifactId>ext-protos</artifactId> <version>${revision}</version> <type>test-jar</type> <scope>test</scope> </dependency>
<dependency> <groupId>[studio_name]</groupId> <artifactId>ext-protos</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>[studio_name]</groupId> <artifactId>ext-protos</artifactId> <version>${project.version}</version> <type>test-jar</type> <scope>test</scope> </dependency>
- Change the following dependency block:
Original Replacement <dependency> <groupId>pragma</groupId> <artifactId>core</artifactId> <version>${revision}</version> </dependency>
<dependency> <groupId>pragma</groupId> <artifactId>core</artifactId> <version>${pragma.mvn.version}</version> </dependency>
- Change
For each of the dependencies listed, update
${revision}
to${pragma.mvn.version}
. Be sure to check for and update two dependency blocks, one default, and one with<type>test-jar</type>
:pragma.core
pragma.server-base
pragma.social
pragma.game
pragma.game-common
Pragma.social-common
In
5-ext/ext-protos/pom.xml
:- Make the following
parent
change:
Original Replacement <parent> <groupId>pragma</groupId> <artifactId>5-ext</artifactId> <version>${revision}</version> </parent>
<parent> <groupId>pragma</groupId> <artifactId>engine-settings</artifactId> <version>PRAGMA-LOCAL-SNAPSHOT</version> <relativePath>../../engine-settings.xml</relativePath> </parent>
- Add
<groupId>[studio_name]</groupId>
above the<artifactId>
tag. - Add
<version>[studio_name]-LOCAL-SNAPSHOT</version>
below the<artifactId>
tag. - For each of the dependencies listed, update
${revision}
to${pragma.mvn.version}
:pragma.proto-defs
pragma.proto-defs
(<type>test-jar</type>
)
- Make the following
In
5-ext/ext-server/pom.xml
:- For the
pragma.server-base
dependency, update${revision}
to${pragma.mvn.version}
. - Change
<parent><groupId>pragma</groupId></parent>
to<parent><groupId>[studio_name]</groupId></parent>
. - Make the following dependency change:
Original Replacement <dependency> <groupId>pragma</groupId> <artifactId>ext</artifactId> <version>${revision}</version> </dependency>
<dependency> <groupId>[studio_name]</groupId> <artifactId>ext</artifactId> <version>${project.version}</version> </dependency>
- For the
Bugs and Fixes #
- SDK
RefreshToken
flows now run at appropriate intervals.- Description: Authentication token intervals were previously dependent on clients’ clocks, leading to incorrect refresh intervals when clocks were incorrect. Token refresh intervals are now independent of player clocks.
- Searching for display names containing the
#
(number sign) character now works properly.
May 24th, 2022
Features #
- New Party service endpoint makes it possible for parties to be joined directly by party ID.
- Description: New Party Service endpoint available at
JoinWithPartyIdV1
. You can use this to write automated party invite flows in your UI.
- Description: New Party Service endpoint available at
- 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 thecontentdata 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.
- Description: We’ve added a way to validate cross-content IDs under
- Portal: Full Access List now available.
- Description: Operators can now create a full access list for players, such as friends and family. This can be managed in the Game Title Management section, at the bottom of the Shard page.
- Portal: Ability to delete player groups added.
- Description: Operators can now delete player groups. To delete a player group, select the group name on the Groups page, click the Edit Details button at the top right of the page, and click the red Delete group button.
Deprecations #
- Replace listed
InventoryRpc
protos by release 0.0.70.Original Replacement Removal Patch InstancedDelta
InstancedDeltaV2
0.0.70 InventoryDeltaV1Data
InstancedDeltaV2
0.0.70
Integrations #
- Update custom
MatchEndBuilders
toMatchEndV2
to support hidden inventory.- Description: To support hidden inventory, we’ve updated the Inventory service
MatchEnd
endpoint andInventoryMatchEndBuilder
. You will need to update customMatchEndBuilders
to look for the newMatchEndV2Response
. - The contents of the
MatchEnd
response have also changed. If you currently inspect theUpdateSummaries
that come back fromInventoryService
in customMatchEndBuilder
, the new response contains aServiceUpdateSummary
, which is composed of twoUpdateSummary
objects. - Until you start using hidden inventory, the player
UpdateSummary
field is equivalent to what was there before. - Integration steps:
- If you have custom
MatchEndBuilders
inspecting context, you will need to update what they look for:Original Replacement InventoryRpc.MatchEndV1Response::class
InventoryRpc.MatchEndV2Response::class
- If you have custom
- Description: To support hidden inventory, we’ve updated the Inventory service
- 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 twoInventoryData
s with content split using the new hidden inventory system. - Integration steps:
- Update references using
inventory
and underlying fields on aPartyPlayer
. Until hidden inventory is configured, use the playerInventoryData
object as the equivalent of the oldinventory
field.Original Replacement InventoryFullV1Data
ServiceInventoryData
- Update references using
- Description: The Party plugin’s
Docs #
- [New Category] Starter Kit documentation has been added.
- [Updated Services Guide]
JoinWithPartyIdV1
added to Party Services Guide.
- New Party service endpoint makes it possible for parties to be joined directly by party ID.
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 beAlice#0001
and the second would beAlice#0002
. The discriminator is now randomly assigned.
- Description: Accounts would previously receive sequentially-assigned discriminators. For example, the first account named
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 topartyExt.proto
if found.
- Delete
- In the
- Description: Some
// 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 ofInventoryService.MatchEndV0
.- Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to
MatchLifecycleService.matchEndV3
. - Integration step:
- Make the following changes:
InventoryRpc protos:
Original Replacement MatchEndV0Request
MatchEndV1Request
MatchEndV0Response
MatchEndV1Response
Inventory RPC service route: Original Replacement ———– —————— matchEndV0
matchEndV1
- Make the following changes:
InventoryRpc protos:
- Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to
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.
- New Party service is now live!
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 byCatalogId
via itsreceivedQuantityByCatalogId
orcostByCatalogId
fields. TheseCatalogIds
are now checked duringContentData
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 theContentHandler
.Note that this initial rollout of cross-content validation does not validate anything nested under an
ext
message.- Description: Inventory Service Content now has additional validation across content types, which is performed during the
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 atplatform/web/portal-base
.
View the
README_PORTAL.md
file inplatform/web
for more information about the new Portal.- Related note: Integration may be required. View the related integration note below.
- Description: The Portal has been upgraded to be faster and more modular. It can be found at
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 atplatform/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.
- Description: The new Portal is now available at
- Update the
ContentDataProxy
class primary constructor if necessary.- Description: The
kClass
param has been removed from theContentDataProxy
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.
- If you are using this class with custom content, you will need to remove the
- Description: The
Original Replacement 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
andInMemGameIT.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 copyInMemSocialIT.yml
andInMemGameIT.yml
over. If you are using a customMakefile
, please update it. - Merge the contents of your existing
InMemSocialIT.yml
andInMemGameIT.yml
files into the new files.
- The
Original Replacement ext/src/test/resources/localDevelopmentShardConfig/InMemSocialIT.yml
ext/src/test/resources/localDevelopmentShardConfig/SocialIT.yml
ext/src/test/resources/localDevelopmentShardConfig/InMemGameIT.yml
ext/src/test/resources/localDevelopmentShardConfig/GameIT.yml
- Use
PragmaJwtSigner
instead ofTokenUtils::createPragmaJWT
.- Description:
TokenUtils::createPragmaJWT
has been replaced byPragmaJwtSigner
. - Integration steps:
- Use
PragmaJwtSigner
instead ofTokenUtils::createPragmaJWT
.
- Use
- Description:
Original Replacement TokenUtils::createPragmaJWT
PragmaJwtSigner
- Update the
Makefile
to reflect changes to the relevantgen-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 relevantgen-sdk-types-<ENGINE>
also depends on theprotos
step.
- If you have your own copy of the
Original Replacement gen-sdk-types-unreal4: ext-protos
gen-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 thePragmaNode
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.
- Description:
- Portal display name searches now handle the underscore
_
and percent%
characters properly. - Fixed
BackgroundableTicker
warnings and strict Include-What-You-Use (IWYU) compilation in Unreal 5.
Docs #
- [Updated Getting Started Guide] Details added to Understanding Pragma Engine.
- [Updated Getting Started Guide] Initial Setup guide rewritten.
May 3rd, 2022
Features #
- The Unity SDK now logs debug details from service errors.
- Description: Developers can now view service errors in the Unity Editor console.
- Match reconnect now available.
- Description: Match reconnect is now available using the Party system and can be used by players to rejoin in-progress matches.
Deprecations #
/v1/info
endpoint connection fields are being renamed.- Description: The
scheme
andwsScheme
fields in the<protocol>://<host>:<port>/v1/info
endpoint are being deprecated, and will be replaced withprotocol
andwebSocketProtocol
.Original Replacement Removal Patch scheme
protocol
0.0.68 wsScheme
webSocketProtocol
0.0.68
- Description: The
Inventory
MatchEndV0
RPC and protos are being renamed toMatchEndV1
.- Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to
MatchLifecycleService.matchEndV3
. InventoryRpc
protos:Original Replacement Removal Patch MatchEndV0Request
MatchEndV1Request
0.0.68 MatchEndV0Response
MatchEndV1Response
0.0.68 - Inventory RPC service route:
Original Replacement Removal Patch matchEndV0
matchEndV1
0.0.68
- Description: Changes are only required to custom services making calls to this endpoint. No changes are required to services making calls to
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 thehost
,port
, andprotocol
fields instead. Note thatprotocol
defaults tohttp
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.
- Description: The
Original Replacement partnerConnectionInfo: url: "http://localhost" host: "localhost" port: 10106
partnerConnectionInfo: protocol: "http" host: "localhost" port: 10106
- Update
InstancedItemPlugin
code that usesUpdateResult
.- Description:
instancedItemGrants
has been renamed toinstancedItemServerGrants
. - Integration steps: Update all plugins that return a
InstancedItemPlugin.UpdateResult
by renaminginstancedItemGrants
toinstancedItemServerGrants
.
- Description:
Original Replacement return InstancedItemPlugin.UpdateResult( extInstancedItem instancedItemGrants stackableItemGrants )
return InstancedItemPlugin.UpdateResult( extInstancedItem instancedItemServerGrants stackableItemGrants )
- Change
ContentDataNodeService.getHandler
method.- Description: The
ContentDataNodeService.getHandler
method withkclass
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 thekclass
parameter.
- Description: The
Original Replacement fun <ContentProto : GeneratedMessageV3> getHandler( kClass: KClass<ContentProto>, resourcePath: String ): ContentData<ContentProto>
fun <ContentProto : GeneratedMessageV3> getHandler( resourcePath: String ): ContentData<ContentProto>
Update the following functions as mentioned in release 0.0.64.
- Description: Session and WebSocket cleanup changes.
Integration step:
Make the following changes:Original Replacement JumpData::longClassNameToShortName()
ProtoUtils.protoShortName()
TokenUtils.createPragmaJWT
use PragmaJwtSigner
methods
Update server configuration for listed gateway config fields.
- Description: Update server configuration for the following gateway config fields.
- Integration step:
SocialOperatorGatewayConfig
,SocialPlayerGatewayConfig
,SocialPartnerGatewayConfig
,GameOperatorGatewayConfig
,GamePlayerGatewayConfig
,GamePartnerGatewayConfig
Original Replacement schema
protocol
wsSchema
webSocketProtocol
Bugs and Fixes #
- Pragma Portal now properly excludes players who are already a member of a group from being shown in the Add Accounts to Player Group page for that group.
Docs #
- [New Services Guide] Match reconnect added.
- [Updated Services Guide] Details added to Play Again section.
- The Unity SDK now logs debug details from service errors.
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
- 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
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
withDeletePlayerInventoryV1
.- Description: We’ve deprecated
ClearPlayerInventoryCacheV1
. - Integration step: Use
DeletePlayerInventoryV1
instead ofClearPlayerInventoryCacheV1
.Original Replacement ClearPlayerInventoryCacheV1
DeletePlayerInventoryV1
- Description: We’ve deprecated
- Move
MatchLifecycleService
configurations fromserviceConfigs
topluginConfigs
.- Description: MatchLifecycleService strategy configuration has been moved, as mentioned in release 0.0.61.
- Integration step: Move MatchLifecycleService configs.
Original Replacement serviceConfigs: MatchLifecycleServiceConfig: matchFoundBuilderStrategy: "CustomMatchFoundBuilderClass" notifyMatchAllocatedStrategy: "CustomNotifyMatchAllocatedClass"
pluginConfigs: MatchLifecycleService.matchFoundBuilderPlugin: class: "CustomMatchFoundBuilderClass" MatchLifecycleService.notifyMatchAllocatedPlugin: class: "CustomNotifyMatchAllocatedClass"
- Update
MatchLifecycleService
strategy class signatures on customext
implementations.- Description: The
matchFoundBuilderStrategy
andnotifyMatchAllocatedStrategy
fields are being deprecated in favor of plugins. - Integration steps:
- Update
ext
implementations to useMatchFoundBuilderPlugin
andNotifyMatchAllocatedPlugin
interfaces instead. - Update primary constructor to required plugin signature.
Original Replacement 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.
- Update
- Description: The
- Added a new way to track account creation and most recent login.
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
onMatchCapacityService
handles reporting into Pragma Engine until a match is available. Once a match is found, it returns the associated match data.
- Description: The new method
- Unreal SDK: You can now initialize Pragma without access to a World.
- Description:
PragmaSession
no longer requires access to a World.
- Description:
- 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 ofServerItemUpdateV2
. This list is aoneof
including either aServerInstancedItemUpdate
or aStackableItemUpdate
. This will return anInventorySegmentV1Data
, which contains the updated item and a delta of changes. The Service call isUpdateItemsServiceV1
. - Postman paths:
Game → RPC - Operator → Inventory → UpdateItemsOperatorV1
Game → RPC - Partner → Inventory → UpdateItemsPartnerV1
- Description: Items can be updated given a
Deprecations #
UnpartitionedDaoNodeService
andPartitionedDaoNodeService
will now useexecuteSingle
(single interaction) andtransact
(multiple statements).Original Replacement Removal Patch execute
executeSingle
0.0.66 executeTransaction
transact
0.0.66 Session and WebSocket cleanup changes.
Original Replacement Removal Patch JumpData::longClassNameToShortName()
ProtoUtils.protoShortName()
0.0.66 TokenUtils.createPragmaJWT
use PragmaJwtSigner methods
0.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.
Original Replacement gameConnection.pragmaId
playerId
socialConnection.pragmaId
socialId
fun isConnectedToGame(): Boolean
gameConnection.isConnected()
fun isConnectedToSocial(): Boolean
socialConnection.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 aPragmaError
.
- Description: The return type of the
Original Replacement 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 ofViewSocialIdentityPartnerV2Request
. - Integration steps:
- Replace all instances of
ViewSocialIdentityPartnerV1Request
withViewSocialIdentityPartnerV2Request
.
- Replace all instances of
- Description:
Original Replacement ViewSocialIdentityPartnerV1Request
ViewSocialIdentityPartnerV2Request
Bugs and Fixes #
- Unreal SDK: Fixed a bug where the Connection state would not return to
Connected
after beingDegraded
.
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.
- Unity SDK: New method allows a game server to directly report match capacity data to Pragma Engine.
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, andConnection::OnRecovered
when they are fully connected again.
- Description: The Unreal SDK now fires
- You can now delete
instancedItems
via Operator, Partner, or Service gateways.- Description: Items will be destroyed when this endpoint is given a
playerID
and anItemServerDestroyV1
list. This list is a oneofInstancedItemServerDestroy
, which is an instance ID. Please note the Operator endpoint will be added to Postman with the next release. InventoryRpc
endpoints::DestroyItemsPartnerV1
DestroyItemsOperatorV1
DestroyItemsServiceV1
- Description: Items will be destroyed when this endpoint is given a
- 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
.
- 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
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.
- Description: The SDK Lobby Service now resets the lobby state
- Pragma Portal: Issue with searching by account provider ID has been resolved.
- The Unreal SDK can now recognize when a connection is degraded/recovered and surface that information to users.
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.
- Description: When authoring plugin content and choosing to throw a custom error using
- 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 runningmake ext
ormake build
from the command line.
- Create the new
- 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
.
- 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
Deprecations #
ViewSocialIdentityPartnerV1Request
is being deprecated in favor ofViewSocialIdentityPartnerV2Request
.Original Replacement Removal Patch ViewSocialIdentityPartnerV1Request
ViewSocialIdentityPartnerV2Request
0.0.64
Integrations #
- Rewrite your configuration files (e.g.
LocalConfig.yml
orCommonConfig.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.
Original Replacement pluginConfigs: GameDataService.gameDataStrategyPlugin: class: "DefaultPragmaGameDataStrategyPlugin"
pluginConfigs: GameDataService.gameDataStrategyPlugin: class: "pragma.gamedata.DefaultPragmaGameDataStrategyPlugin"
Bugs and Fixes #
- Player Groups are now associated with
socialId
instead ofaccountId
.- Description:
accountID
s 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’ssocialId
. This is a purely behind-the-scenes change and should not cause any visible effects.
- Description:
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
- Description: We’ve added a new RPC endpoint for deleting a player group. The payload requires a
- 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
topluginConfigs
by patch 0.0.63.
Original Replacement Removal 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 customext
implementations.- Description: The
matchFoundBuilderStrategy
andnotifyMatchAllocatedStrategy
fields are being deprecated in favor of plugins. - Integration steps:
- Update
ext
implementations to useMatchFoundBuilderPlugin
andNotifyMatchAllocatedPlugin
interfaces instead. - Update primary constructor to required plugin signature.
- Update
- Description: The
Original Replacement 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.
- New endpoint for deleting a player group.
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.
- Description: Player’s social IDs are now sent to game servers. Additionally, social IDs are now included with all
- 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
- Search for the
- Ensure Jaeger is running in Docker. See the instructions in the readme here:
- 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.
- Description: Developers can take advantage of a new SDK event when client tokens successfully refresh. Add a handler for
- 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.
Integrations #
- Confirm you’ve replaced
AddAccountsToPlayerGroupOperatorV1
withBulkActionOperatorV1
.- Description: We replaced
AddAccountsToPlayerGroupOperatorV1
withBulkActionOperatorV1
several patches ago. The code has now been fully removed.Original Replacement AddAccountsToPlayerGroupOperatorV1
BulkActionOperatorV1
- Description: We replaced
Bugs and Fixes #
- Fixed compilation errors and warnings in preview builds of Unreal Engine 5.
- Social IDs are now sent to game servers.
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
withRandomProxy
. - Use the new
getHandler
, as the old one has been deprecated along with the old content system. - Add
ExtUpdatePartyRequest
message topartyRpcExt.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 in5-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.
- Move your content into
- 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
- Replace
LongRangeProxy
withRandomProxy
.- Description:
LongRangeProxy
has been deleted. - Integration step:
- Replace the following:
Original Replacement LongRangeProxy
RandomProxy
- Replace the following:
- 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.
- See
- Description:
- 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.Original Replacement ContentDataNodeService.getHandler(kClass: KClass<ContentProto>, resourcePath: String)
ContentDataNodeService.getHandler(resourcePath: String)
- Use
- Description:
- Add
ExtUpdatePartyRequest
message topartyRpcExt.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 { }
- Paste the following into
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
- Description: The
- Required Integrations:
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 toV2
.- Rewrite your configuration files (e.g.
LocalConfig.yml
orCommonConfig.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.
- Reimplement plugins that implement
- 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
).
- Description: There is a new config option within Matchmaking,
game: serviceConfigs: MatchmakingConfig: enableGetMatchmakingInfo: true
InstancedItemPlugin.Update
can now return instanced and stackable item grants.- Description:
UpdateResult
returned fromInstancedItemPlugin.Update
now includes a list ofinstancedItemGrants
andstackableItemGrants
. To use this feature, simply populate theUpdateResult
with a list ofInstancedItemServerGrant
and/orStackableItemGrant
. - 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.
Original Replacement Removal Patch MatchmakingRpc.LeaveMatchmakingV1
MatchmakingRpc.LeaveMatchmakingV2
0.0.60 Rewrite your configuration files (e.g.
LocalConfig.yml
orCommonConfig.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
assuspend
methods.- Description: Updated
BulkActionPlugin
interface to usesuspend
methods forneedsFullPragmaAccount
andapply
. - 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.
- If you have plugins that implement the
- References
2-pragma/social-common/src/main/kotlin/pragma/account/BulkActionPlugin.kt
4-demo/demo/src/main/kotlin/demo/account/DemoBulkActionPlugin.kt
- Description: Updated
- 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 the5-ext/ext-protos/src/main/proto/shared/
directory. - Paste the following into
partyRpcExt.proto
:
- Create
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.
- Description: Upgrading to the newest version of Pragma will drop any existing emails that were gathered using the
- 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.
- Reimplement plugins that implement
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.
- Removed
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
inStores.json
. - Fixed a crash in the SDK when trying to handle valid
CraftV1
responses that containedErrors
associated with the craft attempt.
- Additional validation for
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 thepragma-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.
- Move your existing
- Description:
- The Portal configuration location has changed.
- Description: Portal config has been moved out of
game-config.json
andsocial-config.json
and is now in YAML (e.g.LocalConfig.yml
orCommonConfig.yml
) as part of theFilePortalModulePlugin
settings. - Integration steps:
- Most users will not want to directly translate the
game-config.json
andsocial-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
- Most users will not want to directly translate the
- Description: Portal config has been moved out of
longRangeProxy
has been deprecated.- Description: Please use
randomProxy
instead oflongRangeProxy
. - 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
andRewardSelectorPlugin.init
.
- See
- Description: Please use
- Removed
InstancedItemPlugin.init
method.- Description: Removed
InstancedItemPlugin.init
aslongRangeProxy
has been removed.
- Description: Removed
- Updated
RewardSelectorPlugin.init
parameters.- Description:
longRangeProxy
has been deprecated. - Integration step: use
randomProxy
in place oflongRangeProxy
.
- Description:
Original Replacement 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 ofrunBlockingTestWithTimeout
for unit tests. - Use
runIntegrationTest
in place ofrunBlockingTestWithTimeout
for integration tests.
- Use
- Description: We have updated the
Original Replacement runBlockingTestWithTimeout
runTest
for unit testsrunIntegrationTest
for integration testsAs 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.
Original Replacement TestAccountManager.operatorClient
TestAccountManager.getOperatorClient()
TestAccountManager.partnerClient
TestAccountManager.getPartnerClient()
PragmaClientFactory.playerEndpointInfo
PragmaClientFactory.getPlayerEndpointInfo()
PragmaClientFactory.operatorEndpointInfo
PragmaClientFactory.getOperatorEndpointInfo()
PragmaClientFactory.partnerEndpointInfo
PragmaClientFactory.getPartnerEndpointInfo()
- Description: Many
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 in5-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
.
Original Replacement ExtPartyDetails
ExtPublicPartyData
ExtPartyPlayer
ExtPublicPlayerData
- Description: As part of the ongoing development of the party service, a couple
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
inStores.json
.- Description: The content system will now ensure that
StoreEntries
havereceivedQuantityByCatalogId
field populated. This check is performed during content apply and service startup, and the engine will not start if this field is missing.
- Description: The content system will now ensure that
- Fixed a crash in the SDK when trying to handle valid
CraftV1
responses that containedErrors
associated with the craft attempt.
February 22nd, 2022
- Added ability to directly add or remove players in a Player Group.
- Required integration:
- Update implementations of
LobbyStrategy.setExtPlayerInfo
with the newLobbyModel
parameter. - Update implementations of
StorePlugin.meetsRequirements
with the newstoreId
parameter. - Replace references to the helper method
assertProtoEquals()
with JUnit’sassertEquals()
.
- Update implementations of
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
- Description: We’ve added functionality that allows directly adding or removing players in a Player Group. Responses include
Integrations: #
- Update implementations of
LobbyStrategy.setExtPlayerInfo
with the newLobbyModel
parameter.- Description: We’ve added a new parameter to the
setExtPlayerInfo
function in theLobbyStrategy
plugin interface, so you can access data from the Lobby when setting playerext
info. - Integration step: Make the following changes in implementations of
LobbyStrategy.setExtPlayerInfo
.
- Description: We’ve added a new parameter to the
Original Replacement setExtPlayerInfo( lobbyPlayer: LobbyPlayer, extPlayerInfo: ExtPlayerInfo )
setExtPlayerInfo( lobbyPlayer: LobbyPlayer, extPlayerInfo: ExtPlayerInfo, lobbyModel: LobbyModel )
- Update implementations of
StorePlugin.meetsRequirements
with the newstoreId
parameter.- Description: We’ve added a new parameter to the
meetsRequirements
function in theStorePlugin
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
.
- Description: We’ve added a new parameter to the
Original Replacement 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’sassertEquals()
method instead. - Integration step:
Original Replacement assertProtoEquals()
JUnit’s assertEquals()
- Description: We’ve removed the
February 15th, 2022
- Added capability to grant rewards with the
InstancedItemPlugin.update
function. - Required integration:
- Update
InstancedItemPlugin.update()
with new parameter and return type.
- Update
- Optional integration:
- Rename histogram config to continue using histogram metrics.
- Bug fix:
- Removed
distributedServiceCounts
configuration.
- Removed
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 ofExtInstancedItem
- New parameter
Reference:
- Structure of
UpdateResult
:
data class UpdateResult( val extInstancedItem: ExtInstancedItem, val rewardGrants: List<RewardGrant> )
- Structure of
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, addinventoryContent: InventoryServiceContent
parameter afterupdateEntry
. - In the
update()
method, change return type fromExtInstancedItem
toUpdateResult
.
Original Replacement InventoryContent.UpdateEntry
inventoryContent: InventoryServiceContent
ExtInstancedItem
UpdateResult
- In the
Reference:
- Check out the pet update example in
DemoInstancedItemPlugin
for a sample implementation.
- Check out the pet update example in
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.
Original Replacement enableHistogram
enableHistogramMetrics
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.
- Added capability to grant rewards with the
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
- Description: We’ve added a
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 aRewardGrant
in addition toinstancedItems
andstackableItems
. ARewardGrant
maps to aRewardTable
that can result in a set of guaranteed rewards items and/or random rewards by usingRewardSlots
. - 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() )
- Description: We’ve added a
Game Shard Access Mode is now live.
- Description:
shardAccessMode
is now enforced onauthenticateOrCreate
. Authentication will respect the setshardAccessMode
and deny access to users not in approved player groups on active limited access events. Default access is set toeveryone
. - Postman path:
Social → RPC - Operator → Game Management → SetShardAccessModeV1
- Description:
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 withinventoryContent
:
Original Replacement catalog: InventoryCatalog
inventoryContent: InventoryServiceContent
- In the
Reference:
inventoryContent.instancedSpecs[<CATALOG_ID>]
returns theInstancedSpec
proto.- View
4-demo
’sCookingCrafter.completeCooking()
orQuests.complete()
for an example of theInventoryContentService
and how to properly add arewardGrant
to theCraftResult
. - 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 byBulkActionOperatorV1
.- See the Postman collection for an example of the payload.
Original Replacement AddAccountsToPlayerGroupOperatorV1
BulkActionOperatorV1
StackableSpecs
andInstancedSpecs
are now accessed as maps instead of lists in code.- There are no changes to the formatting of
StackableSpecs
andInstancedSpecs
in content or protos.InstancedSpecs.json
andStackableSpecs.json
still consist of arrays of objects.
- There are no changes to the formatting of
Original Replacement List<StackableSpec>
Map<String, StackableSpec>
List<InstancedSpec>
Map<String, InstancedSpec>
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
.
- Removed unsupported WebSocket scheme in HTTP responses for
Features #
Users can now use map accessors instead of iterating over an array all the time.
- Description:
ItemCatalog
now hasInstancedEntriesMap
andStackableEntriesMap
.
- Description:
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 valuesocialBindPort
.GamePlayerGatewayConfig
has new valuessocialBindPort
andgameBindPort
.
- 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
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
andrefreshProgression
functions return an updated copy of data and recache the new result with that player.- These functions take in an
InventoryClient
andProgressionClient
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
torewardContent.proto
.- Any imports will need to be updated.
- Renamed
RewardsCount
message toRewardCount
.- Any references and imports will need to be updated.
- Renamed
RewardsTable
message toRewardTable
.- Requires updating any code referencing
RewardsTable
proto messages, as well as the followingInventoryTestFactory
methods:Original Replacement rewardsTables()
rewardTables()
rewardsTable()
rewardTable()
- Requires updating any code referencing
- Moved
RewardsCatalog
fromRewardContent.proto
toInventoryRpc.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
:Original Replacement stackableItemSpecs
stackableSpecs
instancedItemSpecs
instancedSpecs
catalogUpdateEntries
updateEntries
rewardsTables
rewardTables
- Renamed the following content files in the
5-ext/content/shared/
:Original Replacement CatalogCraftingEntries.json
CraftingEntries.json
CatalogUpdateEntries.json
UpdateEntries.json
InstancedItemSpecs.json
InstancedSpecs.json
StackableItemSpecs.json
StackableSpecs.json
- Renamed
New matchmaking function must be added to successfully compile.
- Description: Add new function
addToMatchAndBuildMatchmakingDetails
to implementations ofMatchmakingStrategy
plugin. This will be used in our upcoming game loop systems. - Integration step:
- Paste the following no-op stub into any
MatchmakingStrategy
implementations:
- Paste the following no-op stub into any
- Description: Add new function
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
andsetExtLobbyInfo
. - Integration steps:
You will need to make the following changes:
Original Replacement fun setExtPlayerInfo
suspend fun setExtPlayerInfo
fun setExtLobbyInfo
suspend fun setExtLobbyInfo
If the code is called in
mockk every
orverify
blocks, you will also need to update:Original Replacement every { lobbyStrategy.setExtLobbyInfo... }
coEvery { lobbyStrategy.setExtLobbyInfo... }
verify { lobbyStrategy.setExtLobbyInfo... }
coVerify { lobbyStrategy.setExtLobbyInfo... }
- Description: Added suspend to function definitions
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:Original Replacement (pragma.inventory.)TestFactory
InventoryTestFactory
(pragma.matchmaking.)TestFactory
MatchmakingTestFactory
(pragma.)InventoryTestFactory
InventoryProtoTestFactory
(pragma.)MatchmakingTestFactory
MatchmakingProtoTestFactory
- If you have any tests using any
- Description: You will need to update references to any of the
Changed method names in
BaseServerIT
class- Description:
getConfigAsJsonNode()
has been renamed togetGame ConfigAsJsonNode()
andgetSocialConfigAsJsonNode()
has been added. - Integration step:
- You will need to change all calls to
getConfigAsJsonNode()
togetGameConfigAsJsonNode()
.
- You will need to change all calls to
- Description:
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 nonfunctioningwsScheme
in theauthenticateBackend
section.
- Description: HTTP requests to the
Deprecations #
Original Replacement ItemCatalog.InstancedEntries/StackableEntries
ItemCatalog.StackableEntriesMap/InstancedEntriesMap
ContentData.get(Long)
ContentData.get(String)
ContentDataNodeService::getOrLoadContent()
use ContentDataNodeService::getHandler()
OR theContentDataProxy
classJanuary 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.
- For any classes using the
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)
.
- Description: Define a new method for
- 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:
- Rename
web/packages/5-ext-webapp
toweb/packages/5-ext-webapp_initial
. - Create a new
5-ext-webapp
:$ cd platform && make portal-ext-create
- Bring your custom code over by replacing the entire
/web/packages/5-ext-webapp/src
folder withweb/packages/5-ext-webapp_initial/app/src
. - Update the config files by replacing the
/web/packages/5-ext-webapp/public/config
folder withweb/packages/5-ext-webapp_initial/app/public/config
. - (optional) If needed, add your extra dependencies to
/web/packages/5-ext-webapp/package.json
, then run:run npm install
- Rename
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 underplatform/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
- Optional integrations:
January 18th, 2022
- Required integration:
- You must define message
ExtEnterMatchmakingV2Request
inmatchmakingExt.proto
to successfully compile.
- You must define message
Integrations #
- You must define message
ExtEnterMatchmakingV2Request
inmatchmakingExt.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
- Description: The new proto message
- Required integration:
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.
- Order changed in
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
- Social → RPC Operator → Account →
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.
- Description: A new parameter,
Stores can now accept instanced and stackable items as required ingredients for crafting.
- Description:
requiredCatalogIds
inStores.json
now acceptsinstancedItem
catalogId
s as well asstackableItem
catalogId
s.
- Description:
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
- Description: Add the following lines to
Bugs and Fixes #
Order changed in
Service.shutdown()
.- Description:
shutdownService()
is now called before we cancel all jobs.
- Description:
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 astoreEntry
.
Deprecations #
- none
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
usesgroup
instead ofplayer_group
as the property. - Postman Path:
- Social → RPC Operator → Account →
CreatePlayerGroupOperatorV1
- Social → RPC Operator → Account →
- Improved variable visibility for
PragmaException
messages.- Description: Added
'
around variables to improvePragmaException
messages.
- Description: Added
- Description:
Integration Steps #
- Unit tests must be updated from
runBlockingTest
torunTest
.- Description: Kotlin and Kotlin coroutine versions have been updated, causing deprecation warnings for tests using
runBlockingTest
. - Integration steps:
- Change any instances of
runBlockingTest
torunTest
.
- Change any instances of
- Description: Kotlin and Kotlin coroutine versions have been updated, causing deprecation warnings for tests using
- 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.Original Replacement getStackableItemSpecs()
stackableItemSpecs
getInstancedItemSpecs()
instancedItemSpecs
getCatalogUpdateEntries()
catalogUpdateEntries
getStores()
stores
getRewards()
rewards
getRewardsTables()
rewardsTables
getRewardSlots()
rewardSlots
getRewardBags()
rewardBags
getCraftingEntries()
craftingEntries
- Calls to content getters in
Deprecations #
The following endpoints have been changed:
Original Replacement authenticateOrCreateV1
authenticateOrCreateV2
AccountService.getPragmaPlayerIdsForProviderIdsV1
AccountService.getPragmaPlayerIdsForProviderIdsV2
InventoryServiceContent
getter methods have been updatedSee integration notes above 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.
- Please note that these features are early access and require Postman. They require running against
- Required integration:
- New
GameDataStrategy
interface: Follow the steps in the detailed section below to adjust your implementation to migrate fromsetLoginDataProtoFields
to the newgetExtLoginData
wrapper.
- New
- Optional integration:
- Updated confirmation email expiration duration to be 7 days, with an optional configuration step: Add an
emailTokenExpirationMinutes
config intoCommonConfig.yml
with the desired duration
- Updated confirmation email expiration duration to be 7 days, with an optional configuration step: Add an
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
- Social → RPC Operator → Account →
- 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
- Social → RPC Operator → Account →
- 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 runningpragma-engine
against4-demo
, you must implement the appropriateext
s. Refer to4-demo
and its implementation ofPragma.Account.AccountPlugin
for an example of adding tags and providing them to an account withregisterEmailV1
.
- Paths:
- Social → RPC Partner →
registerEmailV1
platform/4-demo/demo-protos/src/main/proto/shared/accountRpcExt.proto
containsExtCreateAccountRequest
- Social → RPC Partner →
- 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
- Social → RPC Operator → Account →
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:
- Delete any implementations of
fun init(contentDataNodeService: ContentDataNodeService)
. No replacement is required as the plugin constructor provides access to theContentDataNodeService
. - Update
setLoginDataProtoFields
togetExtLoginData
. CreateExtLoginData
, fill it out with the existing logic being passed into the builder, and return it. - Locate plugin configurations for
GameDataService.gameDataStrategy
and update them toGameDataService.gameDataStrategyPlugin
.
- Delete any implementations of
- Description: To increase cohesion between plugins, we’ve updated the
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 intoCommonConfig.yml
with the desired duration. - Reference:
social: serviceConfigs: TokenSignerConfig: emailTokenExpirationMinutes: 10
- 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
Deprecations #
- None
- Added new player group capabilities, such as creating new player groups, viewing information about them, and bulk adding players by tag.
November 30th, 2021
- Added ability to attach multiple provider accounts to
pragmaSocialId
s - 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.
- Description:
Integration Steps #
- None
Deprecations #
- None
- Added ability to attach multiple provider accounts to
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.
- New format of
- 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 your5-ext/ext-server/pom.xml
.
- Configure the ext jar to be copied and renamed on build: Copy the plugin block that was added to
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
- Description: Added
- Added a way to include additional metadata with crafting requests.
- Description: Added
ExtCraftRequest
to themeetsRequirements()
function in theCraftingPlugin
. - Reference: For an implementation example, check out the
PetEvolutionRequest
used in 4-demo’sPetCrafter.kt
. - Path:
pragma-engine/platform/4-demo/demo/src/main/kotlin/pragma/inventory/PetCrafter.kt
- Description: Added
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.
- Description: The format of the
- 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:
Original Replacement PlayerMatchEndV2.item_updates
PlayerMatchEndV2.server_item_updates
getDisplayNameForPragmaPlayerIdForPartnerV1
use match data for player display names 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
to4-demo
, and all example submodules todemo
instead - Updated Makefile and various build scripts to use
4-demo
instead of4-example-ext
- Renamed Unity and Unreal PragmaSDK
ExampleProjects
to bePragmaDemo
- Delete all references to
CatalogTestFactory
in test code. Reimport fromInventoryTestFactory
.CatalogTestFactory
has been collapsed intoInventoryTestFactory
. - Update all references from function
InventoryTestFactory.stackableCatalogEntries
toInventoryTestFactory.stackableSpecs
- Update all references from function
InventoryTestFactory.instancedCatalogEntries
toInventoryTestFactory.instancedSpecs
- Update all references from function
InventoryTestFactory.repeatedStackableDelta
toInventoryTestFactory.stackableDeltas
- Update all references from function
InventoryTestFactory.repeatedInstancedDeltaV2
toInventoryTestFactory.instancedDeltaV2s
- New Pragma CLI option crypto
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 toinventoryRpcExt.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
frominventoryExt.proto
toinventoryRpcExt.proto
- Add new message definition to
inventoryRpcExt.proto
in5-ext
:message ExtInstancedItemServerUpdate { }
- Relocate all protos from both
catalogExt.proto
andstoreContentExt.proto
toinventoryContentExt.proto
. - Delete
catalogExt.proto
- Delete
storeContentExt.proto
- Replace all references from
CatalogContent.GameCatalog
toInventoryContent.ItemCatalog
- Replace all references from both
pragma.catalog.CatalogContent
andpragma.store.StoreContent
topragma.inventory.InventoryContent
- Replace all references from
pragma.InventoryTestFactory.gameCatalog
topragma.InventoryTestFactory.itemCatalog
- Replace all import namespaces references from both
pragma.catalog
andpragma.store
topragma.inventory
- Update all references from
GameCatalog
toItemCatalog
when handlingLoginData
,GetLoginDataV1Response
, orGetCatalogOperatorV1Response
protos - Rebuild all protos and SDK types
- Relocate
Within your Unreal game:
- Replace all references from
Dto/PragmaCatalogContentDto.h
toDto/PragmaInventoryContentDto.h
- Replace all references from
FPragma_Catalog_GameCatalog
toFPragma_Inventory_ItemCatalog
- Replace all references from
FPragma_Catalog_StackableSpec
toFPragma_Inventory_StackableSpec
- Replace all references from
FPragma_Catalog_InstancedSpec
toFPragma_Inventory_InstancedSpec
- Replace all references from
FPragma_Store_Store
toFPragma_Inventory_Store
- Replace all references from
FPragma_Store_StoreEntry
toFPragma_Inventory_StoreEntry
- Replace all references from
FPragma_Store_PurchaseRequirements
toFPragma_Inventory_PurchaseRequirements
- Replace all references from
FPragma_Store_CraftingEntry
toFPragma_Inventory_CraftingEntry
- Replace all references from
FPragma_Store_CostEntry
toFPragma_Inventory_CostEntry
- Replace all references from
FPragma_Store_UpdateEntry
toFPragma_Inventory_UpdateEntry
- Replace all references from
FPragma_Catalog_ExtStackableSpec
toFPragma_Inventory_ExtStackableSpec
- Replace all references from
FPragma_Catalog_ExtInstancedSpec
toFPragma_Inventory_ExtInstancedSpec
- Replace all references from
FPragma_Store_ExtPurchaseRequirements
toFPragma_Inventory_ExtPurchaseRequirements
- Replace all references from
FPragma_Store_ExtUpdateEntry
toFPragma_Inventory_ExtUpdateEntry
- Replace all references from
FPragma_Store_ExtCraftingEntry
toFPragma_Inventory_ExtCraftingEntry
- Replace all references from
FPragma_GameData_GetLoginDataV1Response.Payload().LoginData.GameCatalog
toFPragma_GameData_GetLoginDataV1Response.Payload().LoginData.ItemCatalog
- Replace all references from
Within your Unity game:
- Delete any broken using statements and import new references after regenerating SDK types.
- Update references from
GameCatalog
toItemCatalog
.
Use
PlayerMatchEndV2.server_item_updates
instead of PlayerMatchEndV2.item_updates
Migrate existing
InstancedDataProviderPlugin
implementations to new nameInstancedItemPlugin
- Use the single new
newInstanced
method for all instanced item creation. Presence of therequestExt
indicates server or client pathway. - The
update
method now has arequestExt
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
- Use the single new
Deprecations #
- `PlayerMatchEndV2.item_updates` deprecated. - `getDisplayNameForPragmaPlayerIdForPartnerV1` deprecated. Use match data for player display names. - Renamed operator RPC `ViewGamesV0` to `ViewGameTitlesV1`. No change in behavior.
2021-11-02
Features #
- Players can now invite others using Lobby Invite Codes.
Deprecations #
- Removed
insertAccountsOrIgnoreLegacy
fromUnsafeIdentityDaoNodeService
. UseinsertOrIgnoreAccounts
as a replacement. Types.DisplayName
has been removed in favor ofAccountCommon.DisplayName
- Removed
MatchLifecycleRpc.PlayerInfo
in favor ofMatchLifecycleRpc.PlayerInfoV2
(PlayerInfo.DisplayName string)/(DisplayNameV2 Types.DisplayName)
is now reflected in(PlayerInfoV2.DisplayName AccountCommon.DisplayName)
- Removed
MatchLifecycleRpc.MatchData
in favor ofMatchLifecycleRpc.MatchDataV2
MatchData.PlayerInfo
has been updated toMatchData.PlayerInfoV2
- Removed
MatchLifecycleService.MatchReadyV1
in favor ofMatchLifecycleService.MatchReadyV2
. - Removed
MatchCapacityRpc.ReportCapacityV1Request/Response
in favor ofMatchCapacityRpc.ReportCapacityV2Request/Response
. - Removed
buildExtensionMatchFoundNotification
.
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 usingoneof
pattern inExt
s InviteReceivedV1Notification
includes new fieldinviter_info
, containing theInviterInfo
(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
onInviteReceivedV1Notification
is intended to replace the functionality currently achieved with thegetDisplayNameForPragmaIdForPartnerV1
andgetDisplayNameForPragmaPlayerIdForPartnerV1
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 thePartnerConnectionInfoConfig
under thegameToken
parameter
Integration Notes #
TimeProxy
object has been moved to a class with a companion object. Any existing references toTimeProxy
should be redirected toTimeProxy.defaultInstance
InventoryContent
now returnsContentDataWrappers
instead ofGeneratedMessageV3
for the following calls:getStackableSpec()
,getInstancedSpec()
,getCatalogUpdateEntry()
,getRewardsTable()
,getRewardSlot()
,getRewardBag()
, andgetCraftingEntry()
. The data wrapper objects expose the same data as the proto object, but some names are slightly different. For example,RewardsTable.rewardSlotIdsList -> RewardsTableWrapper.rewardSlotIds
. TheGeneratedMessageV3
can still be accessed via thetoProtobuf()
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.
- Attempting to invite a player that is already in the lobby will now result in a
2021-10-19
Integration Notes #
InventoryV1Data
field onLobbyPlayer
has been removed, replaced byInventoryFullV1Data
.
2021-10-19
Features #
Protobufs
associated with content in thecontent
/shared
folder now use astring
ID instead ofint64
. 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
andlocal_game_player_inventory2
tables in the DB are destroyed and recreated with an additionalcatalogIdStr
field persisting the string value as defined above. The numericcatalogId
field will contain the (SipHash24
) hash of this string ID. - Promoted the RPC endpoint
CraftV0
toCraftV1
- The Unreal4, Unity and C# SDKs now have access to use theCraftV1
RPC endpoint. Implementation examples can be found in theArbiterInstancedDataProviderPlugin
andArbiterCraftingPlugin
; crafting catalog examples can be found inplatform/4-example-ext/content/shared/CatalogCraftingEntries.json
- Documentation can now be found in
pragma-engine/documentation/release
. OpenDefault.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 togameToken
, if you configure this value you will need to update it or authentication errors will occur inGameServer
calls
Deprecation #
InventoryV1Data
field onLoginData
has been removed.InventoryV1Data
field onLobbyPlayer
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.
2021-10-12
Features #
- Added new
coAssertThrowsExtError
andassertThrowsExtError
methods for testing convenience. Seeplatform/2-pragma/core/src/test/kotlin/pragma/utils/TestUtils.kt
Integration Notes #
AccountRpc.DisplayName
is nowAccountCommon.DisplayName
LobbyRpc.proto/LobbyPlayer.display_name
andLobbyRpc.LobbyPlayer.ext
fields have been removed. UseLobbyRpc.proto/LobbyPlayer.player_info.display_name
andLobbyRpc.LobbyPlayer.player_info.ext
instead.MatchCapacityRpc.StartMatchV1Request
,MatchLifecycleRpc.CreateMatchV1Request
,MatchmakingRpc.EnterMatchmakingForPartyV1Request
have been updated to usePlayerInfoV2
PlayerSession
has been updated to usepragma.account.DisplayName
- Removed
GetContentSha256ChecksumsV1Request
/Response
that was not used pragma.PragmaCoreTestFactory.playerInfo
moved topragma.MatchmakingTestFactory.playerInfo
and will need to be reimported if used in tests
Deprecation #
ReportCapacityV1Request
/Response
deprecated in favor ofReportCapacityV2Request
/Response
MatchReadyV1Request
/Response
deprecated in favor ofMatchReadyV2Request
/Response
types.proto/DisplayName
deprecated in favor ofaccountCommon.proto/DisplayName
matchLifecycleRpc.proto/PlayerInfo
deprecated in favor ofmatchLifecycleRpc.proto/PlayerInfoV2
matchLifecycleRpc.proto/MatchData
deprecated in favor ofmatchLifecycleRpc.proto/MatchDataV2
- Added new
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
andcraftingEntries
)
Integration Notes #
- The configuration of Discord authentication has changed very slightly. The block of configuration that used to live under
serviceConfigs.DiscordIdProviderConfig
now resides underpluginConfigs.AccountService.discordIdentityProvider
. See4-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 onLoginData
has been deprecated. UseLoginData
InventoryFullV1Data
.- Removed
InventoryV1Data
insideLobbyPlayer
. AffectsLobbyStrategy
plugin. MatchLifecycleService.MatchEndV2Request
deprecated in favor ofMatchLifecycleService.MatchEndV3Request
.InventoryService.ItemUpdateV3
deprecated in favor ofInventoryService.ItemUpdateV4
.
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
andFPragmaLobbyPlayer
are nowuobjects
(names changed toU*
) 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.
- Lobby Service
- A new operator RPC for creating
UnsafeProvider
(testing) accounts has been added
Integration Notes #
make run-with-config
has been fully replaced by make runMatchProcessedV1Notification
has been removed in favor ofMatchProcessedV2Notification
.PlayerMatchEndProcessor.generateUpdatesForPlayer
has been removed in favor ofPlayerMatchEndProcessor.buildUpdatesForPlayer
.- All settings files, including integration test settings files, must have their settings within the
game:
orsocial:
nodes - The portal resources have been moved back into the engine jar; as a result, any
pom.xml
files generated for5-ext
will have to be manually updated.
Deprecation #
- None
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")
- Specify the path in the call to BaseServerIT constructor. e.g.
Integration Notes #
- Use make protos instead of these removed aliases:
proto protobuf protobufs
Deprecation #
Pragma Engine -
CatalogStackableEntries.json
andCatalogInstancedEntries.json
have been removed in 0.0.36.- Integration tests can now specify a content directory
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.
- Generated proto
Integration Notes #
- Rename
CatalogStackableEntries.json
andCatalogInstancedEntries.json
toStackableItemSpecs.json
andInstancedItemSpecs.json
, respectively. - Integration test default config files were renamed from
InMemGame.yml
toInMemGameIT.yml
andInMemSocial.yml
toInMemSocialIT.yml
- If you use these
yml
files, ensure that the rename has been appliedplatform/5-ext/ext/src/test/resources/localDevelopmentShardConfig/
and preserves any custom settings
- If you use these
make run-with-config
5-ext
pom templates have changed. Merge templatepom-xmls.templates
into5-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
- Delete all the
Deprecation #
Pragma Engine -
CatalogStackableEntries.json
andCatalogInstancedEntries.json
will be removed in 0.0.36 Pragma Engine -make run-with-config
will be removed in 0.0.37- Default location for content is
2021-09-07
Integration Notes #
- Removed command line arguments
social-configuration-filepaths
andgame-configuration-filepaths
. These have been replaced with configuration-filepaths which support a unified configuration file format with agame:
section and asocial:
section. Please refer toplatform/TemplatePragmaConfig.yml
as an example of the new unified format. - Need to merge template
pom-xmls.templates
into5-ext/**/pom.xmls
. The process for this will be to delete all the5-ext/**/pom.xml
and runmake update-template
, then use a diff tool like the one built into IntelliJ to restore local changes.
- Removed command line arguments
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. UsegenerateProto()
instead (or create a tailored test factory for your proto)- The command line arguments
social-configuration-filepaths
andgame-configuration-filepaths
will be removed. Useconfiguration-filepaths
instead. Seeplatform/TemplatePragmaConfig.yml
for an example of the new config file format. - The
3-apps/server
module will be removed August 7.
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 and4-apps
have been renamed to3-apps
. All custom and …ext proto files as well as any extensions defined in3-extensions
should now be defined in the5-ext
module.- Customers should continue to use
make ext run
can be used to just build and run changes in5-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
andgame-configuration-filepaths
will be removed. Useconfiguration-filepaths
instead. Seeplatform/TemplatePragmaConfig.yml
for an example of the new config file format.
2021-08-17
Features #
- Introduced
InventoryRpc.ItemUpdateV4
andMatchendLifecycleRpc.MatchEndV3
MatchEndPlugin
can be authored to enable rpc calls to arbitrary services on match end.- UnrealSDK
- Update
PragmaInventoryService
to return full inventory snapshot onStorePurchaseV4
,UpdateItemsV0
,UpdateItemV3
,UpdateItemV4
- Oneofs allow nothing to be set for serialization or deserialization.
- Code gen: Fix out of order dependencies when using maps.
- Update
Integration Notes #
UpdateItemsV0Request
was updated to useinventoryRpc.ItemUpdateV2
MatchEndV0Request
was updated to usematchlifecycle.MatchEndV2
Architecture Change #
3-extensions
will be removed and4-apps
will be renamed to3-apps
. All custom and …ext proto files as well as any extensions defined in3-extensions
will soon be defined in the5-ext
module.
- Introduced
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 forwardsMatchFailureV1Notification
andGameStartFailureV1Notification
. - Exposed
LobbyServiceRaw::GameStartFailureV1Notification
event.
Deprecation #
- Removed
storePurchaseV3
frominventoryRpc.proto
should usestorePurchaseV4
. - Removed
GetInventoryV1
frominventoryRpc.proto
should useGetInventoryV2
. - Removed
ServiceGetInventoryV1
frominventoryRpc.proto
should useServiceGetInventoryV2
.
2021-08-04
Features #
- Authentication will now return information about error conditions specific to Discord auth failures.
LobbyService
correctly setsExtPlayerInfo
onrespondToLobbyInvite
andcreateAndJoinLobby
calls using theLobbyStrategy.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 aplayer_info
in it. Instead usePlayerInfo
inmatchLifecycleRpc.proto
.StoreEntry
has replacedrequirements
andcatalog_ids_required_in_inventory
with a newPurchaseRequirements
that includes a newstore.ExtPurchaseRequirements
field.- This will be a breaking change to store content if entries reference the old fields
InventoryCommon.ItemUpdateV2
andInventoryCommon.ItemGrantV2
has been changed so internalinstanced
andstackable
fields is aoneof
Deprecation #
- Removed
player_info
fromExtEnterMatchmakingV1Request
inmatchmakingExt.proto
.
Removed #
InventoryRpc.UpdateItemV2
- Use
InventoryRpc.UpdateItemV3
- If using UE4 SDK, please use
PragmaInventoryService.UpdateItemV3
- Use
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.
- Now comes with a Rich Inventory SDK (
Integration Notes #
MatchmakingStrategy.buildMatchmakingKey
has been deleted; remove from strategy implementationsMatchmakingStrategy.buildExtPlayerInfo
has been deleted; remove from strategy implementationsMatchmakingRpc.EnterMatchmakingV1
has been deleted; useMatchmakingRpc.EnterMatchmakingForPartyV1
instead- Proto Renames for Store
Store.UpgradeEntry
→Store.UpdateEntry
Store.ExtUpgradeEntry
→Store.ExtUpdateEntry
- Rename
CatalogUpgradeEntries.json
→CatalogUpdateEntries.json
- All implementations of
PlayerMatchEndProcessor
must now implementbuildUpdatesForPlayer
, which provides a builder that exposesstats
andext
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
- Use
InventoryRpc.StorePurchaseV3
- Use
InventoryRpc.StorePurchaseV4
- If using UE4 SDK, please use
PragmaInventoryService.StorePurchaseV4
- Use
InventoryRpc.GetInventoryV1
- Use
InventoryRpc.GetInventoryV2
- If using UE4 SDK, please use
PragmaInventoryService.GetInstancedItemsV1
,PragmaInventoryService.GetStackableItemsV1
- Use
InventoryRpc.ServiceGetInventoryV1
- Use
InventoryRpc.ServiceGetInventoryV2
- Use
Removed #
InventoryRpc.SimulateRewardsV1
- Use
InventoryRpc.SimulateRewardsV2
- Use
- Unreal SDK
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 a200
forever thereafter
- Will respond with a
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.
- You should be running the
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.
- Now supports OAuth PKCE security when authenticating with Discord. Pragma now accepts the
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
andDiscriminator
are available inAccountService
after logging in.- Added
MatchFailureV1Notification
Raw event.
- Added rich lobby implementation in
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
- Use
2021-06-22
Improvements #
- Fixed a bug where Players were getting invites from “Unknown”
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
andMatchLifecycle
Raw services. Fixed128
s now print as UUID strings in logs instead of msb/lsb json objects.
- Raw services can now be accessed directly from
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
- Eg.
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
- Eg.
Integration Notes #
Pragma Package Rename
- any protos using
gg.pragma.core.Fixed128
type should useimport "pragma/types.proto";
- and replace message types from
gg.pragma.core.Fixed128 example_proto = 3;
toFixed128 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 usepragma
instead - Will need to close the Intellij IDE, delete the maven .m2 repo cache for
/gg/pragma
, run amake clean build
and restart the IDE and reload Maven Projects gg.pragma.game
,gg.pragma.core
,gg.pragma.social
,gg.pragma.protobuf
andgg.pragma
have all been combined intopragma
pragma.match.lifecycle
has been combined intopragma.matchlifecycle
pragma.match.capacity
has been combined intopragma.matchcapacity
- Folder structures match package structure much more closely
- Unity SDK replaces
Pragma.Core
,Pragma.Game
,Pragma.Social
withPragma
- Unreal4 SDK replaces
EPragma_Core_*
withEPragma_*
Deprecation #
Pragma Engine - REMOVED in 0.0.23:
Inventory.upgradeItemV1
- Use
Inventory.updateItemV2
- Use
Inventory.updateItemV1
- Use
Inventory.updateItemV2
- Use
Inventory.storePurchaseV2
- Use
Inventory.storePurchaseV3
- Use
PlayerMatchEnd.stackable_updates
- Use
item_updates
- Use
MatchEndPlayerData.instancedGrants
- Now included in
Inventory.ItemGrants
- Now included in
MatchLifeCycleServicePB.MatchFoundV1Notification
- Should already be using
MatchLifeCycleRpc.MatchConnectionDetailsV1Notification
- Should already be using
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.
- LobbyService
- Unity/C#
- We now have a non-unity C# SDK!
- Fixed a bug where failed
UpdateBackendConfig
would never callOnComplete
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
toProtocolType.Http
- Set
- 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
andupdateItemV1
- Uses the same list of
ItemUpdate
objects fromMatchEnd
- Replaces
UpdateItemsV0
- plural form ofUpdateItemV2
to update items in bulk.OperatorGrantRewardsV0
- operator endpoint that directly grantsRewardGrant
(s) to aplayerId
for testing and player supportStorePurchaseV3
- uses new standard formatted params comparable toUpdateItemV2
etc.
Integration Notes #
LobbyStrategy.buildExtensionMatchmakingRequest
(returns a pair of values, anExtensionEnterMatchmakingV1Request
and aMatchmakingKey
) has been deleted, in favor of the following two functions:LobbyStrategy.buildExtensionEnterMatchmakingV1Request
LobbyStrategy.buildMatchmakingKey
- Note:
extLobbyInfo
(the parameter for the previous call) is available fromlobbyModel.extLobbyInfo
InstancedDataProviderPlugin.newInstanced()
was updated to take the fullCatalog.InstancedEntry
instead of just thecatalogId
for the new instanced item.
Deprecations #
Inventory.upgradeItemV1
- Use
updateItemV2
- Use
Inventory.updateItemV1
- Use
updateItemV2
- Use
MatchFoundV1Notification
- Use
MatchConnectionDetailsV1Notification
- Use
PlayerMatchEnd.stackable_updates
- Use
item_updates
- Use
Removed #
Catalog.InstancedEntry.instance_defaults
replaced byExtensionInstancedEntry.ext
- Removed (were unused)
StackableEntryUpdate
InstancedEntryUpdate
InventoryUpdateV1Notification
- Removed in favor of new variants
MatchEndV1Request
- Use
MatchEndV2Request
- Use
MatchEndV1Notification
- Use
MatchEndV2Notification
- Use
- UnrealSDK
UPragmaConnection::OnDisconnected
- Use
UPragmaConnection::OnDisconnectedV2
.
- Use
TPragmaResult::UnknownErrorCode
.- Use
FPragmaError::UnknownError
.
- Use
2021-06-04
Features #
- Expose extension data on
MatchEndNotification
2021-06-01
Features #
- Add ability to update instanced inventory on match end.
- See
InstancedItemUpdate
andInstancedDataProviderPlugin.update
- See
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 useUPragmaConnection::OnDisconnectedV2
. Pragma Engine - DEPRECATED this release (Scheduled for removal in 0.0.23):TPragmaResult::UnknownErrorCode
. Please useFPragmaError::UnknownError
.
StorePurchaseV2
deprecatedPlayerMatchEnd.stackable_updates
to be replaced byPlayerMatchEnd.item_updates
- Expose extension data on
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
- All Game Data Service Player RPCs and Notifications
- Matchmaking
- Added basic warm body matchmaking strategies
OneVsOneWarmBodyMatchmakingStrategy
FreeForAllWarmBodyMatchmakingStrategy
ThreePlayerCooperativeWarmBodyMatchmakingStrategy
ThreeVsThreeWarmBodyMatchmakingStrategy
- Added basic warm body matchmaking strategies
- Unity SDK
2021-05-25
Features #
- Game server metrics support
MatchEndV2
supports newmetrics
fieldMatchEndV2
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.
- All RPCs defined in the Lobby service are now available through the
- 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
- Enable by adding the following to your
- Raw api services can now be accessed directly via
Session::GetService()
(Session.Account().Raw()
style is still available though). PragmaResult
now has anError()
method that gets the error (ifIsFailure
is true) as a new typeFPragmaError
which encompasses new platform & sdk error enums.- Protocol internals now use
TUniqueFunction
instead ofTFunction
(Can nowMoveTemp
intoRaw
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 nowMoveTemp(TPromise)
into aRaw
method lambda.
- Eliminated an excess copy when passing delegates to
- 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.
- The method will call
SessionService().GetAttribute
- Used to retrieve current Session attributes.
SessionService().GetAttributeChangedDelegate
- Used to watch for
SessionAttribute
changes.
- Used to watch for
- Currently the only Session Attribute is the Game
LobbyId
.
- Added opt-in compile-time deprecation warnings
- To enable, in your
Project.Build.cs
addPrivateDefinitions.Add("PRAGMASDK_ENABLE_DEPRECATION_WARNINGS");
- To enable, in your
- Added a full, stateful Lobby implementation accessible via
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 byExtensionInstancedEntry.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 useUPragmaConnection::OnDisconnectedV2
.TPragmaResult::UnknownErrorCode
. Please useFPragmaError::UnknownError
.
- Game server metrics support
2021-05-18
Deprecation #
- REMOVED this release:
make.ps1
script removedContent 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 byExtensionInstancedEntry
ext
- REMOVED this release:
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
- Steam Identity Provider
2021-05-04
Features #
- Unreal SDK
- Extension services should now live outside of the SDK and register with
Session::RegisterService
instead of being added toPragmaExtensionServices.h
. - New SDK update script:
sdk/unreal4/update-pragma-sdk.sh
.- See script for configuration details.
UPragmaConnection::ConnectionError
renamed toUPragmaConnection::FConnectionError
PragmaSdkConfig
has aUserData
field that can be used to pass arbitrary data using the existingPragma.ini
flow at deploy-time.
- Extension services should now live outside of the SDK and register with
- 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.
- Support for deploying game server binary to a shard.
Deprecation #
Pragma Engine - DEPRECATED this release (will be removed in release 0.0.18):
make.ps1
scriptstorePurchaseV1
RPC
- Unreal SDK
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
- See the Execution section in
- Unreal SDK
UPragmaMatchCapacityService
has a new methodReportCapacityUntilMatchAllocated
for use in the Local Process and Multiplay server flows.- New helper object
UPragmaMultiplayConfig
which can be used to automatically scan for Multiplay-specificserver.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 ofUNKNOWN_ERROR
- Client will receive
- 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.
- Content data is now exclusively loaded externally from the jar from a supplied folder
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
- Buildkite pipeline will conditionally perform build steps based on whether changes were made for a particular step. These are:
- Reduced log output on build and run by default to reduce noise
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
vsskip-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
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
- Plugin support
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
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
- Disconnect events now include an
GetContentSha256ChecksumsV1Request
- Retrieve OS aware sha256 hash of content data that can be used to quickly check content versions