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 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 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.

Client
1
2
3
4
5
6
7
8
9
// 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, 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, maxSize: 5);
System.Console.WriteLine("New Party: {0}", party);

Client
1
2
3
4
5
6
7
8
9
// 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)")

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// 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');

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 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)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 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)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// 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);

Client
1
2
3
4
local open = false
local max_size = 5
local party = socket.party_create(open, max_size)
pprint(party)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// 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 snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

You can create rules on which users can create parties in your game with 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 to post the ID as an update, so a player’s subscribers can see them active in a party
In-app notification to the user’s friends list
Guild, 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.

Client
1
2
3
4
string partyId = "<partyid>";

// Set a status update with your party ID
await socket.UpdateStatusAsync("Join my party: ", partyId);

Client
1
2
3
4
let partyId = "<partyId>"

// Set a status update with your party ID
socket.updateStatus("Join my party")

Client
1
2
3
4
const partyId = '<partyId>';

// Set a status update with your party ID
socket.updateStatus('Join my party');

Client
1
2
3
4
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")

Client
1
2
3
4
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})

Client
1
2
3
4
const partyId = "<partyId>";

// Set a status update with your party ID
socket.updateStatus("Join my party: ", partyId);

Client
1
2
local party_id = "<party_id>"
socket.status_update("Join my party: " .. party_id)

Client
1
2
3
4
string partyId = "<partyid>";

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

Code snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

With the party ID, users can then join the party.

Join party #

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

Client
1
2
3
4
5
6
7
string partyId = "<partyid>";
await socket.JoinPartyAsync(partyId);

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

Client
1
2
3
4
5
6
let partyId = "<partyId>";
try await socket.joinParty(partyId)

socket.onPartyPresence = { presence in
    print("Joined party: \(presence.partyID)")
}

Client
1
2
3
4
5
6
const partyId = '<partyId>';
await socket.joinParty(partyId);

socket.onPartyPresence.listen((presence) {
  print('Joined party: ${presence.partyId}');
});

Client
1
2
3
4
5
6
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])

Client
1
2
3
4
5
6
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])

Client
1
2
3
4
5
6
const partyId = "<partyId>";
await socket.joinParty(partyId);

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

Client
1
2
3
4
5
6
local party_id = "<party_id>"
socket.party_join(party_id)

socket.on_party_presence_event(function(presence)
    print("Joined party: " .. party_id)
end)

Client
1
2
3
4
5
6
string partyId = "<partyid>";
rtClient->joinParty(partyId);

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

Code snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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

Client
1
2
3
4
5
6
7
8
9
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>);

Client
1
2
3
4
5
6
7
8
9
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>)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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]);

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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")

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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>)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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>);

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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 snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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.

Client
1
2
3
string partyId = "<partyid>";
var party = await socket.LeavePartyAsync(partyId);
System.Console.WriteLine("Left party: " + party);

Client
1
2
3
let partyId = "<partyId>";
let party = try await socket.leaveParty(partyId: partyId)
debugPrint("Left party: \(party)")

Client
1
2
3
const partyId = '<partyId>';
final party = await socket.leaveParty(partyId);
print('Left party: $party');

Client
1
2
3
var party_id = "<party_id>"
var party: NakamaAsyncResult = yield(socket.leave_party_async(party_id), "completed")
print("Left party: %s" % party)

Client
1
2
3
var party_id = "<party_id>"
var party: NakamaAsyncResult = await socket.leave_party_async(party_id)
print("Left party: %s" % party)

Client
1
2
3
const partyId = "<partyid>";
const party = await socket.leaveParty(partyId);
console.info("Left party: ", partyId);

Client
1
2
local party_id = "<party_id>"
socket.party_leave(party_id)

Client
1
2
string partyId = "<partyid>";
rtClient->leaveParty(partyId);

Code snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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 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.

Client
1
2
3
4
5
6
7
8
// 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));
};

Client
1
2
3
4
5
6
7
// 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)")
}

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// 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');
});

Client
1
2
3
4
5
6
7
8
9
# 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)

Client
1
2
3
4
5
6
7
8
9
# 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)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// 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)
};

Client
1
2
3
4
5
-- Sending the message
local party_id = "<partyId>"
local op_code = 1
local data = { hello =  "world"}
socket.party_data_send(party_id, op_code, data)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// 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 snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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.

Client
1
2
3
4
5
6
socket.ReceivedPartyLeader += newLeader =>
{
    System.Console.WriteLine("new party leader " + newLeader);
};

await socket.PromotePartyMemberAsync("<partyid>", partyMember);

Client
1
2
3
4
5
socket.onPartyLeader = { newLeader in
    print("new party leader \(newLeader)")
}

try await socket.promotePartyMember(partyId: "<partyId>", partyMember: partyMember)

Client
1
2
3
4
5
6
7
8
socket.onPartyLeader.listen((newLeader) {
  print('new party leader $newLeader');
});

await socket.promotePartyMember(
  partyId: '<partyId>',
  newLeader: partyMember,
);

Client
1
2
3
4
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)

Client
1
2
3
4
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)

Client
1
2
3
4
5
6
socket.onpartyleader += (newLeader) =>
{
    console.info("New party leader: ", newLeader);
};

await socket.promotePartyMember("<partyid>", partyMember);

Client
1
2
3
4
5
6
local party_id = "<partyId>"
socket.party_promote(party_id, presence)

socket.on_party_leader(function(event)
    pprint("New party leader:", event.presence)
end)

Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
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 snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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.

Client
1
2
string partyId = "<partyid>";
await socket.ClosePartyAsync(partyId);

Client
1
2
let partyId = "<partyId>";
try await socket.closeParty(partyId: partyId)

Client
1
2
const partyId = '<partyId>';
await socket.closeParty(partyId: partyId);

Client
1
2
var party_id = "<party_id>"
var party: NakamaAsyncResult = yield(socket.close_party_async(party_id), "completed")

Client
1
2
var party_id = "<party_id>"
var party: NakamaAsyncResult = await socket.close_party_async(party_id)

Client
1
2
const partyId = "<partyid>";
await socket.closeParty(partyId);

Client
1
2
local party_id = "<partyId>"
socket.party_close(party_id)

Client
1
2
string partyId = "<partyid>";
rtClient->closeParty(partyId);

Code snippet for this language Java/Android has not been found. Please choose another language to show equivalent examples.

Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.

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 in the game server. This gives you complete control over your multiplayer net code and the logic associated with actions taken by users.

Heroic Cloud

Deploy Nakama and Satori

Company

Powering Gray Zone Warfare to Early Success: MADFINGER Games and Heroic Labs

Halfbrick Studios: Rebuilding and Relaunching Magic Brick Wars

Heroic Labs and Zynga launch Star Wars: Hunters

Documentation

Community

Download and Install Nakama OSS

Learn how to use Nakama