Pragma Engine 0.0.95
August 2023
Contents #
Summaries | Summarized release notes.
Full Notes | Full notes including descriptions and additional details.
Summaries #
Features #
- [Multiplayer] New Game Instance object and interfaces. | full note
- [Multiplayer] New Game Instance service plugins. | full note
- [Multiplayer] Custom data available for players entering a game instance. | full note
- [Multiplayer] Custom data available within matchmaking game instances. | full note
- [Accounts] Player authentication now supports login queue bypass for faster development iterations. | full note
- [Accounts] You can now have multiple custom identity providers. | full note
- [Portal] Added Limited Grants support. | full note
Deprecations #
- [Infra & Tooling] config | Individual database configuration will not be supported starting in the next release. | full note
Integrations #
- [Multiplayer] Multiplayer features have undergone significant change in version 0.0.95. For integration instructions related to the Pragma Engine Multiplayer features, contact your Pragma representative to get the 0.0.95 Multiplayer integration guide. | full note
- [Accounts] config | Remove the
enabled
configuration from theLoginQueueServiceConfig
. | full note - [Accounts] config | Remove unused fields from Portal config and reconfigure identity provider values. | full note
- [Accounts] platform | If you have the
jsign-core
Maven dependency in yourpom.xml
, you will need to remove it. | full note - [Accounts] sdk | If you’re using the
UPragmaAccountService
, you’ll need to replace the deprecated methods with theFPlayer
class. | full note - [Player Data] sdk | If you sync entitlements, you’ll need to update the
ProviderData
object. | full note - [Infra & Tooling] platform | Add the relative path to the
5-ext
andext-protos
poms in Pragma Engine settings. | full note
Bugs and Fixes #
- [Multiplayer] Fixed usage of timeouts in the SDK’s
MatchApi.StartReportCapacityPolling
method. - [Accounts] The login queue bug introduced in the 0.0.93 release that caused the login queue to only work in single-node deployments has been resolved.
- [Portal] Instanced Items are now the default tab when viewing a player’s inventory.
- [SDKs] Unreal: Fixed an issue where the SDK would still try to connect to WebSockets in HTTP mode.
- [Other] Updated README to describe the order of pom file imports for
5-ext
.
Docs #
- [New Release Notes Page] Added a new section on the Pragma Engine and Pragma SDK to the Release Notes section.
- [Updated Concepts] Improved Login Queue documentation to include information about development use of the login queue bypass.
- [Updated Concepts] Improved code samples in Adding Database Storage.
- [Updated Concepts] Added code samples to the Encryption and Decryption customization topic.
- [Updated Concepts] Added a table to the Authentication concepts page on identity providers and their respective values.
- [Updated Concepts] Added more information on how to create multiple identity providers on the Identity Providers concepts page.
- [New Tech Blog Article] The article Pragma Backend Load Testing Results: Achieving 1 Million CCU is now live! This article overviews data from our recent load testing efforts and showcases results from our 1 million CCU load tests.
Full Notes #
Features #
[Multiplayer] New Game Instance object and interfaces. #
Description: The new GameInstance
object represents a running game instance and includes a GameInstance
, GameParty
, and GamePlayer
interface.
Details: The GameInstance.GameInstance
interface acts as an identifier of the game instance, including a list of parties, players, removed players, and exts. The GameInstance.GameParty
and GameInstance.GamePlayer
interfaces represent a party and a player within the game and can be used with the new Game Instance service plugins to provide details to players and matchmaking services.
Related notes: See “Update references to the Match Lifecycle service to use the new Game Instance service” in the Multiplayer integration guide.
[Multiplayer] New Game Instance service plugins. #
Description: The new Game Instance Plugin and Game Instance Matchmaking Plugin can be used to prepare custom data to send to the game server, matchmaking service, or player. These new plugins replace the Match Found Plugin.
Related notes: See “Update references to Match Found Plugin methods” in the Multiplayer integration guide.
[Multiplayer] Custom data available for players entering a game instance. #
Description: Users can define custom data to send to players when the player is added to a new game instance. This data will be sent to the players immediately, even if a game server is still preparing to host the match.
Details: You define custom data in the new GameInstanceExt.ExtAddedToGame
payload, implement the GameInstancePlugin
’s buildExtAddedToGame
method to compose the payload, and then use the GameLoopApi.OnAddedToGame
event to receive the payload from the player session.
Related notes: See “Replace OnMatchFound references with OnAddedToGame” in the Multiplayer integration guide.
[Multiplayer] Custom data available within matchmaking game instances. #
Description: When using matchmaking to match players with game instances, users can present important content about parties and players within the game instance to the matchmaker.
Details: The GameInstanceMatchmakingPlugin
has received two new functions: buildExtMatchmakingGameParty
and buildExtMatchmakingGamePlayer
. These functions are invoked for every GameInstanceParty
and GameInstancePlayer
within a GameInstance
that is entering matchmaking, as well as for any new players added to the game instance while it is still in matchmaking. The populated ext
s will then be available on the Matchmaking.GameParty
and Matchmaking.GamePlayer
object when comparing Matchables within the matchPartiesWithGame
method.
Related notes: See “Define separate ext payloads to represent game instance parties and game instance players within matchmaking” in the Multiplayer integration guide.
[Accounts] Player authentication now supports login queue bypass for faster development iterations. #
Description: To learn more about using the login queue, see Login and Session.
Details: To turn on login queue bypass, set the devLoginQueueBypass to true in your Social service configuration.
social:
serviceConfigs:
SocialPlayerGatewayConfig:
devLoginQueueBypass: true
Related notes: This update improves the login queue functionality introduced in 0.0.93. If you took 0.0.93 or 0.0.94 see the related integration note.
[Accounts] You can now have multiple custom identity providers. #
Description: You can now define one or more custom identity providers in ExtIdProvider
which can be found in the accountRpcExt.proto
.
Related notes: See integration notes on removing unused fields from the Portal config and reconfiguring identity provider values and updating sync entitlements.
[Portal] Added Limited Grants support. #
Description: Description: You can now view and manage Limited Grants in the Content Catalog and the Content Catalog Editor.
Deprecations #
[Infra & Tooling] config | Individual database configurations will not be supported starting in the next release. #
Description: Pragma Engine will only support the shared database configuration model for DAOs beginning in release 0.0.96. This new format allows you to only set the user, password, and host in one location.
You will need to create a new SharedDatabaseConfigServiceConfig with the values from your environment, including the username, password, and host. Each DAO config then needs to be updated to use the identifierSchemas
and the identifier
block to reference the expected database configuration while setting the schema to what it was previously.
- Before:
ExampleDaoConfig:
databaseConfig:
username: "superuser"
password: "my_encrypted_secret_password"
hostPortSchema: "database.shard.example.com:3306/example_name"
OtherExampleDaoConfig:
databaseConfig:
username: "superuser"
password: "my_encrypted_secret_password"
hostPortSchema: "database.shard.example.com:3306/other_example_name"
- After:
SharedDatabaseConfigServiceConfig:
databaseConfigsByIdentifier:
exampleIdentifier:
username: "superuser"
password: "my_encrypted_secret_password"
host: "database.shard.example.com:3306"
ExampleDaoConfig:
databaseConfig:
identifierSchemas:
1:
identifier: "exampleIdentifier"
schema: "example_name"
OtherExampleDaoConfig:
databaseConfig:
identifierSchemas:
1:
identifier: "exampleIdentifier"
schema: "other_example_name"
Integrations #
[Multiplayer] Multiplayer features have undergone significant change in version 0.0.95. For integration instructions related to the Pragma Engine Multiplayer features, contact your Pragma representative to get the 0.0.95 Multiplayer integration guide. #
[Accounts] config | Remove the enabled
configuration from the LoginQueueServiceConfig
.
#
Description: If you upgraded to Pragma Engine 0.0.93 or 0.0.94 the LoginQueueServiceConfig
configuration included an option to enable or disable the login queue. This has been removed in 0.0.95 and replaced with the devLoginQueueBypass
configuration in the SocialPlayerGatewayConfig
.
For more information, see Login Queue.
Integration step: config | Remove the enabled
configuration from the LoginQueueServiceConfig
.
[Accounts] config | Remove unused fields from Portal config and reconfigure identity provider values. #
Description: We have added a new /v1/idproviders
endpoint that allows the Portal to request up-to-date identity provider information. The four config fields discordClientId
, googleClientId
, twitchClientId
, and authenticationIdProviders
are now removed from the FilePortalModulePlugin
. To configure these values, set them on their respective Identity Provider Plugin config.
Note that instead of config/config.json
, custom portal builds will need to pull in changes to check the new /v1/idproviders endpoint
. The way identity providers retrieve their public information (clientId
) has changed.
Integration steps:
- config | Remove the unused fields from the Portal
routePlugin
.- Before:
pluginConfigs: SocialOperatorGatewayNodeService.routePlugins: plugins: Portal: class: "pragma.gateway.FilePortalModulePlugin" config: portalSource: "web/portal/dist" authenticationIdProviders: 1: UNSAFE 3: DISCORD 4: STEAM 6: GOOGLE discordClientId: "YOUR_DISCORD_CLIENT_ID" googleClientId: "YOUR_GOOGLE_CLIENT_ID"
- After:
pluginConfigs: SocialOperatorGatewayNodeService.routePlugins: plugins: Portal: class: "pragma.gateway.FilePortalModulePlugin" config: portalSource: "web/portal/dist"
- config | If you’re using an identity provider to log into Portal, you’ll need to set the
portalLoginEnabled
flag to true on the respective Identity Provider Plugin config. Below is an example of the Google identity provider enabled for Portal:social: pluginConfigs: AccountService.identityProviderPlugins: plugins: Google: class: "pragma.account.GoogleIdentityProviderPlugin" config: portalLoginEnabled: true
[Accounts] platform | Add ExtIdProvider
to accountRpcExt.proto
.
#
Description: We’ve added ExtIdProvider
to support multiple custom identity providers. You must add ExtIdProvider
to accountRpcExt.proto
or your Pragma Engine will fail to compile.
Integration step: platform | Add ExtIdProvider
to accountRpcExt.proto
:
enum ExtIdProvider {
EXT_UNUSED = 0; // do not use; this exists to make Unsafe value 1 -hrb
reserved 1 to 100; // Pragma supported Id Providers
// === EXTENSIONS (101+) ===
}
[Accounts] platform | If you have the jsign-core
Maven dependency in your pom.xml
, you will need to remove it.
#
Description: An additional Maven dependency was added to the global dependency definitions. If you already have the jsign-core
dependency in your pom.xml
, it will need to be removed.
Integration step: platform | If the following dependency is present in your pom.xml
, it will need to be removed:
<properties>
<jsign.version>4.2</jsign.version>
</properties>
...
<dependency>
<groupId>net.jsign</groupId>
<artifactId>jsign-core</artifactId>
<version>${jsign.version}</version>
</dependency>
[Accounts] sdk | If you’re using the UPragmaAccountService
, you’ll need to replace the deprecated methods with the FPlayer
class.
#
Description: The deprecated methods in UPragmaAccountService
have been removed and need to be replaced by the FPlayer
class.
Integration step: sdk | Replace the following methods from UPragmaAccountService
with the FPlayer
class.
- Before:
// originals from UPragmaAccountService
void LogIn(
const EPragma_Account_IdProvider ProviderId,
const FString& ProviderToken,
const FLoggedInDelegate& OnComplete
);
void LogIntoExistingSession(
FString InPragmaSocialToken,
FString InPragmaGameToken,
FString InPragmaPlayerId,
const FLoggedInDelegate& OnComplete
);
const FString& GetPragmaId() const;
const FString& GetPragmaSocialId() const;
const FString& GetDisplayName() const;
const FString& GetDiscriminator() const;
const FString& GetFullDisplayName() const;
const FString& GetPragmaSocialToken() const;
const FString& GetPragmaGameToken() const;
- After:
// replacements in Pragma::FPlayer
void LogIn(
const EPragma_Account_IdProvider ProviderId,
const FString& ProviderToken,
const FLoggedInDelegate& OnComplete
);
void LogIn(
FString InPragmaSocialToken,
FString InPragmaGameToken,
FString InPragmaPlayerId,
const FLoggedInDelegate& OnComplete
);
const FString& Id() const;
const FString& SocialId() const;
const FString& DisplayName() const;
const FString& Discriminator() const;
const FString& FullDisplayName() const;
const FString& PragmaSocialToken() const;
const FString& PragmaGameToken() const;
[Player Data] sdk | If you sync entitlements, you’ll need to update the ProviderData
object.
#
Description: If you call the sync entitlements SDK functions below, you’ll need to update the ProviderData
object with an EnumToString
for the following SDK methods:
UPragmaInventoryService::SyncEntitlements
UPragmaInventoryService::SyncEntitlementsWithProviderData
Integration step: sdk | Update the following:
- Unreal
- Before:
const auto ProviderData = FPragma_Inventory_ProviderData{EPragma_Account_IdProvider::UNSAFE, ""};
- After:
const auto ProviderData = FPragma_Inventory_ProviderData{EnumToString<EPragma_Account_IdProvider>(EPragma_Account_IdProvider::UNSAFE), ""};
- Unity
- Before:
var providerData = new ProviderData { Provider = IdProvider.Unsafe, AuthCode = "" };
- After:
var providerData = new ProviderData { Provider = IdProvider.Unsafe.GetOriginalName(), AuthCode = "" };
[Player Data] platform | Add the relative path to the 5-ext
and ext-protos
poms in Pragma Engine settings.
#
Description: We’ve added the relative path to poms to fix bugs. Integration steps:
- In
5-ext/pom.xml
, underparent
, verify you have the line:<relativePath>../engine-settings.xml</relativePath>
- In
5-ext/ext-protos/pom.xml
underparent
, verify you have the line:<relativePath>../../engine-settings.xml</relativePath>