Integrations and Deprecations 2025.2.x #

This topic includes integrations and deprecations for Pragma Version 2025.2.0.

Config #

[Engine] New Services #

This release includes new services and databases.

Integration steps:

• Open an infra change request so we can:
  • Ensure your environments include a SocialBackendPartnerClientConfig by default.
• Update your deployed shard configurations or update the common.yml config with new dao configs.

Game Config

game:
    serviceConfigs:
        DynamicConfigDaoNodeServiceConfig:
          databaseConfig:
            identifierSchema:
               identifier: "defaultIdentifier"
              schema: "game_config"
        ContentDataDaoConfig:
          databaseConfig:
            identifierSchema:
              identifier: "defaultIdentifier"
              schema: "game_content"

Social Config

social:
    serviceConfigs:
        DynamicConfigDaoNodeServiceConfig:
          databaseConfig:
            identifierSchema:
               identifier: "defaultIdentifier"
              schema: "social_config"
        ContentDataDaoConfig:
          databaseConfig:
            identifierSchema:
              identifier: "defaultIdentifier"
              schema: "social_content"
        PermissionDaoConfig:
          databaseConfig:
            identifierSchema:
              identifier: "defaultIdentifier"
              schema: "social_permissions_and_roles"              

Will address:

* details: username must be set directly or by a generated database config via an identifier.
* details: password must be set directly or by a generated database config via an identifier.
* details: hostPortSchema must be set directly or by a generated database config via an identifier.
* ERROR pragma.permissions.PermissionSynchronizationService - failed to sync game permissions with social

Pragma CLI #

[Engine] New common config file #

We have added a new common cli config file and you need to update your existing config file to the latest format.

Integration steps:

• Run ./pragma update 2025-2

Will address:

* No common config file found. New projects can create one with 'project init', and existing projects can generate one via 'update 2025-2'

Protos #

[Engine] Game Services RPC proto files require new file option #

Update and add the file option to all rpc proto files that correspond with a game service. This file option ensures that SDK generation can target the appropriate Game or Social backend. This has been enforced for social services so you do not need to update social service rpc files.

Pragma requires each service to have a corresponding proto file that contains its rpc protos. The file name must conform with the pattern <service-name>Rpc.proto or <service-name>ServiceRpc.proto. Look for these files to update.

Integration steps:

• At the file level, add the GAME backend type option to each affected proto file.

option (pragma.backend_type) = GAME;

Will address:

java.lang.IllegalStateException: Failed to run custom plugin: java.lang.Exception: path/to/some/proto-file.proto is missing a backend type.

Plugins #

[Multiplayer] MatchmakingPlugin.getQueueName() #

Integration steps: Implement MatchmakingPlugin.getQueueName()

Return only a category / fixed list of queue names or game modes. Including randomly generated values in the return will result in runaway metrics generation. Each unique return value will create a multiplicative increase in the number of generated data in the metrics database which can result in data loss or delays.

Good example:

    override fun getQueueName(
        extMatchmakingKey: ExtMatchmakingKey
    ): String {
        // game modes represent a fixed list of game modes: 1V1_UNRANKED, 3v3_RANKED, etc.
        return "${extMatchmakingKey.gameMode}"
    }

Bad example - will introduce metrics stability issues:

    override fun getQueueName(
        extMatchmakingKey: ExtMatchmakingKey
    ): String {
        // the number of unique values grows unbounded due to a randomly generated UUID
        return "${extMatchmakingKey.someAutoGeneratedUUID}"
    }

Will address:

... is not abstract and does not implement abstract member public abstract fun getQueueName(extMatchmakingKey: ExtMatchmakingKey): String defined in pragma.matchmaking.MatchmakingPlugin

[Accounts] Removed functions from AccountPlugin #

We have removed the deprecated functions:

• AccountPlugin.onAccountCreated(pragmaAccount: PragmaAccount)
• AccountPlugin.onAccountLogin(pragmaAccount: PragmaAccount)

Integration steps Convert and use:

• AccountPlugin.onAccountCreated(pragmaAccount: PragmaAccount, idProviderAccount: IdProviderAccount)
• AccountPlugin.onAccountLogin(pragmaAccount: PragmaAccount, idProviderAccount: IdProviderAccount)

Will address:

* 'onAccountCreated' overrides nothing
* 'onAccountLogin' overrides nothing

[Accounts] IdentityProviderPlugins must have a ProviderPluginConfig #

To support multi-game we have updated the required interfaces on the IdentityProviderPlugin. If you have implemented this plugin, you will need to update its config type.

Integration steps

• Update the config definition to inherit ProviderPluginConfig or IdentityProviderPluginConfig
• add an override lateinit var config property in the plugin.

