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 the LoginQueueServiceConfig. | 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 your pom.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 the FPlayer 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 and ext-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 #

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 exts 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 #

[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, under parent, verify you have the line: <relativePath>../engine-settings.xml</relativePath>
  • In 5-ext/ext-protos/pom.xml under parent, verify you have the line: <relativePath>../../engine-settings.xml</relativePath>

Pragma Engine 0.0.94
Pragma Engine 0.0.96