Integrations and Deprecations 0.2.0 #

This topic includes integrations and deprecations for Pragma Version 0.2.0.

Integrations #

Behavioral changes #

This section describes changes in behavior due to new/updated functionality. Extra care should be taken when implementing changes to avoid unexpected behaviors or regressions.

[Game Instance] Update GameInstancePlugin.onEndGame() to explicitly end a game #

Pragma Engine no longer implicitly ends a game instance after GameInstancePlugin.onEndGame() is called. To preserve existing behavior, update onEndGame() to explicitly call the new gameInstance.end() method.

Integration steps:

• Locate custom implementations of GameInstancePlugin.onEndGame()
• Call gameInstance.end() within in plugin method
• Take the <PlayerIds, ExtGameEnded> map returned by the current onEndGame() implementation, and pass it to gameInstance.end(extMap) as the extMap parameter

See also: New Game Instance capabilities.

[Accounts] Set enableLegacyInventoryDataCollection to true to include player’s inventory in their data rights request package #

Pragma Engine no longer includes player’s inventory in the data rights package by default. To include a player’s inventory data in the game data rights report, set the new enableLegacyInventoryDataCollection config property to true under the game config section.

game:
  pluginConfigs:
    DataRightsPollingService.dataRightsGamePlugin:
      class: "pragma.datarights.DefaultDataRightsGamePlugin"
      config:
        enableLegacyInventoryDataCollection: true

Syntax changes #

This section describes changes in naming, file locations, and other syntactical updates.

[Accounts] Reorganize Unsafe Identity Provider config values #

We created an Unsafe Identity Provider Plugin to make configuring the Unsafe identity easier and to match the behavior of other identity provider plugins.

Integration steps:

Before: to enable/disable the Unsafe identity provider, set canAuthenticate to true or false

social:
  serviceConfigs:
      UnsafeIdentityDaoConfig:
        canAuthenticate: true 
        databaseConfig:
          username: "username"
          password: "password"
          hostPortSchema: "host-port-schema"
  pluginConfigs:
      AccountService.identityProviderPlugins:
        plugins:
            Steam:
              class: "pragma.account.SteamIdentityProviderPlugin"

After: to enable the Unsafe identity provider, remove canAuthenticate and add the Unsafe Identity Provider Plugin.

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      databaseConfig: 
        username: "username"
        password: "password"
        hostPortSchema: "host-port-schema"
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Unsafe:
          class: "pragma.account.UnsafeIdentityProviderPlugin"
        Steam:
          class: "pragma.account.SteamIdentityProviderPlugin"

After: To disable the Unsafe identity provider, don’t include the Unsafe identity provider plugin.

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      databaseConfig: 
        username: "username"
        password: "password"
        hostPortSchema: "host-port-schema"
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Steam:
          class: "pragma.account.SteamIdentityProviderPlugin"

[Accounts] If you have a custom identity provider that you are using for Portal login, you’ll need to add an enumValue field #

To support additional behaviors around displaying provider information, we now require enumValue in all authProviders.

Add the associated enum IdProvider to the new enumValue field in your authProvider. In addition, if you have a custom portal build you’ll need to manually add the ID to each authProvider.

For example, to add a custom identity provider you’ll need to define it in the accountRpcExt.proto file.

enum ExtIdProvider {
    EXT_UNUSED = 0;  
    reserved 1 to 100; // Pragma supported Id Providers

    //  === EXTENSIONS (101+) ===
    MY_CUSTOM_PROVIDER = 101;
}

Below is an example of how you would modify your custom authProviders/myCustomProvider/myCustomProvider.js file.

