Last Updated: 9/22/2021, 7:52:24 AM

# Party

# Overview

The AccelByte Lobby Service includes Party features to enable multiplayer play. All Party features use WebSocket to ensure smooth communication between players. Players can interact with parties in several ways, including:

  • User Party Info shows players information about their party, including the Party ID, Leader ID, and the list of Party Members.
  • Create Party allows players to create a new party that other players can join.
  • Invite to Party allows players to invite their friends to join their party. Both the inviter and invitee will receive a notification when the invitation is sent.
  • Join Party allows players to join a party that they’ve been invited to join. When the player joins the party the inviter and other party members will be notified.
  • Reject Party Invitation allows players to reject a party invitation. The inviter will be notified that their invitation was rejected.
  • Promote Member as a Party Leader allows players to set another player as the party leader.
  • Kick Party allows party leaders to remove another player from their party.

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage a party in the Admin Portal.

Usage Resource Action
Admin Get All Parties ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read
Admin Get Party Data ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read
Update Party Attributes ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Update
Admin Get User Party Data ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# How It Works

# Create a Party

Players who aren’t already in a party can create one. The sequence diagram below shows how parties are created.

When a player tries to create a party, the SendCreatePartyRequest message is sent to the Lobby service. If the player isn’t already in a party, the request will be successful and the party will be created. If the player is already in a party, the request will return the error PartyCreateResponse(error:11232): PartyCreationAlreadyInParty.

party

# Leave Party

Players can leave parties they don’t want to play in. The sequence diagram below shows what happens when a player leaves a party.

When a player leaves a party, the SendLeavePartyRequest message is sent to the Lobby service. The PartyLeaveNotif and PartyDataUpdateNotif will be sent to the other players in the party, informing them that another player has left. When the last player leaves a party, the party will be disbanded.

party

# Send a Party Invitation and Join a Party

If a player is in a party, they can invite other players to join that party. If the invitee is a member of another party and accepts the invitation, they’ll automatically leave their current party and join the new party. Invitees can either accept or reject the invitation.

# Accept a Party Invitation

The sequence diagram below shows what happens when a player accepts a party invitation.

party

  1. Player 1 sends a party invitation to player 2 by sending a partyInviteRequest through Lobby.
  2. Lobby will send the partyInviteResponse and partyDataUpdateNotif as a response to player 1.
  3. Lobby will send the partyGetInvitedNotif as a party invitation from player 1 to player 2.
  4. Player 2 accepts the party invitation by sending partyJoinRequest to Lobby.
  5. Lobby will send partyJoinResponse and partyDataUpdateNotif to player 2.
  6. Lobby will send partyJoinNotif and partyDataUpdateNotif to player 1.
  7. Player 2 sends a party invitation to player 3 by sending partyInviteRequest through Lobby.
  8. Lobby will send partyInviteResponse and partyDataUpdateNotif as a response to player 2.
  9. Lobby will send partyInviteNotif and partyDataUpdateNotif to another party member. In this case, it is player 1.
  10. Lobby will send the partyGetInvitedNotif as a party invitation from player 2 to player 3.
  11. Player 3 accepts the party invitation by sending partyJoinRequest to Lobby.
  12. Lobby will send partyJoinResponse and partyDataUpdateNotif to player 3.
  13. Lobby will send partyJoinNotif and partyDataUpdateNotif to player 1 and player 2.

# Reject a Party Invitation

The sequence diagram below shows what happens when a player rejects a party invitation.

