Pragma Engine 0.0.100

March 2024

What’s New? #

New Bans feature prevents bad actors from logging into your game. #

The new Bans feature allows you to restrict bad actors from receiving a game authentication token. Bad actors can apply to individuals such as those who are cheating or creating a toxic environment for other players. We currently support adding and viewing bans through both the Social Operator Portal and directly from the game server. When an account is banned, the player can receive a ban notification that allows you to remove them from the game. In addition, you can revoke bans and get rid of their effects on an account from the Social Operator Portal. We’re actively working on more exciting bans features that’ll come out in future releases such as time-based bans and ban reasons.

Using the Friends service, you can allow players to block friend invites from specific accounts. Players also have the option to disable all incoming friend invites.

Updated managed service tooling for engine setup and deployment. #

This release includes improvements to managed infrastructure tooling. New default env, database, and bearer token configuration require less manual configuration management. Nodes can be vertically scaled on an individual basis to address bottlenecks in a cost efficient manner. We’ve also added stop, start, force stop, and status commands to shards in Buildkite, and have implemented automatic log rotation and truncation to make enabling debug logging safer.

Contents #

Summaries | Summarized release notes.

Full Notes | Full notes including descriptions and additional details.

Summaries #

Features #

[Multiplayer] Unreal: Players can block friend invites from specific accounts. | full note
[Multiplayer] Unreal: Players can disable all incoming friend invites. | full note
[Accounts] Prevent bad actors from logging into your game with the new Bans feature. | full note
[Accounts] Personal data packages now include ban history by default. | full note
[Accounts] Customize which game data is collected for personal data reports using the Data Rights Game Plugin. | full note
[Accounts] Configure how long you want game shard information to be cached. | full note
[Accounts] Configure the frequency to check for new data requests in the Data Rights Polling service. | full note
[Accounts, Portal] Manage player ban information using the new Bans tab in the Social Operator Portal. | full note
[Accounts, Portal] Customize the data rights package to include game data such as inventory. | full note
[Player Data] Improved the process of reloading content files on engine startup. | full note
[Player Data] You can now add specific business logic to Operations for custom notifications, metrics, telemetry information, and logs. | full note
[Player Data] Improved Player Data Client and Engine data transfer so the Client only receives the necessary amount of player data changes. | full note
[Infra & Tooling] Easily identify unique platform-side loggers with standardized class-based constructors. | full note
[Infra & Tooling] Track issues with third-party services using the new External HTTP requests dashboard. | full note
[Infra & Tooling] New Buildkite pipeline for stopping, starting, and retrieving the status of shards. | full note
[Infra & Tooling] Added automatic log rotation service to safely enable debug logs without filling up disks. | full note
[Infra & Tooling] Managed infrastructure platforms now contain default values to reduce the complexity of managing multiple configuration files for different shards. | full note
[Infra & Tooling] Specify any branch to auto-deploy to any shard for more flexibility with Pragma’s auto-deploy functionality. | full note
[Infra & Tooling] Database users and passwords only need to be defined once using a new default SharedDatabaseConfigServiceConfig. | full note
[Infra & Tooling] Bearer token setup and usage are now automated to make it easier to set up communication between Game and Social backends. | full note
[Infra & Tooling] AWS instance sizes can now be independently scaled per service/group to customize your node sizes to support your game needs. | full note
[Engine] Added missingHeartbeatTimeoutMillis, a configurable session timeout period that can be used to accurately capture and update player presence statuses when disconnects happen. | full note
[Portal] Search by Pragma player ID from the Operator Social and Game Portals. | full note
[Portal] You can now extend the Portal by adding tabs to a page. | full note

Deprecations #

[Player Data] platform | Deprecated addfileToWatch() in the ContentDataNodeService due to new content reloading feature. | full note

Integrations #

[Multiplayer] sdk | Update checks for InviterNotFound and InviteeNotFound to instead check for SocialIdentityNotFound. | full note
[Accounts] platform | Update references of CreateAccountWithUnsafeProviderV2. | full note
[Accounts] portal | If you have a custom Portal overlay on the ViewAccount portlet, you’ll need to adjust your overlay configuration. | full note
[Player Data] platform | Remove any use case of addfileToWatch() from the ContentDataNodeService. | full note
[Player Data] platform | If you’re using the Player Data SDK, rename certain collections and objects. | full note
[Player Data] platform | Update any use case of the Xbox Entitlements Provider Plugin. | full note
[Player Data] sdk | Update any use case of the Unreal player data SDK. | full note
[Infra & Tooling] platform, config | Update logger references to use the new class-based constructors. | full note
[Infra & Tooling] platform | Update DependentJob constructors to include a name field. | full note
[Infra & Tooling] other | If you’re using the “Players in Game Instances per minute[stacked]” Grafana graph, you’ll need to have a new graph deployed. | full note