Example:

/**
* Config is required to implement `ProviderPluginConfig` 
* which is done through `IdentityProviderPluginConfig`
*/
class SteamAppConfig private constructor(
    type: BackendType
) : IdentityProviderPluginConfig<SteamAppConfig>(type) {
    // ...
}

class SteamIdentityProviderPlugin(
    override val service: Service,
    override val contentDataNodeService: ContentDataNodeService,
    private val httpClient: TimedHttpClient,
    private val logger: Logger,
) : IdentityProviderPlugin, ConfigurablePlugin<SteamAppConfig> {

    
    // required override by the `IdentityProviderPlugin`
    // implemented by the `ConfigurablePlugin`
    override lateinit var config: SteamAppConfig

    //...
}

Will address:

... is not abstract and does not implement abstract member public abstract val config: ProviderPluginConfig<*> defined in pragma.account.IdentityProviderPlugin

[Monitization] OrderProviderPlugins must have a ProviderPluginConfig #

To support multi-game we have updated the required interfaces for order provider plugins. If you have any custom OrderProviderPlugins, you will need to update its config.

Integration steps:

• Update the config definition to inherit ProviderPluginConfig or OrderProviderPluginConfig
• add an override lateinit var config property in the plugin.

Example:

// Config is required to implement `ProviderPluginConfig`
// which is done through the `OrderProviderPluginConfig`
class SteamOrderProviderPluginConfig private constructor(
    type: BackendType
 ) : OrderProviderPluginConfig<SteamOrderProviderPluginConfig>(type) {
    // ...
}

class SteamOrderProviderPlugin(
    override val service: Service,
    override val contentDataNodeService: ContentDataNodeService,
    private val httpClient: TimedHttpClient,
    private val logger: Logger,
    private val timeProxy: TimeProxy,
) : OrderProviderPlugin, ConfigurablePlugin<SteamOrderProviderPluginConfig> {

    // required override by the `OrderProviderPlugin` 
    // implemented by using `ConfigurablePlugin`
    override lateinit var config: SteamOrderProviderPluginConfig
    override suspend fun onConfigChanged(config: SteamOrderProviderPluginConfig) {
        this.config = config
    }
    // ...
}

Will address:

... is not abstract and does not implement abstract member public abstract val config: ProviderPluginConfig<*> defined in pragma.order.OrderProviderPlugin

Interface Changes #

[Engine] DistributedService.run() is now suspend #

Integration steps:

• Add the suspend modifier to all custom distributed services’ run function.
• Update any test code, any test call of run() should be placed in a runBlocking.

Will address:

* 'run' overrides nothing
* Conflicting overloads: public open fun run()
* Suspend function 'run' should be called only from a coroutine or another suspend function

[Engine] ContentDataNodeService.addFileToWatch() has been removed #

All content is automatically added to the file watcher on startup and this is no longer needed.

Integration steps:

• Delete any use of addFileToWatch().

Will address:

* Unresolved reference: addFileToWatch

[Engine] Removed deprecated functions from SocialBackendPartnerClientNodeService #

Removed deprecated:

• SocialBackendPartnerClientNodeService.requestRpcV2
• SocialBackendPartnerClientNodeService.requestRpc
• SocialBackendPartnerClientNodeService.makeSocialRequest

Integration steps: Replace with:

• SocialBackendPartnerClientNodeService.makeSocialRequestV2()

Will address:

* Unresolved reference: requestRpcV2
* Unresolved reference: requestRpc
* Unresolved reference: makeSocialRequest

[Engine] IntAnySerializer.createGeneratedMessageV3 function has been removed #

Removed deprecated:

• IntAnySerializer.createGeneratedMessageV3

Integration steps:

• Replace any use with IntAnySerializer.createMessage()

Will address:

* Unresolved reference: createGeneratedMessageV3

[Player Data] EntityData.get() has been removed #

Removed deprecated:

• EntityData.get()

Integration steps: Replace with:

• PlayerDataSnapshot.getEntityById(instanceId: UUID)

Will address:

* Unresolved reference: get

Removed test helper: nextI() #

Removed deprecated nextI() from the ProtoTestFactory.

Integration steps:

• Pass in 1 for the i param on any test helper that was using a default i.

Will address:

* No value passed for parameter 'i'

Portal #

[Accounts] New Features #

If your project is configured to run a customized project portal, run ./pragma portal package to pick up the new portal features.

Unreal SDK #

[Unreal: MatchApi] MatchApi.GetGameStartData has been removed #

The deprecated MatchApi.GetGameStartData() method has been removed.

Integration steps: Replace with:

• MatchApi.Link Deprecation note.

