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
{{% variable "Pragma" "path-content" %}}
: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:
{{% variable "Pragma" "path-extProto" %}}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:
{{% variable "Pragma" "path-extProto" %}}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 {{% variable "Pragma" "postman-authenticateOrCreateV1" %}}
{{% variable "Pragma" "postman-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
- {{% variable “Pragma” “postman-GetLoginDataV1-name” %}} 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 {{% variable “Pragma” “command-make-run” %}}MatchProcessedV1Notification
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 {{% variable “Pragma” “command-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