Bugs and Fixes #

Previously, the partyId field on the GamePlayer object within the Game Instances interface would change when a player changed parties during a game. With version 0.0.100, the GamePlayer object’s partyId remains set to the value of the party the player queued with.
You can no longer invite yourself to be a friend. Doing so will result in a Friend_SelfOperationNotAllowed error. Previously, you could send yourself a friend invite.
Backend services that use the FriendService.SetPresencePartnerV1 function can only modify existing Presence values. Attempting to set a presence that does not exist will result in a PresenceNotFound response. Previously, partner endpoints could create a presence for a user, even if the user was offline. Now, a player has to create a basic presence before the backend services can manipulate the rich presence.
Identity Provider display name changes are now reflected on the Social Identity on first login after they are changed in the AccountPlugin.onAccountLogin method. Previously a user’s name change would not be immediately reflected when logging in for the first time.
The Xbox Entitlements Provider Plugin has been updated to fix a bug that ignored multiple purchases of the same Xbox consumable. This was fixed by using a new modifiedDate field to identify each purchase as unique between multiple purchases of the same consumable. See the related integration note for more information.
Branches with slashes are now handled appropriately. Previously, having a branch with a slash could cause problems with deploying config or content artifacts. This was fixed by replacing slashes with dashes in certain scenarios.
PlayStation Unreal clients can now properly connect to multinode shards with multiple gateways.

Docs #

[New Concepts] New Bans page with the release of the new Bans feature.
[New Concepts] New Account Data Reference page with information on available plugins and data classes associated with account data.
[New Tutorials] New Unreal tutorials for implementing party and matchmaking functionality.
[Updated Concepts] New diagrams have been added to the Key Concepts and Overview pages in Player Data.
[Updated Concepts] Added two new sections on Privacy Rights about enabling game data collection and the Data Rights Game Plugin.
[Updated Concepts] Added an example flow and diagram in the Login Queue section.
[Updated Concepts] Added new section on Social Operator Portal about bans.
[Updated Concepts] Added new section Pragma Account on the Account Data Overview page with information on what makes up a Pragma Account and default display name behavior.
[Updated Concepts] Added Account Plugin page with details on how to retrieve bans.

Full Notes #

Features #

[Multiplayer] Unreal: Players can block friend invites from specific accounts. #

Description: Using the Friend service with Unreal, you can allow players to prevent specific accounts from sending them friend invites.

Details: When a player blocks an account using the FriendApi with the account’s socialId, the account is added to the player’s blocklist, and the account can no longer send friend invites to the blocker. Blocking current friends results in both accounts being removed from each others’ friend list. The FriendApi can also be used to unblock an account or view a blocklist.

See the Friends Tasks documentation for instructions on using the block/unblock accounts feature.

[Multiplayer] Unreal: Players can disable all incoming friend invites. #

Description: Using the Friend service with Unreal, you can allow players to disable all incoming friend invites.

Details: Users can disable or reenable the ability to receive friend invites using the FriendApi. This ability is separate from the blocklist; when friend invites are disabled, no accounts are added to the blocklist. Similarly, no accounts are removed from the blocklist if friend invites are reenabled.

See the Friends Tasks documentation for instructions on using the disable/enable invites feature.

[Accounts] Prevent bad actors from logging into your game with the new Bans feature. #

Description: You can prevent bad actors (cheaters, toxic players) from receiving a game authentication token by issuing a ban on their account. We now offer the following ban features:

Ban an account to restrict a player from logging into your game
View an account’s ban history including revoked and active bans
Revoke a ban and remove its effects on the account This does not currently end the player’s connected session nor invalidate their still-valid authentication token. You can remove a player from the game once they receive their ban notification.

Details: The following are new ban endpoints:

