Pragma Engine 0.1.0 #

June 2024

We have available patches for this release; the latest version with patches is 0.1.4. See the Patches section below for details.

What’s New? #

  • Customize expected errors with Application Errors

    Application errors are a new type of customizable error that represents expected and planned error flows. Unlike existing Pragma Exception and Ext errors (which will now be called Service Errors), application errors are not urgent and don’t necessitate anyone getting paged to fix the error. For example, an application error is now used by the Accounts service to handle cases where banned users attempt to log into their account.

    Each application error can include custom data, and can be authored from protos for your own use in plugins, Player Data Modules, and custom services.

  • Integrating Pragma releases is now easier!

    We’re updating Pragma version numbering to 0.1.0. Going forward, we will now increment the minor version (0.X.0) of Pragma. Patches and fixes will be pushed as patch versions (0.X.1) facilitating easier management and upgrading between minor versions.

    The new versioning system also offers a better way to upgrade to the latest Pragma versions. New release artifacts (git patch files) allow you to apply release changes without managing a long lived “source” branch in your repository. This significantly cuts down on merge conflict problems if you have made any modifications to the engine. Learn more about taking a release in the Update Pragma Engine.

  • Broadcast Notifications to Players

    You can now send notifications to all logged-in players using new operator and service endpoints. For example, you can alert active players of upcoming maintenance, or notify player clients that a new content catalog is available.

See Integrations and Deprecations for Version 0.1.0 for integration notes.

Feature list #

  • [Multiplayer] Easily manage party and game instance features with dedicated APIs for the Unreal SDK. | full note
  • [Multiplayer] Easily manage game instance, friend, and presence features with the new APIs for the Unity SDK. | full note
  • [Multiplayer] Ensure locally cached state is in sync with the Pragma platform using improved caching mechanisms on all player client APIs for the Unreal SDK. | full note
  • [Accounts] Customize which identity providers are visible to other players to avoid exposing personal information. | full note
  • [Accounts] Remove players from their active session and block them from reconnection. | full note
  • [Accounts] Add a full account ban and filter for relevant bans. | full note
  • [Accounts] Display active ban information for banned players attempting to log in. | full note
  • [Engine] Define common, expected, and uncritical errors with Application Errors. | full note
  • [Engine] Broadcast custom notifications to all active players. | full note

Fixes & Improvements #

  • The GameShardId is now auto-populated and is set when a new Server session is started. Previously, any user attempting to call GetPlayerIdentities would only get an error due to the accidental omission of the required GameShardId value.
  • The following endpoints were fixed and no longer error when passing in an empty list: GetPlayerIdentitiesOperatorV1Request, GetPlayerIdentitiesServiceV1Request, and GetPlayerIdentitiesPartnerV1Request. Previously calling GetIdentities with an empty list of player IDs would throw a SQL error instead of returning 0 results.
  • Version 0.0.100 included a bug that broadcast the OnFriendInviteReceived event to the sender when sending a friend invite. As of version 0.1.0, only invitees will receive the OnFriendInviteReceived event.
  • Improved stability and monitoring for the platform’s metric collector. A new Grafana dashboard for the metrics collector, [shard name] - otelcollector is available. Supported in Pragma engine versions 0.0.95 and later.
  • Health checks are now conducted for all ports during platform start and deploy pipelines. Supported in Pragma engine versions 0.0.95 and later. A new version of the protoc-custom-plugins package ( v1.0.36) is now available. Pragma will make use of this new version in this release.

Doc Improvements #

  • [Concepts] Moved the reference section of Player Data Service SDK from Operations to Live Data.
  • [Concepts] Added a new section on Player Data Service APIs to the Operation’s Reference page.
  • [Concepts] Added new sections to the Account Data Overview page with information on all the ways to retrieve social and player identities.
  • [Concepts & Tutorials] Removed concept pages and tutorials for the Inventory service.

New Features #

Multiplayer #

[Multiplayer] Easily manage party and game instance features with dedicated APIs for the Unreal SDK. #

The player client can interact with party and matchmaking functions in the new PartyApi, and game instance functions in the new GameInstanceApi. These new APIs will eventually replace the deprecated GameLoopApi, and improve SDK management and reduce bloat. See the GameLoopApi Migration for Unreal for integration instructions.

[Multiplayer] Easily manage game instance, friend, and presence features with the new APIs for the Unity SDK. #

The new GameInstanceApi, FriendApi, and PresenceApi allow users to easily interact with game instances, friends, and presence functionality via a rich API for the Unity SDK. These APIs include improved caching mechanisms that synchronize data between the player client and platform.

[Multiplayer] Ensure locally cached state is in sync with the Pragma platform using improved caching mechanisms on APIs for the Unreal SDK. #