party

  1. Player 1 sends a party invitation to player 2 by sending partyInviteRequest through Lobby.
  2. Lobby will send partyInviteResponse and partyDataUpdateNotif as a response to player 1.
  3. Lobby will send the partyGetInvitedNotif as a party invitation from player 1 to player 2.
  4. Player 2 accepts the party invitation by sending partyJoinRequest to Lobby.
  5. Lobby will send partyJoinResponse and partyDataUpdateNotif to player 2.
  6. Lobby will send partyJoinNotif and partyDataUpdateNotif to player 1.
  7. Player 2 sends a party invitation to player 3 by sending partyInviteRequest through Lobby.
  8. Lobby will send partyInviteResponse and partyDataUpdateNotif as a response to player 2.
  9. Lobby will send partyInviteNotif and partyDataUpdateNotif to another party member. In this case, it is player 1.
  10. Lobby will send the partyGetInvitedNotif as a party invitation from player 2 to player 3.
  11. Player 3 accepts the party invitation by sending partyRejectRequest to Lobby.
  12. Lobby will send partyRejectResponse to player 3.
  13. Lobby will send partyRejectNotif and partyDataUpdateNotif to player 1 and player 2.

# Kick a Party Member

The party leader can kick another party member from the party. The sequence diagram below shows what happens when a player is kicked from a party.

party

  1. Player 1 kicks player 2 by sending a partyKickRequest message.
  2. Lobby will send partyKickResponse and partyDataUpdateNotif as a response to player 1.
  3. Lobby will send partyKickNotif to player 2
  4. After player 2 kicked from the party, Lobby will send partyKickNotif and partyDataUpdateNotif as well to another party member. In this case, it is player 3.

# Promote a Party Leader

The party leader is able to promote another party member from the party to become the new party leader. Once the new party leader is promoted, the old party leader will be demoted to become a regular party member. The sequence diagram below shows what happens when a party leader promotes another player to be the leader.

party

  1. Player 1 promotes player 2 by sending a partyPromoteLeaderRequest message.
  2. Lobby will send partyPromoteLeaderResponse and partyDataUpdateNotif as a response to player 1.
  3. Lobby will send partyDataUpdateNotif to player 2 that indicates that player 2 is promoted to become the new party leader.
  4. After player 2 is promoted, Lobby will send partyDataUpdateNotif as well to another party member. In this case, it is player 3.

# Invite to Party using the Party Code

A player can invite another player to their party by sending them a valid party code. Each party has its own party code. Only the party leader has the ability to retrieve and change the current party code. The sequence diagram below shows what happens when a player invites another player to a party using the party code.

party

# Party Leader

  • The party leader retrieves the party code by sending a SendPartyGetCodeRequest message. Lobby will return the PartyGetCodeResponse.
  • To change the party code by invalidating the current code and generating a new one, the party leader sends the SendPartyGenerateCodeRequest message. Lobby will return the PartyGetCodeResponse.

# Party Member

  • A party member tries to retrieve the party code by sending a SendPartyGetCodeRequest message. Lobby will return the PartyGetCodeResponse(error:11394).
  • Another party member tries to change the party code by sending a SendPartyGenerateCodeRequest message. Lobby will return the PartyGenerateCodeResponse(error:11394).

# Join a Party using the Party Code

Players who aren’t already in a party can join a party if they have its party code. If the player is already in a party, they will have to leave their old party before joining a new one. The sequence diagram below shows what happens when a player joins a party using a party code.

party

# In a Party

  1. A player joins the party via party code by sending SendPartyJoinViaCodeRequest with the party code as a parameter.
  2. Because the player is already in a party, Lobby sends the PartyJoinViaCodeResponse(error:11574).
  3. The player leaves their old party by following the flow in the Leave Party section. After leaving their party, the flow will proceed as it did if the user didn’t have a party..

# Not in a Party

  1. A player joins the party via party code by sending SendPartyJoinViaCodeRequest with the party code as a parameter.
  2. Lobby will send the partyJoinViaCodeResponse as a response to the player.
  3. Lobby will send the PartyJoinNotif and PartyDataUpdateNotif to other party members.

# Party Storage

Game Client needs to be able to store party properties such as Party ID and Party Member in a JSON form. Lobby service will collect the party properties, and game servers will write custom attributes based on the needs. See the diagram below to know how party storage works.

party

# Implementing Parties using the SDK

# Create a Party

Players can create a party that can be used for matchmaking. A player can only create one party at a time, and will become the leader of the party they create.

# Invite to Party