Issue a ban. BanAccount will add a ban for the specified SocialId.
- AccountRpc.BanAccountOperatorV1Request
- AccountRpc.BanAccountServiceV1Request
- AccountRpc.BanAccountPartnerV1Request
View an account’s ban history. GetBansBySocialId will return the historical list of bans for the specified SocialId.
- AccountRpc.GetBansV1Request
- AccountRpc.GetBansBySocialIdOperatorV1Request
- AccountRpc.GetBansBySocialIdPartnerV1Request
- AccountRpc.GetBansBySocialIdServiceV1Request
Revoke a ban. RevokeBanAccount will remove the effects of a ban on the account for the specified banId.
- AccountRpc.RevokeBanAccountOperatorV1Request
- AccountRpc.RevokeBanAccountServiceV1Request
- AccountRpc.RevokeBanAccountPartnerV1Request

When an account is banned, the currently active account will receive a ban notification. The contents of the ban notification can be found in AccountRpc.BanV1Notification.

Bans can be retrieved from the Account Plugin by PragmaAccount::getBans. This returns a list of previously revoked and currently active bans associated with the Pragma Account.

Ban history is deleted on Pragma Account deletion.

Example:

Unreal

Server->Session()->BansApi().BanAccountFromGameShard(
  SocialId, 
  AllGames, 
  Delegate
);

Unity

server.BansApi.BanAccountFromGameShard(
  socialId, 
  allGames, 
  completeDelegate
);

For more information, see the Bans page.

Related notes: See Manage player ban information using the new Bans tab in Social Operator Portal feature note.

[Accounts] Personal data packages now include ban history by default. #

Description: Ban history is now collected as part of the personal data package that is sent to a player.

Details: To comply with GDPR, ban history is included in the data collected for a personal data package. Ban history includes previously revoked and currently active bans for the player.

[Accounts] Customize which game data is collected for personal data reports using the Data Rights Game Plugin. #

Description: The new Data Rights Game Plugin can be used to customize which game data is collected and given to a player in their personal data report.

Details: If you have game data collection enabled, the personal data requests will go through the default Data Rights Game Plugin. This plugin implements the DataRightsGamePlugin and provides a buildPersonalDataReport method. The default plugin will retrieve all information from the various services that provide personal game data (game inventory) and compile them into a report. You can either extend the plugin implementation or write your own custom plugin.

[Accounts] Configure how long you want game shard information to be cached. #

Description: The new configurable game shard cache can be used for fetching game display information and game shard ID resolution.

Details: New configuration class GameShardCacheConfig found in GameShardCacheNodeService. The new configuration property cacheRefreshSeconds is a long used to determine how frequently the GameShardCacheNodeService checks in seconds for changes to game shards and their relevant metadata. This configuration has a minimum value of 1 second and a default value of 10 seconds.

Related notes: See Customize the data rights package to include game data such as inventory feature note.

[Accounts] Configure the frequency to check for new data requests in the Data Rights Polling service. #

Description: The new Data Rights Polling service is used to collect game data for your personal data packages. You can configure how frequently new game data requests are checked for processing the personal data report.

Details: The new configuration property checkRequestsFrequencyInMinutes in the DataRightsPollingServiceConfig is an int used to determine the frequency in minutes to check for new requests to be processed. This configuration has a minimum value of 1 minute and a default value of 10 minutes.

Related notes: See Customize the data rights package to include game data such as inventory feature note.

[Accounts, Portal] Manage player ban information using the new Bans tab in the Social Operator Portal. #

Description: The Social Operator Portal now has a new Bans tab with the bans associated with the player’s account.

Details: You can add, view, and revoke bans on an account in the Social Operator Portal. To view bans information for a player, on their Account overview page click on the Bans tab.

[Accounts, Portal] Customize the data rights package to include game data such as inventory. #

Description: You can now include game data such as inventory in a data rights package sent back to a player. The Data Rights service now also retrieves game data for the account. By default, only social data is collected for the personal data report and game data collection will need to be enabled.

Details: To enable game data collection you’ll need to do the following:

Ensure the Social Backend Partner Client Config, under the game config, has bearerToken set to a valid Partner token for the social backend. If your infrastructure is managed by Pragma this should already be set.
In the Data Rights Polling Service config under the game config, set enabled to true.
In the Data Rights Service config under the social config, set includeGameDataReports to true.

You can view the status of the social and game data being collected in the Social Operator Portal. The overall status of a personal data request is displayed on a player’s Account overview page under the Data Rights tab. To view details on the individual status of the social and game data, click on a personal data request to open the right hand drawer.

See Send players their personal data and Game data configuration for more information.

Related notes: For information on how to customize what game data is collected, see the Customize which game data is collected for personal data reports using the Data Rights Game Plugin feature note.

[Player Data] Improved the process of reloading content files on engine startup. #

