Integrations and Deprecations 0.3.x #

This topic includes integrations and deprecations for Pragma Version 0.3.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.

[Engine] Update 5-ext POMs #

Due to recent changes in the Player Data service, POMs in 5-ext must be updated. You must perform this step even if you are not actively using the player data service

• Delete the following two POMs:

  • 5-ext/ext-player-data/pom.xml
  • 5-ext/ext-player-data/player-data-generated-types/pom.xml

• Run make CP_TEMPLATE_POM and verify the two POMs have been updated.

• If you have made custom changes to these POMs, use a git diff tool to merge back your changes.

[Multiplayer] Check your party and game instance timeouts #

Stale party and game instance timers are now based on access time, not creation time. Default expiration time has been lowered from 10080 minutes (seven days) to 1440 minutes (one day). You can adjust this duration using the stalePartyExpirationMinutes or staleGameInstanceExpirationMinutes config value. See Set party expiration and Set game instance expiration for instructions on how to set these values.

Syntax Changes #

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

[Engine] Remove and regenerate load test files #

Because Pragma made changes to load test files in version 0.3.0, you need to regenerate your copies in 5-ext.

1. Remove the 5-ext/load-test-core directory and all files inside it.

2. In the 5-ext/ext/src/main/kotlin/demo/gameinstance/GameFlowGameInstancePlugin.kt file, rename the gameInstance parameter to gameInstanceSnapshot in the following functions:

   • buildExtGameStart()
   • onEndGame()

3. Regenerate the load-test-core directory by running make ext.

[Multiplayer] Migrate from the GameLoopApi to the GameInstanceApi and PartyApi #

The GameLoopApi was deprecated in version 0.1.0 and removed in this version. If you haven’t already done so, migrate from using the GameLoopApi SDK for Unreal to instead use the GameInstanceApi and PartyApi. Instructions for doing so are available in the GameLoopApi Migration for Unreal section of the 0.1.0 integration notes.

[Party] Update usage of existing PartyApi files, functions, and events #

The following files, functions, and events related to the PartyApi were changed to provide better organization and to better support new party functionality.

Files:

Methods:

Events:

See also: Improved party invites for all party members.

[Party] Remove PartyPlayer.Inventory property and related configs #

The Party.PartyPlayer.inventory property was deprecated in release 0.2.0 and removed as of 0.3.0. See the deprecation note for integration instructions.

[Party] Update PartyConfig changes #

The following PartyConfig values have been changed:

• inventoryTagsToInclude was removed. If you are using inventoryTagsToInclude in your PartyPlugin, migrate the value to your plugin’s config block.

• enableLocalGameServerVersions was renamed to enableGameServerVersionDevelopmentOverride. If you are using this config property, update your config file to reference the property by its new name. For example:

  game:
    serviceConfigs:
      PartyConfig:
        enableGameServerVersionDevelopmentOverride: true
  

[Player Data] Update Component definitions in the Player Data service #

Player Data no longer requires a @ComponentOrdering function. Instead, Component definitions require the new @SerializedName(name) annotation.

Integration Steps:

1. Add a new @SerializedName annotation to all defined Component classes. You must provide a unique string identifier for each Component. We recommend using a UUID or UNIX timestamp. For example:

   @SerializedName("88a03c44-4790-4002-97bc-39323e590344")
   data class ExampleComponentData(
       @FieldNumber(1) var stringData: String,
       @FieldNumber(2) var intData: Int
   ): Component
   

2. Add a suppress annotation on your @ComponentOrdering annotated function. For example:

   @Suppress("DEPRECATION", "unused")
   @pragma.playerdata.ComponentOrdering
   

   *You cannot delete this function until you have reset all the Player Data Databases in all enviroments. You do not need to clear out your databases for this integration. Instead, you’re only required to add the supression. After integrating the release into your project, you can clear out your databases and delete this function as a follow up task.

3. Run make skip-tests ext in the platform directory. This make command will generate the following file to replace the ComponentOrdering map: 5-ext/ext-player-data/player-data-generated-types/typesRegistry.

   Once you have committed the typesRegistry file to your Pragma Engine Git repository, you cannot make changes to the Component’s serialized names without dropping all data from your databases in all environments.

See the Live Data task on how to Define a Component for more implementation details.

[Player Data] Update Player Data Component usage via the PragmaSDK #

If you’re actively using the PragmaSDK Player Data service, you’ll need to update how you access Components:

Unreal

We’ve replaced FPragma_PlayerData_ExtComponent with a new type: FPragmaAny. See the example below on how to access Components using this new type.

// example of accessing data from a component from the cache
const auto Store = Player->Session()->PlayerDataService().GetCache().Pin();
const TSharedPtr<FPragmaEntity> InitialEntity = Store->GetUniqueEntityByName("some-entity").Pin();