Players can invite other players to their party, as long as the invited player is not already in a party. Party invitees will receive a notification that they have been invited to join a party and current party members will also receive a notification that someone has been invited to the party. Party invitees are identified by the inviteeUserId parameter in the Unity SDK and by inviteePlayerId in the UE4 SDK.

# Join a Party

Players that are invited to a party can accept the invitation and join the party. Party invitees will receive a notification that they’ve joined the party and current party members will also receive a notification that someone is joining the party. The party is identified by the partyID parameter and the invitation by the invitationToken parameter.

# Reject a Party Invitation

When a player has been invited to a party, they can choose to reject the invitation. Party invitees will receive a notification that they’ve rejected the invitation and current party members will also receive a notification that someone has rejected the party invitation. The party is identified by the partyID parameter and the invitation by the invitationToken parameter.

# Promote a Member as the Party Leader

The party leader can promote another party member to become the new party leader. All party members will be notified of the new party leader. The new party leader is identified by the memberUserId parameter.

# Kick Players From a Party

The party leader has the privilege to remove a party member from their party by kicking them out of the party. Kicked party member will receive a notification that they’ve been kicked out of the party, and current party members will also receive a notification that someone has been kicked from the party. The kicked party member is identified by the memberUserId parameter in Unity and by KickPlayerId in UE4.

# Leave a Party

Party members can choose to leave their party. If the party leader leaves the party, party leadership will be passed to another party member automatically. Party members that leave the party will receive a notification that they’ve left the party and current party members will also receive a notification that someone is leaving the party.

# Party Storage

Party Storage enables a party to store party attributes that can be passed from the game server to the game client. The game server will write the party’s storage to ensure that all party members get the same information or notification from the server.

# Party Data Update Notification

Use this function to notify players of any updates to party data. Party members will be notified if an event occurs in the party, such as when a player accepts a party invitation, joins the party, or leaves the party.

# Get Party Data (Client-Side)

Use this function to retrieve specific party data from the client side. Make sure you have players logged in to allow this API call.

# Get Party Data (Server-Side)

Use this function to retrieve specific party data from the server side. Make sure the game server is authenticated to allow this API call.

# Retrieve Active Parties

This function will retrieve active parties from the game server side. The game server must be authenticated to allow this API call.There are two types of functions you can use to retrieve active parties:

In the first function, you can define the limit and offset in the beginning.

In the second function, you can retrieve the active party on the next page using the previous pagination.

# Write Party Data

Write Party Data is an exclusive feature for the game server. In writing party data, it can occur that multiple servers write to the same party at the same time. To avoid this, our SDK has a timestamp in the backend to ensure that the latest write data will never be overwritten with older data.

# Managing Party using the API

You can also use our API endpoints to manage parties.

# Get All-Party Data in a Namespace

You can get all-party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get All Parties: GET - /lobby/v1/admin/party/namespaces/{namespace}/parties endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the desired values into the Offset and Limit fields if you want the results to be paginated.

Upon a successful request, the party data will be retrieved. Here is the response example of the successful request:

# Get Party Data

You can get specific party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get Party Data: GET - /lobby/v1/admin/party/namespaces/{namespace}/parties/{partyId} endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the Party ID.

Upon a successful request, the party data will be retrieved. Here is the response example of the successful request:

# Update Party Attributes

You can update party attributes using the API. To do so, follow steps below:

  1. Use the Update Party Attributes: PUT - /lobby/v1/public/party/namespaces/{namespace}/parties/{partyId}/attributes endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the Party ID.
  4. Fill out the Response Body:
    • Input the Custom Attribute with the attributes you want to update.

Upon a successful request, the party attributes will be updated. Here is the response example of the successful request:

# Get User Party Data

You can get specific party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get User Party Data: GET - /lobby/v1/admin/party/namespaces/{namespace}/users/{userId}/party endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the User ID of the user you want to get the party data.

Upon a successful request, the party data of the user will be retrieved. Here is the response example of the successful request:

  • Learn about our Chat service, which let’s party members interact with each other.
  • Check out our Matchmaking guide to see how parties can be matched to play against each other.
  • Players can form parties with their friends if you integrate our Friends service into your game.