Description: The Content Data Node Service now automatically adds all packaged content files to the file watcher for hot-reloading. This makes it easier for reloading newly added content since all packaged content files are now automatically updated on engine startup.

[Player Data] You can now add specific business logic to Operations for custom notifications, metrics, telemetry information, and logs. #

Description: The Context object, utilized by Player Data Operation functions, now contains a helper function called OnSuccess.

Details: The new OnSuccess function allows you to add logic after an Operation has successfully applied updates to the database and SDK cache, as well as before the Response is returned. OnSuccess() is useful for sending out custom notifications to players and adding additional metrics, telemetry information, and logs.

See the Context Reference documentation for further information.

[Player Data] Improved Player Data Client and Engine data transfer so the Client only receives the necessary amount of player data changes. #

Description: We’ve optimized the data flow between Pragma Engine and the Player Data Client for player data updates.

Details: Previously Pragma Engine sent an Entity and all its Components to the client when an Entity was updated. Now Pragma Engine will only send the minimal amount of data needed to update the client side cache.

Related notes: See Update any use case of the Unreal player data SDK integration note.

[Infra & Tooling] Easily identify unique platform-side loggers with standardized class-based constructors. #

Description: To standardize construction of loggers in the platform and guarantee unique names, we’ve changed our logger constructors from a name-based constructor to a class-based constructor that produces loggers named after the fully qualified class name of a given class. This allows you to quickly identify and configure appropriate loggers.

Details: Users will see the names of many platform-side loggers change from a short name (e.g, PartyService) to a fully qualified name (e.g., pragma.party.PartyService).

[Infra & Tooling] Track issues with third-party services using the new External HTTP requests dashboard. #

Description: We’ve built an External HTTP request dashboard that is included in the Grafana tool provided with the Pragma Engine. This dashboard can be used to support detecting and triaging issues communicating with identity providers or entitlement providers.

The new dashboard contains the following graphs:

External HTTP Requests Per Minute
External HTTP Errors Per Minute
Median External HTTP request duration [log scale]
99th percentile External HTTP request duration [log scale]

[Infra & Tooling] New Buildkite pipeline for stopping, starting, and retrieving the status of shards. #

Description: The new pipeline in Buildkite <studio-name>-engine-platform-commands provides quick and easy access to commonly used commands that help manage your single and multi-node shards.

Details: The following commands can run concurrently on all nodes in a given shard:

stop: attempts graceful shutdown of Pragma service
force stop: runs kill -9 on the Pragma service
start: starts the Pragma service
status: prints the disc utilization of each shard, as well as the systemctl status of Pragma, Honeytail, and AppStatus
startup-logs: outputs the first 200 lines of the Pragma service platform logs

[Infra & Tooling] Added automatic log rotation service to safely enable debug logs without filling up disks. #

Description: Managed infrastructure customers now have a log rotation service automatically running on all their EC2 instances. This log rotation service truncates log files exceeding 100MB, which prevents disk space from filling up and causing platform instability.

Details: The log rotation service performs checks every 10 minutes via a systemd timer. This functionality is available as soon as you deploy the platform to your environment.

[Infra & Tooling] Managed infrastructure platforms now contain default values to reduce the complexity of managing multiple configuration files for different shards. #

Description: Managed infrastructure platforms now contain infrastructure-defined defaults for shard env variables. A shard’s <shard>.env file takes precedence over these defaults, meaning if you want different values, you should define them in your env file.

The following values now have defaults:

ENV_CONFIG: comma-separated list of the engine config yamls to load. Defaults to config/common.yml, config/shard/<shardname>.yml.
ENV_MODE: managed infrastructure will be set by Pragma to the correct value ("DEVELOPMENT" or “PRODUCTION”) based on the shard’s intended use.
MAX_MEMORY: default will be set by Pragma based on the type of instance the Pragma process is running on and will be managed for you.

Details:

If you have no entries in your <shard>.env file and you want to use the Pragma defaults, no action is required.
If you have entries in your <shard>.env file and you don’t want to use the Pragma defaults, no action is required.
If you have entries in your <shard>.env file and you want to use the Pragma defaults instead, comment out the above three values from your <shard>.env file.

[Infra & Tooling] Specify any branch to auto-deploy to any shard for more flexibility with Pragma’s auto-deploy functionality. #

Description: Previously, the main branch could be set to automatically deploy to the test shard. With this version, you can request that any branch be automatically deployed to any shard. You can have multiple branches auto-deploy to any specific shard, but you can’t have a branch target multiple shards.