// Note FPragmaComponent: FPragmaAny
for (TTuple<FString, FPragmaComponent> Component : InitialEntity->Components)
{
    if (Component.Value.Is<FPragma_PlayerData_MigrationTrackerProto>()) {
        const FPragma_PlayerData_MigrationTrackerProto MigrationTrackerComponent =
            Component.Value.ReadValue<FPragma_PlayerData_MigrationTrackerProto>();
        const int32 MigrationCountData = MigrationTrackerComponent.MigrationCount;
    }
} 

Unity

We’ve replaced ExtComponent with PragmaAny. See the example below on how to access Components.

var getFuture = player.PlayerData.Get();
yield return Utils.WithTimeout("Get PlayerData", getFuture);
// filter entity by name
var numEntity = getFuture.Result.Payload.Entities.First(entity => entity.EntityName.Name == "number-data");
// loop over components to filter for wanted components
foreach (var component in numEntity.Components)
{
    if (component.SerializedComponent.Is<NumberDataProto>())
    {
        var numberData = component.SerializedComponent.Read<NumberDataProto>();
    }
}

[Game Instance] Add new ExtData message to 5-ext #

Because we added the ExtData message to the Pragma protos, you need to add an entry for ExtData in your 5-ext/ext-protos/src/main/proto/shared/gameInstanceExt.proto file:

message ExtData {
}

See also: Coordinate post-matchmaking activities with the new Game Instance Data Store.

[Game Instance] Discontinue use of GAME_INSTANCE_ID and ENABLE_GAME_RECONNECT session attributes #

We removed the GAME_INSTANCE_ID and ENABLE_GAME_RECONNECT session attributes. Use the GameInstanceApi OnAddedToGameInstance and OnRemovedFromGameInstance SDK events instead.

[Game Instance] Rename GameInstancePlugin gameInstance parameter #

In the GameInstancePlugin methods, we renamed the gameInstance parameter to gameInstanceSnapshot. This clarifies that you are working with a snapshot of the game instance data. Any changes you make to the game instance aren’t applied until the end of the plugin method.

Update parameter names in your GameInstancePlugin methods from gameInstance to gameInstanceSnapshot.

[Game Server] Update usage of OnGameStartFailed and KeepAliveFailed events #

The OnGameStartFailed and KeepAliveFailed events now return types that better support custom application errors:

• For Unreal, these events now return TPragmaResult<> instead of FPragmaError
• For Unity, these events now return a Result with error data on it instead of an Error type

[Game Server] Update usage of Unity MatchApi Future methods #

The Future() methods in the SDK for Unity now return Results without specific types.

[Engine] Update code to account for removal of OpenTelemetry spans and tracing #

In version 0.2.0, several items were deprecated as part of our removal of OpenTelemetry spans and tracing. These items are removed as of version 0.3.0. For integration instructions, see the 0.2.0 deprecation note.

[Engine] Update code to account for ServiceErrorFacade function changes #

In version 0.2.0, several ServiceErrorFacade functions were deprecated and replaced with functions that use the protoShortName. For integration instructions, see the 0.2.0 deprecation note.

[Engine] Remove and regenerate load test files

Because Pragma made changes to load test files in version 0.3.0, you need to regenerate your copies in 5-ext.

1. Remove the following directories and all files inside them:

   • 5-ext/ext/src/main/kotlin/demo
   • 5-ext/load-test-core

2. Regenerate the demo and load-test-core files by running make ext

Deprecations #

[Party] RespondToInvite deprecated in favor of Accept and Decline methods #

The RespondToInvite() method in the PartyAPI SDK for Unreal and Unity has been deprecated and replaced with specific accept and decline methods. Use PartyApi.AcceptPartyInvite() to accept a party invite, and PartyApi.DeclinePartyInvite() to decline a party invite.

PartyApi.RespondToInvite() is scheduled to be removed in Pragma Version 0.4.0.

[Multiplayer] MatchApi methods no longer expose the raw service delegates #

To conform to the other multiplayer APIs, Unreal and Unity MatchApi methods (with the exception of VerifyPlayer) no longer expose the raw service delegate. Most methods now take a FOnCompleteDelegate with a TPragmaResult<> parameter for Unreal, or CompleteDelegate with a Result parameter for Unity.

Integration steps:

In Unreal SDK references:

• Replace the callback parameter to a delegate of type UPragmaMatchApi::FOnCompleteDelegate for the following methods:

  • ConnectPlayers
  • ConnectMorePlayers
  • UpdateGameInstance
  • RemovePlayers
  • EndGame
  • EnterMatchmaking
  • LeaveMatchmaking

• Replace the callback param to a delegate of type UPragmaMatchApi::FVerifyPlayerDelegate for the following method:

  • VerifyPlayer

In Unity SDK references:

• Replace the callback param to a delegate of type MatchApi.CompleteDelegate for the following methods:

  • ConnectPlayers
  • ConnectMorePlayers
  • UpdateGameInstance
  • RemovePlayers
  • EndGame
  • EnterMatchmaking
  • LeaveMatchmaking

• Replace the callback param to a delegate of type MatchApi.VerifyPlayerDelegate for the following method:

  • VerifyPlayer

Pre-0.3.0 methods will be removed in Pragma Version 0.4.0.