# Parties

**URL:** https://heroiclabs.com/docs/nakama/concepts/parties/
**Summary:** Enable users to form parties and communicate with their members. Any user can create a party and will become the initial party leader. Users can invite other players to join or can mark the party as private so other players must request to join. When all players leave the party it’s gone.
**Keywords:** create party, find party, join party, leave party, rotate party leader, promote party leader, close party
**Categories:** nakama, parties, concepts

---


# Real-time Parties

Real-time parties is a great way to add team play to a game, enabling users to form a party and communicate with party members.

A party is a group of users who’ve gathered together to participate in some kind of gameplay or social gathering. Any user can create a party and will become the initial party leader. Users can invite other players to join or can mark the party as private so other players must request to join. A leader is always required and selected from players who are currently connected when the current leader leaves. When all players leave the party it’s gone.

A very common Nakama-supported use case for parties is to matchmake together in groups. This suits gameplay where users collaborate in squads, or where players compete in team battles. The [matchmaker](../multiplayer/matchmaker/) can be passed a party ID which instructs the matching logic to ensure that enough capacity is reserved to join the match altogether.

Parties differ from the [groups](../groups/) feature because they’re not designed to exist between play sessions when the user goes offline. A party only exists as long as at least one user is in it. You should use groups if you want to create guild systems or other gameplay which should exist as a persistent entity in your game or apps.

## Create party

A party can be created by any user. You can limit the max number of users allowed in the party (up to 256) and whether a party member must wait for approval from the leader before they can join. A party is also created with state which can be modified by the party leader.

{{< code type="client" >}}
```csharp
// Create an open party (i.e. no approval needed to join) with 10 max users
// This maximum includes the party leader
var party = await socket.CreatePartyAsync(open: true, hidden: false, maxSize: 10);
System.Console.WriteLine("New Party: {0}", party);

// Create a closed party (i.e. approval needed to join) with 5 max users
// This maximum includes the party leader
var party = await socket.CreatePartyAsync(open: false, hidden: false, maxSize: 5);
System.Console.WriteLine("New Party: {0}", party);
```
{{< / code >}}

{{< code type="client" >}}
```swift
// Create an open party (i.e. no approval needed to join) with 10 max users
// This maximum includes the party leader
let party = try await socket.createParty(open: true, maxSize: 10)
debugPrint("New Party: \(party)")

// Create a closed party (i.e. approval needed to join) with 5 max users
// This maximum includes the party leader
let party2 = try await socket.createParty(open: false, maxSize: 5)
debugPrint("New Party: \(party2)")
```
{{< / code >}}