...
export default {
  id: MyCustomProvider.PROVIDER_ID,
  name: 'My Custom Provider',
  iconName: 'myCustomProvider',
  enumValue: 101,
 ...

[Accounts] Setup for upcoming Orders and Fulfillments services #

This integration is required. It is to enable the upcoming Orders and Fulfillments services.

Integration steps:

• Copy the orderExt.proto and orderContentExt.proto files from platform/1-protos/proto-exts/src/main/proto/shared/ into platform/5-ext/ext-protos/src/main/proto/shared/
• If not already configured, include OrderDaoConfig in the database config.
• If not already configured, include FulfillmentDaoConfig in the database config.

social:
  serviceConfigs:
    SharedDatabaseConfigServiceConfig:
      databaseConfigsByIdentifier:
        defaultIdentifier:
          username: "superuser"
          password: "password"
          host: "localhost"
    OrderDaoConfig:
      databaseConfig:
        identifierSchemas:
          1:
            identifier: "defaultIdentifier"
            schema: "local_social_order1"

game: 
  serviceConfigs:
    SharedDatabaseConfigServiceConfig:
      databaseConfigsByIdentifier:
        defaultIdentifier:
          username: "superuser"
          password: "password"
          host: "localhost"
    FulfillmentDaoConfig:
      databaseConfig:
        identifierSchemas:
          1:
            identifier: "defaultIdentifier"
            schema: "local_game_fulfillment1"

• If you have a multi-node environment, please reach out to Pragma to ensure these services are added to your infrastructure correctly.

[Engine] | Remove unused logging configurations from yml file #

Remove any definition of the following from your shard configuration yml:

• LoggingConfig.fileLoggerRolledFilename
• LoggingConfig.fileLoggerMaxFileSize
• LoggingConfig.fileLoggerRolledTotalSizeCap

[Engine] Update the load test modules in 5-ext #

If you have made modifications to the load-test-core module, manually update the 5-ext\load-test-core\src\test\kotlin\pragma\loadtest\PreRebalanceInventorySetup.kt and 5-ext\load-test-core\src\main\kotlin\pragma\loadtest\ScenarioFactory.kt files with the following change:

Old: val clientFactory = PragmaClientFactory(

New: val clientFactory = PragmaClientFactory.build(

If you haven’t made any modifications to the load testing modules, delete the generated load-test and load-test-core modules under 5-ext and run make ext to regenerate the modules.

[Game Server] Update configurations to account for new game server version default #

The dev-defaults.yml config now specifies a defaultGameServerVersion as a fallback configuration for all game client versions. If you were using the following two values, remove them in all config yaml files:

• enableGameServerVersionDefault
• gameServerVersionDefault

If you already defined your own server compatibility map, no action is required. To specify your own default game server version, see Manage game server compatibility.

[Multiplayer] Update references to relocated SDK files #

The following common files in the Unreal and Unity SDKs have been relocated for better project organization. Update references to the following objects:

Unreal

Unity

[Multiplayer] Update config files for enableAbsoluteTimeout and absoluteTimeoutMillis renames #

Update any config files that define the following GameInstanceServiceConfig keys:

Note that the timeout unit has changed from milliseconds to minutes.

[Party] Update expected return value for Unreal PartyApi.GetPendingPartyInvites #

PragmaPartyApi.GetPendingPartyInvites() now returns TSharedPtr<const TArray<FPragmaPartyInvite>>.

[Presence] Update reference to GetPresence() SDK function #

Replace calls to UPragmaPresenceApi::GetPresence() with calls to UPragmaPresenceApi::GetPresenceCache()->GetPresence().

The original structure was deprecated in Pragma Engine version 0.1.0 and is no longer available as of 0.2.0.

[Presence] Replace PresenceGameBackendClient with PresenceApi #

In your 5-ext folder, replace references to the PresenceGameBackendClient class with references to the backend PresenceApi class.

[Player Data] Update any Player Data Operation callbacks in the Unreal SDK to take the TPragmaResult parameter instead of TOptional #

Player Data Operations previously returned a TOptional in the Unreal SDK. This parameter provided no detail as to why a callback for an Operation failed and was incompatible with application errors.

Integration steps:

• sdk | Replace all Player Data callbacks in the Unreal SDK to take a TPragmaResult<X> parameter instead of TOptional<X>. TOptional::Get has no direct equivalent for TPragmaResult, so any instances of TOptional::Get need to be manually replaced.

• sdk | Update your SDK Operation code with any new function names for TPragmaResult, such as:

  • IsSet -> IsSuccessful
  • GetValue -> Payload

[Player Data] Update reference to PlayerDataProtoTestFactory #

We renamed the PlayerDataProtoTestFactory to PlayerDataCoreTestFactory in the pragma-engine/platform/2-pragma/core/src/test/kotlin/pragma/ folder. Update references accordingly.

Game Server Allocation Changes #

Make the following changes to account for the new game server allocation process. See Allocate a dedicated game server in the Game Instance Tasks for more information on allocating game servers.

Game Instance Plugin changes #

• Explicitly allocate a game server for a game instance by invoking GameInstanceInterface.allocateGameServer() from any GameInstancePlugin method
  • To keep existing behavior, no action is needed. allocateGameServer() is automatically called from the new GameInstancePlugin.handleBackendCreateByMatchmakingRequest() method, which will start the allocation process as soon as a game instance is created out of matchmaking.
• Rename any overridden Game Instance Plugin updateGameInstance() methods to handleBackendUpdateRequest()

Game Server Provider Plugin (formerly Game Instance Host Plugin) changes #

• If you have a custom implementation of the GameInstanceHostPlugin, move functionality to a GameServerProviderPlugin implementation.

  • Replace GameInstanceHostPlugin.findHostForGameInstance() with GameServerProviderPlugin.startAllocationForGameInstance()

• If using Amazon GameLift, Hathora, or Multiplay, reach out to your third-party representative to get access to the appropriate Game Server Provider Plugin implementation.

• If using the Pragma Fleet service you should now use the FleetGameServerProviderPlugin.

• Update all config references to GameInstanceHostPlugin to instead point to GameServerProviderPlugin.

• Consider switching to the LocalProcessGameServerProviderPlugin if:

  • You have been using the FleetService and LocalProcessFleetPlugin only for local development
  • You already use the GameInstanceHostPlugin/GameServerProviderPlugin for non-local deployments

Ext changes #

• In 5-ext/ext-protos/src/main/proto/shared/gameInstanceExt.proto

  • Rename ExtUpdateGameInstanceRequest to ExtBackendUpdateRequest

  • Add a definition for the new ExtPlayerUpdateRequest payload

  • Add a definition for the new ExtAllocateGameServer payload

    • If you were previously inspecting fields on GameInstance.GameInstance to perform game server allocation work, put that data in ExtAllocateGameServer

• In 5-ext/ext-protos/src/main/proto/shared/fleetExt.proto, delete ExtHostRequest. Migrate necessary fields to ExtAllocateGameServer.

• In implementations of the FleetPlugin, change any ExtHostRequest function parameters to use ExtAllocateGameServer instead

Deprecations #

[Party] Move data stored on PartyPlayer.inventory to PartyPlayer.ext #

The Party.PartyPlayer.inventory property is deprecated in release 0.2.0. Party Plugin implementations that use the inventory property to store data from the Inventory Service on a player should move the data to PartyPlayer.ext. To do so, add properties to the partyRpcExt.proto file’s ExtPartyPlayer message. For example:

message ExtPartyPlayer {
    ...
    pragma.inventory.ServiceInventoryData inventory = 17;
}

The deprecated properties are scheduled to be removed in Pragma Version 0.3.0.

[Engine] Removal of OpenTelemetry spans and tracing #

As part of our removal of OpenTelemetry spans and tracing, we made the following changes:

• Deprecated CoreConfig.openTelemetryServiceName field
• Removed support for running Pragma Engine with the opentelemetry-javaagent.jar and associated Makefile targets and code
• Deprecated OpenTelemetry tracing context facility’s code and protobuf fields due to thread changes when Kotlin coroutines are resumed from being suspended
• Pragma Engine no longer presents an invalid traceId in the pragma.ExternalResponse and pragma.ExternalResponseJson protos

To prepare for these deprecations, do the following:

• If you defined CoreConfig.openTelmetryServiceName in your pragma-engine config file, remove this field.

• Replace use of the run-with-otel Makefile target with run

• Remove instances of the following:

  • pragma.InternalRequest.tracingContext
  • pragma.InternalNotification.tracingContext
  • pragma.ExternalResponse.traceId
  • pragma.ExternalResponseJson.traceId

The deprecated properties are scheduled to be removed in Pragma Version 0.3.0

[Engine] | Several ServiceErrorFacade functions have been updated with the protobuf short-name associated with the RPC’s Request #

ServiceErrorFacade.badSession, ServiceErrorFacade.internalError, and ServiceErrorFacade.pragmaError contained an invalid traceId. This property has been replaced with the appropriate RPC Request’s protobuf short-name. protoShortName can be obtained using JumpData.getProtoInfoForType(type: Int) to interrogate the returned ProtoInfo.protoShortName field, which then passes in as the first argument to the functions above.

To prepare for this deprecation, replace any use cases of the following functions with the new protoShortName:

The deprecated properties are scheduled to be removed in Pragma Version 0.3.0