Will address:

Error C2039 : 'RequestStartGame': is not a member of 'UPragmaMatchApi'

[Unreal: FPragmaError] Removed ErrorCode method #

The deprecated FPragmaError::ErrorCode() method has been removed since this would result in an exception if the failure was due an application error.

Integration steps: Use FPragmaError::ToString() instead.

Will address:

Error C2039 : 'ErrorCode': is not a member of 'FPragmaError'

[Unreal: Multiplayer] Errors Reclassification #

The Multiplayer services (GameInstance, Party, and Matchmaking) have undergone an error audit. These services now throw specific typed application errors when expected ’negative’ outcomes occur to provide consistent error handling across Pragma. These changes include using discrete application error types instead of a general application error and no longer use the PragmaError enums.

Application errors are used for expected ’negative’ outcomes for a Rpc, for example a Party Full error. Application errors are differentiated from service level errors that indicate the request itself failed in an unexpected way, for example a db query operation failing. Application errors provide detailed context for clear error handling and player facing UI, and the separation of Application error types will help differentiate between operations that failed to be processed vs a successfully processed request whose result is a negative case.

See the error classification tables for a complete mapping of removed PragmaError enums and with the new application error types.

If you see EPragma_SdkError::Client_InvalidErrorType in logs, this indicates an Application Error occurred but the handler treated it as a Service Error. Update the handling code to check for an Application Error.

SDK Before:

Player->CreateParty(/* ... */,
    FOnCompleteDelegate::CreateLambda([/* ... */] (TPragmaResult<> Result) {
    if (Result.IsFailure())
    {
      if (Result.Error().Platform() == EPragma_PlatformError::PartyService_AlreadyInParty)
      {
        ...
      }
    }
}));

SDK After:

Player->CreateParty(/* ... */,
  FOnCompleteDelegate::CreateLambda([/* ... */] (TPragmaResult<> Result) {
    // checking for a specific application error occurrence
    if (Result.IsTypedFailure() &&
        Result.GetErrorType() == 
            FPragma_Party_PlayerAlreadyInPartyApplicationError::StaticStruct())
    {
        // typed error includes strongly typed error metadata
        const auto AppError = 
            Result.ReadError<FPragma_Party_PlayerAlreadyInPartyApplicationError>()
        /* ... */
    }

    // Or Convert failure into a string regardless
    // if it's a service error or application error
    if (Result.IsFailure) {
        const auto ErrorString = Result.GetErrorAsString();
    }
}));

Unity SDK #

[Unity: MatchApi] MatchApi.GetGameStartData() has been removed #

The deprecated MatchApi.GetGameStartData() method has been removed.

Integration steps: Replace with:

• MatchApi.Link Deprecation note.

[Unity: Account] Removed deprecated LogIn methods #

The deprecated methods have been removed:

• Pragma.Player.LogIn(IdProvider providerId, string providerToken, Action<Result> onComplete)
• Pragma.Player.LogIn(ExtIdProvider providerId, string providerToken, Action<Result> onComplete)

Integration steps: Replace with:

• Pragma.Player.LogIn(IdProvider providerId, string providerToken, Action<Result<string>> onComplete)
• Pragma.Player.LogIn(ExtIdProvider providerId, string providerToken, Action<Result<string>> onComplete)

[Unity: Multiplayer] Errors Reclassification #

The Multiplayer services (GameInstance, Party, and Matchmaking) have undergone an error audit. These services now throw specific typed application errors when expected ’negative’ outcomes occur to provide consistent error handling across Pragma. These changes include using discrete application error types instead of a general application error and no longer use the PragmaError enums.

Integration steps: Update any reference or check against a removed PragmaError with the new Application Error type.

// result is a Pragma.Result<TPayloadType>
if (result.IsFailure)
{
  // Convert failure into a string regardless if it's a service error or application error
  var errorString = result.ErrorAsString;

  if (result.IsTypedFailure)
  {
    // Add application error handling logic here
    if (result.ErrorType == typeof(UnknownPartyIdApplicationError))
    {
      var appError = result.ReadError<UnknownPartyIdApplicationError>();
      ...
    }
  }
  else
  {
    // Add service error handling logic here
    var serviceError = result.Error;
    ...
  }
}

[Multiplayer] Errors reclassification tables #

Party Service #

Replace any reference of the following PragmaError enums or EPragma_PlatformError with the Application Error Unreal Type

Game Instance Service #

Replace any reference of the following PragmaError enums or EPragma_PlatformError with the Application Error Type

Matchmaking Service #

Replace any reference of the following PragmaError enums or EPragma_PlatformError with the Application Error Type

The following PragmaError enums have been removed #