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 currentonEndGame()
implementation, and pass it togameInstance.end(extMap)
as theextMap
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
andorderContentExt.proto
files fromplatform/1-protos/proto-exts/src/main/proto/shared/
intoplatform/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
Object | Now located |
---|---|
FPragmaGameInstance class | Pragma/Common/GameInstance/ |
FPragmaGameInstanceCache class | Pragma/Common/GameInstance/ |
FPragmaHostConnectionDetails struc | Pragma/Common/GameInstance/ |
FPragmaParty class | Pragma/Common/Party/ |
FPragmaPartyCache class | Pragma/Common/Party/ |
IPragmaPartyCache classes | Pragma/Common/Party/ |
FPragmaPartyPlayer | Pragma/Common/Party/ |
FPragmaPresence class | Pragma/Common/Presence/ |
IPragmaPresenceCache interface | Pragma/Common/Presence/ |
FPragmaPresenceCache class | Pragma/Common/Presence/ |
FPragmaBan struct | Pragma/Common/Bans/ |
FPragmaBanRecord struct | Pragma/Common/Bans/ |
FPragmaAccountBannedApplicationError class | Pragma/Common/Bans/ |
Unity
Object | New namespace |
---|---|
GameInstance class (Renamed to PragmaGameInstance ) | Pragma.Common.GameInstance |
GameInstanceCache class | Pragma.Common.GameInstance |
PragmaParty class | Pragma.Common.Party |
PragmaPartyCache class | Pragma.Common.Party |
PragmaPartyPlayer class | Pragma.Common.Party |
PragmaPresence | Pragma.Common.Presence |
PresenceCache class | Pragma.Common.Presence |
BasicPresence enum has | Pragma.Common.Presence |
[Multiplayer ] Update config files for enableAbsoluteTimeout and absoluteTimeoutMillis renames
#
Update any config files that define the following GameInstanceServiceConfig
keys:
Original | Rename |
---|---|
enableAbsoluteTimeout (default false) | enableStaleGameInstanceExpiration (default true) |
absoluteTimeoutMillis (default 10 hrs) | staleGameInstanceExpirationMinutes (default 7 days) |
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 forTPragmaResult
, so any instances ofTOptional::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.
original | replacement |
---|---|
PlayerDataProtoTestFactory.kt | PlayerDataCoreTestFactory.kt |
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 newGameInstancePlugin.handleBackendCreateByMatchmakingRequest()
method, which will start the allocation process as soon as a game instance is created out of matchmaking.
- To keep existing behavior, no action is needed.
- Rename any overridden Game Instance Plugin
updateGameInstance()
methods tohandleBackendUpdateRequest()
Game Server Provider Plugin (formerly Game Instance Host Plugin) changes #
If you have a custom implementation of the
GameInstanceHostPlugin
, move functionality to aGameServerProviderPlugin
implementation.- Replace
GameInstanceHostPlugin.findHostForGameInstance()
withGameServerProviderPlugin.startAllocationForGameInstance()
- Replace
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 toGameServerProviderPlugin
.Consider switching to the
LocalProcessGameServerProviderPlugin
if:- You have been using the
FleetService
andLocalProcessFleetPlugin
only for local development - You already use the
GameInstanceHostPlugin
/GameServerProviderPlugin
for non-local deployments
- You have been using the
Ext changes #
In
5-ext/ext-protos/src/main/proto/shared/gameInstanceExt.proto
Rename
ExtUpdateGameInstanceRequest
toExtBackendUpdateRequest
Add a definition for the new
ExtPlayerUpdateRequest
payloadAdd 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 inExtAllocateGameServer
- If you were previously inspecting fields on
In
5-ext/ext-protos/src/main/proto/shared/fleetExt.proto
, deleteExtHostRequest
. Migrate necessary fields toExtAllocateGameServer
.In implementations of the
FleetPlugin
, change anyExtHostRequest
function parameters to useExtAllocateGameServer
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 thepragma.ExternalResponse
andpragma.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 withrun
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
:
Original | Replacement |
---|---|
ServiceErrorFacade.badSession(traceId: UUID, debugMessage: String) | ServiceErrorFacade.badSession(protoShortName: String, debugMessage: String) |
ServiceErrorFacade.internalError(traceId: UUID, requestId: Int) | ServiceErrorFacade.internalError(protoShortName: String, requestId: Int) |
ServiceErrorFacade.pragmaError(traceId: UUID, requestId: Int, pragmaError: PragmaError) | ServiceErrorFacade.pragmaError(protoShortName: String, requestId: Int, pragmaError: PragmaError) |
The deprecated properties are scheduled to be removed in Pragma Version 0.3.0