Details: Each branch can only have one associated shard. The deployment will deploy all the appropriate artifacts based on the build, and restart the shard. You can request this feature by opening a customer service request with the branch and shard you want to associate.

[Infra & Tooling] Database users and passwords only need to be defined once using a new default `SharedDatabaseConfigServiceConfig`. #

Description: Managed infrastructure customers can now have the SharedDatabaseConfigServiceConfig configuration defined by default. If you are already using this configuration for custom services, you can still add a default definition in addition.

Once this is defined, you can add a set of identifier schemas to any DAO config and it will handle the user and passwords for you. For each shard you’d like to enable this for, contact your support representative to handle the infrastructure side, and then add the identifier schemas to any DAO config you’d like to use this feature for.

Example: In this example, we add multiple identifier schemas to the database config for the PlayerDataDaoConfig:

PlayerDataDaoConfig:
    databaseConfig:
        identifierSchemas:
            1:
                identifier: "defaultIdentifier"
                schema: "local_game_player_data1"
		    2: 
                identifier: "defaultIdentifier"
                schema: "local_game_player_data2"

[Infra & Tooling] Bearer token setup and usage are now automated to make it easier to set up communication between Game and Social backends. #

Description: You no longer need to generate, encrypt, and store bearer tokens in the SocialBackendPartnerClientConfig.bearerToken config, as this process has now been automated. If you have entries in this bearerToken config, you can delete them and let Pragma’s infrastructure tooling manage creation and configuration of the bearer tokens on the backend. To turn on this feature, contact your support representative.

[Infra & Tooling] AWS instance sizes can now be independently scaled per service/group to customize your node sizes to support your game needs. #

Description: Infra-defined multinode topology can now define an AWS instance type per node group. Previously, multinode topologies required all nodes to operate on the same AWS instance type, like c7i.large. We can now vertically scale specific nodes upon request. For example, if you want to vertically scale your matchmaking node, then you can request Pragma to scale your c7i.large to a c7i.xlarge.

[Engine] Added `missingHeartbeatTimeoutMillis`, a configurable session timeout period that can be used to accurately capture and update player presence statuses when disconnects happen. #

Description: You can now configure a timeout period to expire player sessions based on missed heartbeat calls between players and the platform. This supports more responsive session notifications for when players disconnect.

Details: A new configuration has been added to GamePlayerSessionConfig and SocialPlayerSessionConfig called missingHeartbeatTimeoutMillis with a default of 65 seconds. If a player client doesn’t check in with the PlayerSessionService.HeartbeatV1 endpoint then their session is expired and terminated. The SDK automatically calls the heartbeat endpoint every 30 seconds.

Note that if the platform has GameInstanceServiceConfig.reconnect set to REQUIRED or OPTIONAL, the Game Player Session service keeps the player session active for longer if the player is in a match–this is to allow for reconnecting to an in-progress match. When the match ends, if the player client hasn’t checked in with the PlayerSessionService.HeartbeatV1 endpoint, the session will then be terminated.

[Portal] Search by Pragma player ID from the Operator Social and Game Portals. #

Description: Operators can now search by Pragma playerId from the Operator Social and Game Portals.

Details: The ability to search by Pragma playerId has been added to the PlayerSearchFilter RPC proto. This allows searching for players by Pragma playerId in the following locations:

Social Operator Portal account listing
Game Operator Portal player listing
Bulk operations through the BulkActionOperatorV1Request
GetPragmaAccountOverviewsPartnerV1Request

[Portal] You can now extend the Portal by adding tabs to a page. #

Description: We’ve added builder methods AddTab and updateTab. This allows the extension of the Portal by adding tabs under a page.

Details: Both addTab and updateTab share the same functionality as addPage and updatePage with the following differences:

The created tabs will inherit the title and breadcrumb route of the parent page.
They will inherit the parent page’s subtitle unless another one is specified.

Deprecations #

[Player Data] platform | Deprecated `addfileToWatch()` in the `ContentDataNodeService` due to new content reloading feature. #

Description: Previously, addfileToWatch() was required for manually adding content files to the file watcher for the hot reloading of content. Now that the ContentDataNodeService automatically adds all packaged content files to the file watcher on engine startup, this function now has been deprecated and will be removed next release. Related notes: See Improved the process of reloading content files on engine startup and Remove any use case of addfileToWatch() from the ContentDataNodeService.

Integrations #