As of this release, all player client APIs for the Unreal SDK include the Initialize() and ForceSync() functions, which allow users to better determine if their locally cached state is in sync with the Pragma platform See Initialize Presence service in Unreal SDK for integration instructions.

Accounts #

[Accounts] Customize which identity providers are visible to other players to avoid exposing personal information. #

To avoid exposing personal information, you can customize which identity providers are visible to other players using the new visibleToOtherPlayers config value.

  • When set to true, the configured identity provider will appear in the responses for Player session type RPC endpoints that fetch player and social identities.
  • When set to false, the configured identity provider will be filtered out of the response for the same endpoints.

Example:

Steam:
  class: "pragma.account.SteamIdentityProviderPlugin"
  config:
    visibleToOtherPlayers: true

[Accounts] Remove players from their active session and block reconnection. #

The following new endpoints are available for removing and blocking a player’s session:

  • PlayerSessionRpc.BlockPlayerSessionOperatorV1Request
  • PlayerSessionRpc.BlockPlayerSessionPartnerV1Request
  • PlayerSessionRpc.BlockPlayerSessionServiceV1Request

BlockPlayerSession requests require a pragmaId and a duration in milliseconds. The duration is used to determine the length of time a block should be maintained for a given client. The maximum duration of a block is the length of a single session.

See Remove and block players from their active session in the documentation for more details.

[Accounts] Add a full account ban and filter for relevant bans. #

You can now add a full account ban to a player account in the Social Operator Portal.

Unreal SDK has a new Partner call:

Server->BanAccount(PragmaSocialId, DurationInMillis, BanReason, Comment, OnCompleteDelegate)

You can also toggle what type of bans information (revoked, expired, and active) is returned when requesting an account’s ban history. Previously all ban information was returned.

See Bans in the documentation for more details.

[Accounts] Display active ban information for banned players attempting to log in. #

  • The Social Player Portal now displays an Account Banned error page when a player with active bans attempts to log in. This error page can show players their ban information (duration, reason) and is a swappable component under Account.Bans.AccountBannedDisplay.

  • We’ve also introduced a new swappable component under Account.SignIn.IdProviderAuthErrorHandler, which allows for customization of all authentication error displays.

  • In the Pragma SDK, the LogIn result can now be a TypedFailure which can be read as an AccountApplicationError containing information about the player’s active bans.

    Player->Session()->LogIn(EPragma_Account_IdProvider::UNSAFE, "test01",
    FPlayer::FLoggedInDelegate::CreateLambda(
        [this](const TPragmaResult<>& Result)
        {
            if (Result.IsTypedFailure() && Result.GetErrorType() == FPragma_Account_AccountBannedApplicationError::StaticStruct())
            {
                const FPragmaAccountBannedApplicationError ApplicationError = Result.ReadError<FPragma_Account_AccountBannedApplicationError>();
                const TArray<FPragmaBan> ActiveBans = ApplicationError.ActiveBans;
            }
        }));

See the Detect banned error case and perform a social-only login for integration instructions.

Engine #

[Engine] Define common, expected, and uncritical errors with Application Errors. #

ApplicationErrorException is a new class that can be used to throw expected, common, and uncritical errors. For example, if a player is updating their display name but uses too many characters, a customized Account Plugin can throw an Application Error to state that the requested display name is too long. Application errors are not tracked as errors via metrics, so continue to use PragmaException and ExtException for anything critical and trackable.

See also Parse error data for typed failures in the integration notes.

See the updated Custom Errors documentation for more details.

[Engine] Broadcast custom notifications to all active players #

The Player Session service has two new endpoints that allow operators (notifyAllActiveSessionsOperatorV1) and services (notifyAllActiveSessionsServiceV1) to send custom notifications to all logged-in players connected to Pragma.

Example payload:

{
    "requestId": 1,
    "type": "PlayerSessionRpc.NotifyAllActiveSessionsOperatorV1Request",
    "payload": {
        "notification": {
            "type": "PlayerDataNotifications.MyCustomV1Notification",
            "payload": {
                "message": "hello 1"
            }
        }
    }
}

Batch size (notifyAllActiveSessionsBatchSize) and broadcast delay (notifyAllActiveSessionsBatchIntervalMillis) values can be set in the PlayerSessionConfig.

Patches #

For information on updating to the latest Pragma version see Update Pragma Engine.

0.1.1 #

Fixed a bug that caused a crash in the Unreal SDK when failing to connect to the Pragma Engine Backend.

0.1.2 #

Fixed a bug where the GameLoopApi.OnGameInstanceReconnect event for the Unreal SDK would not consistently fire after login.

0.1.3 #

Fixed a bug where matchmaking queues were overloading the metrics pipeline.

0.1.4 #

Fixed a bug that caused a crash in the Unreal SDK when an unexpected Application Error was thrown.


Pragma Engine 0.0.101
Integrations