{{< code type="client" >}}
```dart
// Create an open party (i.e. no approval needed to join) with 10 max users
// This maximum includes the party leader
final party = await socket.createParty(
  open: true,
  maxSize: 10,
);
print('New Party: $party');

// Create a closed party (i.e. approval needed to join) with 5 max users
// This maximum includes the party leader
final party2 = await socket.createParty(
  open: false,
  maxSize: 5,
);
print('New Party: $party2');
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
# Create an open party (i.e. no approval needed to join) with 10 max users
# This maximum includes the party leader
var open = true
var max_size = 10
var party = yield(socket.create_party_async(open, max_size), "completed")
print("New party: %s" % party)

# Create a closed party (i.e. approval needed to join) with 5 max users
# This maximum includes the party leader
var open = false
var max_size = 5
var party = yield(socket.create_party_async(open, max_size), "completed")
print("New party: %s" % party)
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
# Create an open party (i.e. no approval needed to join) with 10 max users
# This maximum includes the party leader
var open = true
var max_size = 10
var party = await socket.create_party_async(open, max_size)
print("New party: %s" % party)

# Create a closed party (i.e. approval needed to join) with 5 max users
# This maximum includes the party leader
var open = false
var max_size = 5
var party = await socket.create_party_async(open, max_size)
print("New party: %s" % party)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
// Create an open party (i.e. no approval needed to join) with 10 max users
// This maximum includes the party leader
const open = true;
const maxSize = 10;
const party = await socket.createParty(open, maxSize);
console.info("New Party: ", party);

// Create a closed party (i.e. approval needed to join) with 5 max users
// This maximum includes the party leader
const open = false;
const maxSize = 5;
const party = await socket.createParty(open, maxSize);
console.info("New Party: ", party);
```
{{< / code>}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local open = false
local max_size = 5
local party = socket.party_create(open, max_size)
pprint(party)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
// Create an open party (i.e. no approval needed to join) with 10 max users
// This maximum includes the party leader
auto successCallback = [](const NParty& party)
{
    cout << "Successfully created party: " << party.id << endl;
};

auto errorCallback = [](const NRtError& error)
{
    cout << "Error: " << error.message << endl;
};

bool open = true;
int maxPlayers = 10;
rtClient->createParty(open, maxPlayers, successCallback, errorCallback);

// Create a closed party (i.e. approval needed to join) with 5 max users
// This maximum includes the party leader
auto successCallback = [](const NParty& party)
{
    cout << "Successfully created party: " << party.id << endl;
};

auto errorCallback = [](const NRtError& error)
{
    cout << "Error: " << error.message << endl;
};

bool open = false;
int maxPlayers = 5;
rtClient->createParty(open, maxPlayers, successCallback, errorCallback);
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

You can create rules on which users can create parties in your game with [before hooks](../../server-framework/introduction/hooks/#before-hooks) using runtime code.

## Find party

After creating a new party, there’s many ways for the party ID to be shared with other users to enable them to find and join:

- [Status events](../status/) to post the ID as an update, so a player's subscribers can see them active in a party
- [In-app notification](../notifications/) to the user’s [friends](../friends/) list
- [Guild](../groups/), sharing the party ID with all members

The way you combine these features of the server to power your game design can create wonderful social mechanics to bring users together and create a deep and meaningful player community.

{{< code type="client" >}}
```csharp
string partyId = "<partyid>";

// Set a status update with your party ID
await socket.UpdateStatusAsync("Join my party: ", partyId);
```
{{< / code >}}

{{< code type="client" >}}
```swift
let partyId = "<partyId>"

// Set a status update with your party ID
socket.updateStatus("Join my party")
```
{{< / code >}}

{{< code type="client" >}}
```dart
const partyId = '<partyId>';

// Set a status update with your party ID
socket.updateStatus('Join my party');
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var party_id = "<party_id>"

# Set a status update with your party ID
var update : NakamaAsyncResult = yield(socket.update_status_async(JSON.print({"Join my party: %s" % party_id}), "completed")
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var party_id = "<party_id>"

# Set a status update with your party ID
var update : NakamaAsyncResult = await socket.update_status_async(JSON.stringify({"Join my party: %s" % party_id})
```
{{< / code >}}

{{< code type="client" >}}
```javascript
const partyId = "<partyId>";

// Set a status update with your party ID
socket.updateStatus("Join my party: ", partyId);
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<party_id>"
socket.status_update("Join my party: " .. party_id)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
string partyId = "<partyid>";

// Set a status update with your party ID
rtClient->updateStatus("Join my party: " + partyId);
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

With the party ID, users can then [join the party](#join-party).

## Join party

A user must join a party before they can send messages, see the member list, or invite other users.

{{< code type="client" >}}
```csharp
string partyId = "<partyid>";
await socket.JoinPartyAsync(partyId);

socket.ReceivedParty += party =>
{
    System.Console.WriteLine("Joined party: " + party);
};
```
{{< / code >}}

{{< code type="client" >}}
```swift
let partyId = "<partyId>";
try await socket.joinParty(partyId)

socket.onPartyPresence = { presence in
    print("Joined party: \(presence.partyID)")
}
```
{{< / code >}}

{{< code type="client" >}}
```dart
const partyId = '<partyId>';
await socket.joinParty(partyId);

socket.onPartyPresence.listen((presence) {
  print('Joined party: ${presence.partyId}');
});
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var party_id = "<party_id>"

var join: NakamaAsyncResult = yield(socket.join_party_async(party_id), "completed")

func _on_party_presence(p_presence : NakamaRTAPI.PartyPresenceEvent):
    print("Joined party: %s" % [p_presence.party_id])
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var party_id = "<party_id>"

var join: NakamaAsyncResult = await socket.join_party_async(party_id)

func _on_party_presence(p_presence : NakamaRTAPI.PartyPresenceEvent):
    print("Joined party: %s" % [p_presence.party_id])
```
{{< / code >}}

{{< code type="client" >}}
```javascript
const partyId = "<partyId>";
await socket.joinParty(partyId);

socket.onpartypresence = (presence) => {
    console.info("Joined party: ", partyId);
};
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<party_id>"
socket.party_join(party_id)

socket.on_party_presence_event(function(presence)
    print("Joined party: " .. party_id)
end)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
string partyId = "<partyid>";
rtClient->joinParty(partyId);

listener.setPartyPresenceCallback([](const NPartyPresenceEvent& presence) {
    cout << "Joined party: " << presence.partyId << endl;
});
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

If the party is private, users can request to join and the party leader can accept or reject.

{{< code type="client" >}}
```csharp
string partyId = "<partyid>";
// List all existing join requests
var requests = await socket.ListPartyJoinRequestsAsync(partyId);

// Accept a join request
await socket.AcceptPartyMemberAsync(partyId, <userPresence>);

// Reject a join request
await socket.RemovePartyMemberAsync(partyId, <userPresence>);
```
{{< / code >}}

{{< code type="client" >}}
```swift
let partyId = "<partyId>";
// List all existing join requests
let requests = try await socket.listPartyJoinRequests(partyId: partyId)

// Accept a join request
try await socket.acceptPartyMember(partyId: partyId, presence: <userPresence>)

// Reject a join request
try await socket.removePartyMember(partyId: partyId, presence: <userPresence>)
```
{{< / code >}}

{{< code type="client" >}}
```dart
const partyId = '<partyId>';

// List all existing join requests
final requests = await socket.listPartyJoinRequests(partyId);

// Accept a join request
await socket.acceptPartyMember(partyId, requests.presences[0]);

// Reject a join request
await socket.removePartyMember(partyId, requests.presences[0]);
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var party_id = "<party_id>"

# List all existing join requests
var requests: NakamaAsyncResult = yield(socket.list_party_join_requests_async(party_id), "completed")

# Accept a join request
var request: NakamaAsyncResult = yield(socket.accept_party_member_async(party_id, <user_presence>), "completed")

# Reject a join request
var request: NakamaAsyncResult = yield(socket.remove_party_member_async(party_id, <user_presence>), "completed")
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var party_id = "<party_id>"

# List all existing join requests
var requests: NakamaAsyncResult = await socket.list_party_join_requests_async(party_id)

# Accept a join request
var request: NakamaAsyncResult = await socket.accept_party_member_async(party_id, <user_presence>)

# Reject a join request
var request: NakamaAsyncResult = await socket.remove_party_member_async(party_id, <user_presence>)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
const partyId = "<partyid>";

// List all existing join requests
const requests = await socket.listPartyJoinRequests(partyId);

// Accept a join request
await socket.acceptPartyMember(partyId, <userPresence>);

// Reject a join request
await socket.removePartyMember(partyId, <userPresence>);
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<party_id>"

-- List all existing join requests
local requests = socket.party_join_request_list(socket, party_id)

-- Accept a join request
socket.party_accept(party_id, presence)

-- Reject a join request
socket.party_remove(party_id, presence)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
string partyId = "<partyid>";

// List all existing join requests
rtClient->listPartyJoinRequests(partyId);

// Accept a join request
rtClient->acceptPartyMember(partyId, <userPresence>);

// Reject a join request
rtClient->removePartyMember(partyId, <userPresence>);
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

## Leave party

A user can leave a party at any time. The user will also be automatically removed from the party if they disconnect from the server.

{{< code type="client" >}}
```csharp
string partyId = "<partyid>";
var party = await socket.LeavePartyAsync(partyId);
System.Console.WriteLine("Left party: " + party);
```
{{< / code >}}

{{< code type="client" >}}
```swift
let partyId = "<partyId>";
let party = try await socket.leaveParty(partyId: partyId)
debugPrint("Left party: \(party)")
```
{{< / code >}}

{{< code type="client" >}}
```dart
const partyId = '<partyId>';
final party = await socket.leaveParty(partyId);
print('Left party: $party');
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var party_id = "<party_id>"
var party: NakamaAsyncResult = yield(socket.leave_party_async(party_id), "completed")
print("Left party: %s" % party)
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var party_id = "<party_id>"
var party: NakamaAsyncResult = await socket.leave_party_async(party_id)
print("Left party: %s" % party)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
const partyId = "<partyid>";
const party = await socket.leaveParty(partyId);
console.info("Left party: ", partyId);
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<party_id>"
socket.party_leave(party_id)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
string partyId = "<partyid>";
rtClient->leaveParty(partyId);
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

### Party leader rotation

When a user leaves the server will check whether they are the current party leader and, if they were, send a message to indicate the leader has left and which member was promoted as the new party leader.

When an automated promotion happens the leader chosen will always be the user who has been part of the party for the longest since it was created. This is a deterministic process and cannot be changed. See [manual leader promotion](#manual-leader-promotion) if your game needs different criteria to promote a new leader.

## Send messages

Any user who is a party member can send messages to the party containing: text, emotes, or game specific actions.

{{< code type="client" >}}
```csharp
// Sending a message
socket.SendPartyDataAsync(partyId: "<partyid>", opCode: 1, data: System.Text.Encoding.UTF8.GetBytes("{<message>}"));

// Receiving the message
socket.ReceivedPartyData += data =>
{
    System.Console.WriteLine("Received: " + System.Text.Encoding.UTF8.GetString(data));
};
```
{{< / code >}}

{{< code type="client" >}}
```swift
// Sending a message
try await socket.sendPartyData(partyId: "<partyId>", opCode: 1, data: "{<message>}".data(using: .utf8))

// Receiving the message
socket.onPartyData = { data in
    print("Received: \(data)")
}
```
{{< / code >}}

{{< code type="client" >}}
```dart
// Sending a message
await socket.sendPartyData(
  partyId: '<partyId>',
  opCode: Int64(1),
  data: utf8.encode('{<message>}'),
);

// Receiving the message
socket.onPartyData.listen((data) {
  print('Received: $data');
});
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
# Sending the message
var party_id = "<party_id>"
var op_code = 1
var data = "<message>".to_utf8()
var party_message: NakamaAsyncResult = yield(socket.send_party_data_async(party_id, op_code, data), "completed")

# Receiving the message
var message: NakamaAsyncResult = yield(socket.received_party_data(data), "completed)
print("Received: %s" % message)
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
# Sending the message
var party_id = "<party_id>"
var op_code = 1
var data = "<message>".to_utf8()
var party_message: NakamaAsyncResult = await socket.send_party_data_async(party_id, op_code, data)

# Receiving the message
var message: NakamaAsyncResult = await socket.received_party_data(data)
print("Received: %s" % message)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
// Sending the message
const partyId = "<partyId>";
const opCode = 1;
const data = {"hello": "world"};
socket.sendPartyData(partyId, opCode, data);

// Receiving the message
socket.onpartydata = (data) => {
    console.info("Received: ", data)
};
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
-- Sending the message
local party_id = "<partyId>"
local op_code = 1
local data = { hello =  "world"}
socket.party_data_send(party_id, op_code, data)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
// Sending the message
string partyId = "<partyid>";
int32_t opCode = 1;
string data = "{\"hello\":\"world\"}";
rtClient->sendPartyData(partyId, opCode, data);

// Receiving the message
listener.setPartyDataCallback([](const NPartyData& data) {
    std::cout << "Received: " << data.data << std::endl;
});
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

### Manual leader promotion

As well as regular messages the party leader can also send a special promotion message which will declare that they’ve stepped down as the current leader and who they have promoted to the new leader.

{{< code type="client" >}}
```csharp
socket.ReceivedPartyLeader += newLeader =>
{
    System.Console.WriteLine("new party leader " + newLeader);
};

await socket.PromotePartyMemberAsync("<partyid>", partyMember);
```
{{< / code >}}

{{< code type="client" >}}
```swift
socket.onPartyLeader = { newLeader in
    print("new party leader \(newLeader)")
}

try await socket.promotePartyMember(partyId: "<partyId>", partyMember: partyMember)
```
{{< / code >}}

{{< code type="client" >}}
```dart
socket.onPartyLeader.listen((newLeader) {
  print('new party leader $newLeader');
});

await socket.promotePartyMember(
  partyId: '<partyId>',
  newLeader: partyMember,
);
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var new_leader = "<user_id>"
var party_id = "<party_id>"
var leader: NakamaAsyncResult = yield(socket.received_party_leader(party_id, new_leader), "completed)
print("New party leader: %s" % new_leader)
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var new_leader = "<user_id>"
var party_id = "<party_id>"
var leader: NakamaAsyncResult = await socket.received_party_leader(party_id, new_leader)
print("New party leader: %s" % new_leader)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
socket.onpartyleader += (newLeader) =>
{
    console.info("New party leader: ", newLeader);
};

await socket.promotePartyMember("<partyid>", partyMember);
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<partyId>"
socket.party_promote(party_id, presence)

socket.on_party_leader(function(event)
    pprint("New party leader:", event.presence)
end)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
auto successCallback = []()
{
    cout << "Successfully promoted party member" << endl;
};

auto errorCallback = [](const NRtError& error)
{
    cout << "Error: " << error.message << endl;
};

for (NUserPresence presence : party.presences)
{
    if (presence.sessionId != party.leader.sessionId)
    {
        rtClient->promotePartyMember(party.id, presence, successCallback, errorCallback);
    }
}
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

## Close party

A party cannot be closed by any member other than the party leader. The party leader can also eject all party members, which will close the party and clear its state on the server. In most cases it's more useful from a game design perspective to allow the leader to leave.

{{< code type="client" >}}
```csharp
string partyId = "<partyid>";
await socket.ClosePartyAsync(partyId);
```
{{< / code >}}

{{< code type="client" >}}
```swift
let partyId = "<partyId>";
try await socket.closeParty(partyId: partyId)
```
{{< / code >}}

{{< code type="client" >}}
```dart
const partyId = '<partyId>';
await socket.closeParty(partyId: partyId);
``` 
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
var party_id = "<party_id>"
var party: NakamaAsyncResult = yield(socket.close_party_async(party_id), "completed")
```
{{< / code >}}

{{< code type="client" framework="godot4" >}}
```gdscript
var party_id = "<party_id>"
var party: NakamaAsyncResult = await socket.close_party_async(party_id)
```
{{< / code >}}

{{< code type="client" >}}
```javascript
const partyId = "<partyid>";
await socket.closeParty(partyId);
```
{{< / code >}}

{{< code type="client" lang="lua" framework="defold" >}}
```lua
local party_id = "<partyId>"
socket.party_close(party_id)
```
{{< / code >}}

{{< code type="client" >}}
```cpp
string partyId = "<partyid>";
rtClient->closeParty(partyId);
```
{{< / code >}}

{{< missing type="client" lang="java" />}}
{{< missing type="client" lang="shell" />}}
{{< missing type="client" lang="bash" />}}

## Best practices

We recommend you don’t use parties to implement multiplayer game logic or use it for scenarios where the messages sent to the party members is intended to drive gameplay progression. In these cases it’s better to use the [authoritative multiplayer engine](../multiplayer/authoritative/) in the game backend. This gives you complete control over your multiplayer net code and the logic associated with actions taken by users.