[Multiplayer] sdk | Update checks for `InviterNotFound` and `InviteeNotFound` to instead check for `SocialIdentityNotFound`. #

Description: The Friend service errors InviterNotFound and InviteeNotFound have been replaced with SocialIdentityNotFound when a social ID cannot be found for the target player.

Integration steps:

sdk | Any UPragmaFriendApi method delegates checking for InviterNotFound or InviteeNotFound responses should now check for SocialIdentityNotFound instead.

[Accounts] platform | Update references of `CreateAccountWithUnsafeProviderV2`. #

Description: The CreateAccountWithUnsafeProviderV2 endpoint, which is typically used for creating test accounts, has been split into 2 separate endpoints. This endpoint had a flag (skipAuthOrCreate) for controlling whether or not to also create a Pragma Account in addition to a Unsafe Provider account. We’ve split these into two new separate endpoints:

CreateTestAccountsOperatorV2Request
- This endpoint has the same functionality as the old endpoint with skipAuthOrCreate set to false. This will create both Unsafe Provider accounts and the corresponding Pragma Accounts.
CreateTestUnsafeAccountsOnlyOperatorV1Request
- This endpoint has the same functionality as the old endpoint with skipAuthOrCreate set to true. This only creates Unsafe Provider accounts and doesn’t create the corresponding Pragma Accounts.

Integration steps:

platform | Update references of CreateAccountWithUnsafeProviderV2 to use one of the following new endpoints based on your use case:

skipAuthOrCreate set to false

Before

val newAccounts = listOf(
    AccountRpc.CreateUnsafeProviderAccount.newBuilder()
        .setDisplayName(displayName)
        .setId(accountId)
        .build()
)

val request = AccountRpc.CreateAccountWithUnsafeProviderV2Request.newBuilder()
                .addAllNewAccounts(newAccounts)
                .setGameShardId(gameShardId)
                .setSkipAuthenticateOrCreate(false)
                .build(),

After

val newAccounts = listOf(
        AccountRpc.CreateTestAccount.newBuilder()
            .setUnsafeAccount(
                AccountRpc.CreateTestUnsafeAccount.newBuilder()
                    .setDisplayName(displayName)
                    .setId(accountId)
                    .build()
            )
            .setPragmaAccount(
                AccountRpc.CreateTestPragmaAccount.newBuilder()
                    .setIsBanned(false)
                    .build()
            )
            .build()
)

val request =  AccountRpc.CreateTestAccountsOperatorV2Request.newBuilder()
                    .addAllNewAccounts(newAccounts)
                    .setGameShardId(gameShardId)
                    .build()

skipAuthOrCreate set to true

Before

val newAccounts = listOf(
    AccountRpc.CreateUnsafeProviderAccount.newBuilder()
        .setDisplayName(displayName)
        .setId(accountId)
        .build()
)

val request = AccountRpc.CreateAccountWithUnsafeProviderV2Request.newBuilder()
                .addAllNewAccounts(newAccounts)
                .setGameShardId(gameShardId)
                .setSkipAuthenticateOrCreate(true)
                .build(),

After

val newAccounts = listOf(
    AccountRpc.CreateTestUnsafeAccount.newBuilder()
        .setDisplayName(displayName)
        .setId(accountId)
        .build()
)

val request =  AccountRpc.CreateTestUnsafeAccountsOnlyOperatorV1Request.newBuilder()
                    .addAllNewAccounts(newAccounts)
                    .build()

[Accounts] portal | If you have a custom Portal overlay on the `ViewAccount` portlet, you’ll need to adjust your overlay configuration. #

Description: The DataRightsRequest component was moved to a separate page so that it could be under a separate tab section.

Integration steps:

portal | Adjust your overlay configuration to use the updated DataRightsRequest component on the AccountDataRightsPage page.

[Player Data] platform | Remove any use case of `addfileToWatch()` from the `ContentDataNodeService`. #

Description: addfileToWatch() has been deprecated due to new ContentDataNodeService functionality for packaging content files on engine startup.

Integration steps:

platform | Remove any calls made to ContentDataNodeService.addfileToWatch(). This call was usually made in plugins or custom service code.

[Player Data] platform | If you’re using the Player Data SDK, rename certain collections and objects. #

Description: To follow our SDK naming standards, we have renamed select Player Data SDK collections and objects. Any instances of these collections or objects must be updated with the new name.

Integration steps:

