Integrations and Deprecations 0.5.x #
This topic includes integrations and deprecations for Pragma Version 0.5.0.
Behavioral integrations #
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.
[Multiplayer ] Configure plugin methods if you want to prevent players from joining multiple game instances
#
By default, players are now allowed to join multiple game instances, and enter matchmaking while in a game instance. If you want to preserve pre-0.5.0 behavior and prevent players from joining multiple game instances simultaneously, follow the integration steps below.
Integration steps: When handling create and join requests, do the following:
- Call
GameInstanceApi.getIdsForPlayer()
with the requesting player’s ID. - If the returned list of game instance IDs is not empty (meaning a player is already associated with a game instance), throw an application error to prevent the player’s party from entering matchmaking.
Handling methods where you might want to apply the above include:
Game Instance Plugin:
handleBackendCreateRequest()
handlePlayerCreateRequest()
handleBackendAddPlayersRequest()
handlePlayerJoinRequest()
Party Plugin:
handlePlayerEnterMatchmakingRequest()
[Multiplayer ] Update OnRemovedFromParty SDK event handlers
#
Previously, the Party API OnRemovedFromParty
SDK event was broadcast when a player’s party was shut down by the backend. As of version 0.5.0, PartyApi.OnRemovedFromParty
is broadcast to a player any time they are removed from a party.
Integration steps:
If you are handling the OnRemoveFromParty
event, check the payload to identify the the party the player is being removed from and, if necessary, update how you handle the event.
[Portal ] Update Portal to use LESS variables
#
As part of our upgrade to the ant-design-vue library we are removing the Ant Design CSS variables in favor of LESS variables. The CSS variables were deprecated in version 0.4.0 and are now removed in this version. See the deprecation note in the 0.4.0 release notes for integration instructions.
Syntax integrations #
This section describes changes in naming, file locations, and other syntactical updates.
[Engine ] Check in the updated pom.xml file to your Pragma Engine repository
#
The core engine dependencies have been updated. A new pom.xml file will be generated during the next Pragma Engine build.
[Multiplayer ] Update use of Match API RemovePlayers() and Game Instance Plugin onRemovePlayers()
#
To streamline and standardize removing players from a game instance, we deprecated functionality related to the MatchApi.RemovePlayers()
method, the GameInstancePlugin.onRemovePlayers()
method, and associated exts. If you haven’t already, follow the instructions in the 0.4.0 Update use of Match API RemovePlayers() and Game Instance Plugin onRemovePlayers() deprecation note.
[Multiplayer ] Replace decline reconnect methods and listeners
#
The MatchApi.OnPlayerDeclineReconnect
event and the GameInstanceApi.DeclineReconnect()
method in the SDK for Unreal and Unity were deprecated in version 0.4.0 and have been removed in version 0.5.0. If you haven’t already, follow the instructions in the 0.4.0 deprecation note.
[Multiplayer ] Replace OnAddPlayers listeners with OnPlayersAdded
#
To maintain consistent naming across events, the MatchApi.OnAddPlayers
event in the SDK for Unreal and Unity was deprecated in version 0.4.0 in favor of the MatchApi.OnPlayersAdded
event. Although there is no timeline for removing the OnAddPlayers
event, we recommend you follow the instructions in the 0.4.0 deprecation note.
[Multiplayer ] Update calls to Game Instance API Update() and Leave() methods
#
To support multiple game instances per player, you now have to provide the game instance ID when requesting game instance updates or when issuing player leave requests from the Game Instance API.
Integration steps: Update calls according to the following tables:
Unreal old
GameInstanceApi.Update(
ExtPlayerUpdateRequest RequestExt,
OnCompleteDelegate OnComplete)
GameInstanceApi.Leave(
ExtPlayerLeaveRequest RequestExt,
OnCompleteDelegate OnComplete)
Unreal new
GameInstanceApi.Update(
FString GameInstanceId,
ExtPlayerUpdateRequest RequestExt,
OnCompleteDelegate OnComplete)
GameInstanceApi.Leave(
FString GameInstanceId,
ExtPlayerLeaveRequest RequestExt)
Unity old
GameInstanceApi.Update(
ExtPlayerUpdateRequest requestExt,
CompleteDelegate onComplete)
GameInstanceApi.Leave(
ExtPlayerLeaveRequest requestExt)
Unity new
GameInstanceApi.Update(
PragmaId gameInstanceId,
ExtPlayerUpdateRequest requestExt,
CompleteDelegate onComplete)
GameInstanceApi.Leave(
PragmaId gameInstanceId,
ExtPlayerLeaveRequest requestExt)
[Multiplayer ] Update Game Instance getIdForPlayer() and getForPlayer() calls to account for new return values
#
To support multiple game instances, we updated the following GameInstanceApi backend methods:
getIdForPlayer()
has been renamed togetIdsForPlayer()
and returns a list of game instance IDs for the given player, instead of a single game instance.getForPlayer()
now returns a list of game instance summaries, instead of a single game instance summary.
Integration steps:
Rename references to GameInstanceApi.kt:getIdForPlayer()
with GameInstanceApi.kt:getIdsForPlayer()
.
- Expect a list of game instance IDs from
getIdsForPlayer()
. - Expect a list of GameInstanceSummary objects from
getForPlayer()
.
[Multiplayer ] Update handleBackendCreateRequest() and handleBackendAddPlayersRequest() to use new PlayerToAdd data class
#
To provide the plugins with additional context about the new player being added, we created the PlayerToAdd
data class.
Integration steps: Update the following Game Instance Plugin methods to use the updated playersToAdd parameter:
Old methods:
handleBackendCreateRequest(
gameInstanceSnapshot: GameInstance.GameInstance,
requestExt: ExtBackendCreateRequest,
playersToAdd: Map<PlayerId, ExtBackendAddPlayer>
)
handleBackendAddPlayersRequest(
gameInstanceSnapshot: GameInstance.GameInstance,
requestExt: ExtBackendAddPlayersRequest,
playersToAdd: Map<PlayerId, ExtBackendAddPlayer>
)
Replacements:
handleBackendCreateRequest(
gameInstanceSnapshot: GameInstance.GameInstance,
requestExt: ExtBackendCreateRequest,
playersToAdd: List<PlayerToAdd>
)
handleBackendAddPlayersRequest(
gameInstanceSnapshot: GameInstance.GameInstance,
requestExt: ExtBackendAddPlayersRequest,
playersToAdd: List<PlayerToAdd>
)
[Multiplayer ] Update calls to GameInstanceCache.GetGameInstance()
#
We updated the GameInstanceCache.GetGameInstance()
method and added a new GameInstanceCache.GetFirstGameInstance()
method to support the new multiple game instance feature. If you are using the Game Instance cache in the client SDK for Unreal or Unity, follow these integration steps.
Integration steps:
- If you are allowing players to be in multiple game instances, update
GetGameInstance()
calls to accept a specific game instance ID:GetGameInstance(gameInstanceId)
. - If you do not want to implement the multiple game instance functionality, replace calls to
GetGameInstance()
withGetFirstGameInstance()
. This new method assumes the requesting player only has one associated game instance, and returns that game instance object.
[Multiplayer ] Update calls to the Game Instance API Create() method to accept a GameInstanceIdDelegate
#
To support allowing players to be in multiple game instances at the same time, the GameInstanceApi.Create()
method in the SDK for Unreal and Unity now returns a Result containing a FString
(for Unreal) or PragmaId
(for Unity).
Integration steps:
For Unreal:
- Update any code that invokes
PragmaGameInstanceApi.Create()
to pass aFGameInstanceIdDelegate
instead of anFOnCompleteDelegate
. - Update the new delegate’s argument from
TPragmaResult<>&
toTPragmaResult<FString>&
.
For Unity:
Update any code that invokes GameInstanceApi.Create()
to pass a delegate containing Result<PragmaId>
instead of a Result
.
[Accounts ] Update references of NotFoundApplicationError
#
We’ve moved NotFoundApplicationError
to a shared location. If you are using NotFoundApplicationError
, update imports and usages.
Integration steps:
SDK:
old structure new structure struct FPragma_Account_NotFoundApplicationError;
struct FPragma_NotFoundApplicationError;
platform import:
old import new import import pragma.account.AccountRpc.NotFoundApplicationError
import pragma.NotFoundApplicationError
Deprecations #
[Multiplayer ] handleBackendCreateByMatchmaking(), handleBackendAddPlayersByMatchmakingRequest(), and related ext build methods have been deprecated
#
To simplify and consolidate the game instance flow, we deprecated several Game Instance Plugin and Game Instance object methods and exts.
Integration steps:
Migrate logic from the following deprecated methods to their replacement methods:
Game Instance Plugin methods:
deprecated method replacement method handleBackendCreateByMatchmakingRequest()
handleBackendCreateRequest()
handleBackendAddPlayersByMatchmakingRequest()
handleBackendAddPlayersRequest()
Game Instance ext build methods:
deprecated method replacement method NewGameInstance.setExtGamePlayer()
NewGameInstance.setExtForPlayer()
UpdateGameInstance.setExtGamePlayer()
UpdateGameInstance.setExtForPlayer()
Note: The
setExtForPlayer()
methods were introduced in version 0.4.0.Follow the deprecation notes for migrating game instance and player data to data stores.
The deprecated methods and exts are expected to be removed in version 0.6.0.
[Multiplayer ] MatchmakingGameInstance.teams deprecated in favor of getPlayersByTeamNumber()
#
The teams
property on the Matchmaking Game Instance has been deprecated in favor of the MatchmakingGameInstance.getPlayersByTeamNumber()
method, which returns a map of team number to GamePlayer.
Integration steps:
Replace calls to MatchmakingGameInstance.teams
with MatchmakingGameInstance.getPlayersByTeamNumber()
.
MatchmakingGameInstance.teams
is expected to be removed in version 0.6.0.