Create and Join Parties #
This topic provides instructions on how to create new parties and join existing parties.
A player can only be in one party at a time. If a player is in a party when they attempt to make a new party, the player is removed from the existing party.
Create party from the player client #
Create and join a new party
Using the Party API for Unreal or Unity, call CreateParty()
with the following data:
ExtCreateRequest
: Use this payload to specify custom party data that the platform needs to know when a party is being created. For example, you may want the user to select their preferred game mode. This data will be stored on theExtParty
payload.ExtPlayerJoinRequest
: Use this payload to specify custom player data, such as a selected champion, to pass to theonAddPlayer()
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payload.preferredGameServerZones
:(optional) preferred game server zones. You can change this value later (seeSetPartyPreferredGameServerZones
).gameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).
Player->PartyApi().CreateParty(
FPragma_Party_ExtCreateRequest& ExtCreateRequest,
FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
TArray<FString>& PreferredGameServerZones,
TMap<FString, int32>& GameServerZoneToPing,
FOnCompleteDelegate& OnComplete
);
player.PartyApi.CreateParty(
ExtCreateRequest extCreateRequest,
ExtPlayerJoinRequest extPlayerJoinRequest,
List<string> preferredGameServerZones,
Dictionary<string, int> gameServerZoneToPing,
CompleteDelegate onComplete
);
{
"requestId": 1,
"type": "PartyRpc.CreateV1Request",
"payload": {
"createRequestExt":{},
"playerJoinRequestExt":{},
"gameClientVersion":"gameClientVersion1",
"preferredGameServerZones": [ "gameServerZone1", "gameServerZone2" ],
"gameServerZoneToPing": { "gameServerZone1": 10, "gameServerZone2": 20 }
}
}
After issuing CreateParty()
, the Party service creates a new party and uses data in ExtCreateRequest
to customize the initial party state.
The player that created the party is added and assigned the leader role, and the Party Plugin onAddPlayer()
method is invoked to apply player customization options. See handle added players.
Join a party by invite code #
Use a party’s invite code to join the party
A user can join an existing party by providing a valid invite code. For example, a player may want to join a party with an invite code they received from a player via Discord.
After an invite code is obtained, the player client calls JoinPartyWithInviteCode()
, which accepts the following information:
ExtPlayerJoinRequest
: Use this payload to specify custom player data, such as a selected champion, to pass to theonAddPlayer()
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payloadinviteCode
: invite code obtained by the player joining the partygameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).
Player->PartyApi().JoinPartyWithInviteCode(
const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
const FString& InviteCode,
const TMap<FString, int>& GameServerZoneToPing,
const FOnCompleteDelegate& OnComplete
);
player.PartyApi.JoinPartyWithInviteCode(
ExtPlayerJoinRequest extPlayerJoinRequest,
string inviteCode,
Dictionary<string, int> gameServerZoneToPing,
CompleteDelegate onComplete
);
{
"requestId": 4,
"type": "PartyRpc.JoinWithInviteCodeV1Request",
"payload": {
"requestExt":{},
"inviteCode":"CDCLGP",
"gameClientVersion":"gameClientVersion1"
}
}
Party invite codes are case sensitive. Ensure the code you issue in the join request uses the same capitalization as the invite code generator. The Pragma Engine default code generator uses a combination of numbers and capital letters. Inconsistent capitalization could lead to routing errors.
When a player calls JoinPartyWithInviteCode()
, the Party service adds the player to the party and invokes the Party Plugin onAddPlayer()
method. See handle added players.
Join a party by party ID #
Use a party’s ID to join to party
A user can join an existing party by providing a valid party ID. This could happen if you want a player to be able to join a party by right-clicking on another player to join their party without an invite.
To join by party ID, the player client calls the Party API JoinPartyWithId()
method, which accepts the following information:
ExtPlayerJoinRequest
: Use this payload to specify custom player data, such as a selected champion, to pass to theonAddPlayer()
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payloadpartyId
: party ID of the party the player is attempting to joingameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).
Player->PartyApi().JoinPartyWithId(
const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
const FString& PartyId,
const TMap<FString, int>& GameServerZoneToPing,
const FOnCompleteDelegate& Delegate
);
player.PartyApi.JoinPartyWithId(
ExtPlayerJoinRequest extPlayerJoinRequest,
PragmaId partyId,
Dictionary<string, int> gameServerZoneToPing,
CompleteDelegate onComplete
);
{
"requestId": 5,
"type": "PartyRpc.JoinWithPartyIdV1Request",
"payload": {
"requestExt":{},
"partyId":"5e359a34-8112-4a84-81d5-86f11f261f67",
"gameClientVersion":"gameClientVersion1"
}
}
When a player calls JoinPartyWithId()
, the Party service adds the player to the party and invokes the Party Plugin onAddPlayer()
method. See handle added players.
Handle added players #
Update party player data when player joins a party
When a player is added to a party, the Party Plugin onAddPlayer()
method is invoked with the ExtPlayerJoinRequest
. Customize this method to set player object data.
In our example, onAddPlayer()
takes character selections from ExtPlayerJoinRequest
and puts it on the party player’s ext (ExtPartyPlayer
).
override suspend fun onAddPlayer(
requestExt: ExtPlayerJoinRequest,
playerToAdd: Party.PartyPlayer,
party: Party.Party,
partyConfig: PartyConfig,
) {
playerToAdd.ext.selectedCharacter = requestExt.requestedCharacter
//...
}
Related events and errors #
Related events:
- OnJoinedParty
- OnPartyUpdated
- OnPlayerJoinedParty
- OnExtBroadcastPartyChanged
- OnExtPrivatePlayerChanged
- OnPartyPreferredGameServerZonesChanged
- OnPartyPlayersChanged
Related errors:
- PartyService_AlreadyInParty
- PartyService_NotInParty
- PartyService_PlayerNotLeader
- PartyService_PlayerNotFound