platform | Rename any instances of the following collection:
original replacement
PragmaPlayerData::PlayerDataOperationsSubServiceCollection PragmaPlayerData::FPlayerDataOperationsSubServiceCollection
platform | Rename any instances of the following object:
original replacement
PlayerDataSyncError EPlayerDataSyncError

original	replacement
`PragmaPlayerData::PlayerDataOperationsSubServiceCollection`	`PragmaPlayerData::FPlayerDataOperationsSubServiceCollection`

original	replacement
`PlayerDataSyncError`	`EPlayerDataSyncError`

[Player Data] platform | Update any use case of the Xbox Entitlements Provider Plugin. #

Description: New changes have been added to the Xbox Entitlements Provider Plugin and any use case of the plugin must be updated.

Integration steps:

platform | Contact customer support for more details.

[Player Data] sdk | Update any use case of the Unreal player data SDK. #

Description: The FPlayerDataCache now returns Entity as a FPragmaEntity. This was done to reduce the amount of data sent to clients to sync the SDK cache with player data updates. We’ve added the FPragmaEntity type which is used for accessing Entities through the FPlayerDataCache. This new type stores Components in a TMap vs TArray.

Integration steps:

sdk | Update any client code as needed to use the new FPragmaEntity type and its associated structure.

FPragmaEntity has the following properties:

property	description
`FString Name;`	The string `Name` of the `Entity`.
`FString InstanceId;`	The `InstanceId` of the `Entity`.
`TMap<FString, FPragma_PlayerData_ExtComponent> Components;`	New structure for a list of `Components` belonging to the `Entity`.

[Infra & Tooling] platform, config | Update logger references to use the new class-based constructors. #

Description: The string-based constructor in PragmaLoggerFactory has been replaced with a class-based constructor to produce a logger with a fully qualified name.

Integration steps:

platform | Update calls to PragmaLoggerFactory.getLogger(string) to instead call PragmaLoggerFactory.getLogger(KClass) or PragmaLoggerFactory.getLogger(Class).
- Examples:
  original replacement
  PragmaLoggerFactory.getLogger(PartyQueues::class.simpleName!!) PragmaLoggerFactory.getLogger(PartyQueues::class)
  original replacement
  PragmaLoggerFactory.getLogger("hardcodedString") PragmaLoggerFactory.getILoggerFactory().getLogger("hardcodedString

original	replacement
`PragmaLoggerFactory.getLogger(PartyQueues::class.simpleName!!)`	`PragmaLoggerFactory.getLogger(PartyQueues::class)`

original	replacement
`PragmaLoggerFactory.getLogger("hardcodedString")`	`PragmaLoggerFactory.getILoggerFactory().getLogger("hardcodedString`

config | Within the core/logging/loggers configuration, locate any individual logger configuration and ensure that they reference the correct logger name. The following are just two examples of configurations that require changing.

Party service

Before

core:
  logging:
    loggers:
      "PartyService": "DEBUG"

After

core:
  logging:
    loggers:
      "pragma.party.PartyService": "DEBUG"

Token Decoder Node service

Before

core:
  logging:
    loggers:
      "TokenDecoderNodeService": "DEBUG"

After

core:
  logging:
    loggers:
      "pragma.auth.TokenDecoderNodeService": "DEBUG"

[Infra & Tooling] platform | Update `DependentJob` constructors to include a name field. #

Description: The DependentJob class now takes in a name field. This field can uniquely identify the job within logs and metrics if any mutexes within it are locked. Users constructing DependentJobs will need to provide a string name to each job they construct.

Integration steps:

platform | Update all non-compiling code constructing DependentJob() to pass a string name to the constructor. For example, change DependentJob() to DependentJob("Descriptive Name").

[Infra & Tooling] other | If you’re using the “Players in Game Instances per minute[stacked]” Grafana graph, you’ll need to have a new graph deployed. #

Description: The Player in Game Instances graph in Grafana was returning incorrect data. The graph has now been fixed to show the accurate number of how many players are in game at the given moment. Previously, the Grafana graph was incorrectly using the increase function to get the number which should be used for Counters.

Integration steps:

other | Reach out to your Pragma customer success representative to update your Grafana graph.

Pragma Engine 0.0.100

What’s New? #

New Bans feature prevents bad actors from logging into your game. #

New blocking capabilities in the Friend service gives players control over social interactions. #

Updated managed service tooling for engine setup and deployment. #

Contents #

Summaries #

Features #

Deprecations #

Integrations #

Bugs and Fixes #

Docs #

Full Notes #

Features #

[Multiplayer] Unreal: Players can block friend invites from specific accounts. #

[Multiplayer] Unreal: Players can disable all incoming friend invites. #

[Accounts] Prevent bad actors from logging into your game with the new Bans feature. #

[Accounts] Personal data packages now include ban history by default. #

[Accounts] Customize which game data is collected for personal data reports using the Data Rights Game Plugin. #

[Accounts] Configure how long you want game shard information to be cached. #

[Accounts] Configure the frequency to check for new data requests in the Data Rights Polling service. #

[Accounts, Portal] Manage player ban information using the new Bans tab in the Social Operator Portal. #

[Accounts, Portal] Customize the data rights package to include game data such as inventory. #

[Player Data] Improved the process of reloading content files on engine startup. #

[Player Data] You can now add specific business logic to Operations for custom notifications, metrics, telemetry information, and logs. #

[Player Data] Improved Player Data Client and Engine data transfer so the Client only receives the necessary amount of player data changes. #

[Infra & Tooling] Easily identify unique platform-side loggers with standardized class-based constructors. #

[Infra & Tooling] Track issues with third-party services using the new External HTTP requests dashboard. #

[Infra & Tooling] New Buildkite pipeline for stopping, starting, and retrieving the status of shards. #

[Infra & Tooling] Added automatic log rotation service to safely enable debug logs without filling up disks. #

[Infra & Tooling] Managed infrastructure platforms now contain default values to reduce the complexity of managing multiple configuration files for different shards. #

[Infra & Tooling] Specify any branch to auto-deploy to any shard for more flexibility with Pragma’s auto-deploy functionality. #

[Infra & Tooling] Database users and passwords only need to be defined once using a new default SharedDatabaseConfigServiceConfig. #

[Infra & Tooling] Bearer token setup and usage are now automated to make it easier to set up communication between Game and Social backends. #

[Infra & Tooling] AWS instance sizes can now be independently scaled per service/group to customize your node sizes to support your game needs. #

[Engine] Added missingHeartbeatTimeoutMillis, a configurable session timeout period that can be used to accurately capture and update player presence statuses when disconnects happen. #

[Portal] Search by Pragma player ID from the Operator Social and Game Portals. #

[Portal] You can now extend the Portal by adding tabs to a page. #

Deprecations #

[Player Data] platform | Deprecated addfileToWatch() in the ContentDataNodeService due to new content reloading feature. #

Integrations #

[Multiplayer] sdk | Update checks for InviterNotFound and InviteeNotFound to instead check for SocialIdentityNotFound. #

[Accounts] platform | Update references of CreateAccountWithUnsafeProviderV2. #

[Accounts] portal | If you have a custom Portal overlay on the ViewAccount portlet, you’ll need to adjust your overlay configuration. #

[Player Data] platform | Remove any use case of addfileToWatch() from the ContentDataNodeService. #

[Player Data] platform | If you’re using the Player Data SDK, rename certain collections and objects. #

[Player Data] platform | Update any use case of the Xbox Entitlements Provider Plugin. #

[Player Data] sdk | Update any use case of the Unreal player data SDK. #

[Infra & Tooling] platform, config | Update logger references to use the new class-based constructors. #

[Infra & Tooling] platform | Update DependentJob constructors to include a name field. #

[Infra & Tooling] other | If you’re using the “Players in Game Instances per minute[stacked]” Grafana graph, you’ll need to have a new graph deployed. #

Helpful? Yes No

What did you like?

What went wrong?

[Infra & Tooling] Database users and passwords only need to be defined once using a new default `SharedDatabaseConfigServiceConfig`. #

[Engine] Added `missingHeartbeatTimeoutMillis`, a configurable session timeout period that can be used to accurately capture and update player presence statuses when disconnects happen. #

[Player Data] platform | Deprecated `addfileToWatch()` in the `ContentDataNodeService` due to new content reloading feature. #

[Multiplayer] sdk | Update checks for `InviterNotFound` and `InviteeNotFound` to instead check for `SocialIdentityNotFound`. #

[Accounts] platform | Update references of `CreateAccountWithUnsafeProviderV2`. #

[Accounts] portal | If you have a custom Portal overlay on the `ViewAccount` portlet, you’ll need to adjust your overlay configuration. #

[Player Data] platform | Remove any use case of `addfileToWatch()` from the `ContentDataNodeService`. #

[Infra & Tooling] platform | Update `DependentJob` constructors to include a name field. #