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. Limit the max number of users in the party (up to 256) and choose whether members need the leader’s approval to join. Assign an optional JSON label to make the party discoverable via party search. Party labels use the same format and query syntax as match labels. Set hidden to true to keep the party out of search results. Hidden parties can’t have a label.

1
2
3
4
5
6
7
8
9

// Create an open party (i.e. no approval needed to join) with 10 max users and a searchable label
// This maximum includes the party leader
var party = await socket.CreatePartyAsync(open: true, hidden: false, maxSize: 10, label: "{\"mode\":\"capture_the_flag\"}");
System.Console.WriteLine("New Party: {0}", party);

// Create a closed, hidden party (i.e. approval needed, not discoverable via search) with 5 max users
// This maximum includes the party leader
var party = await socket.CreatePartyAsync(open: false, hidden: true, maxSize: 5);
System.Console.WriteLine("New Party: {0}", party);

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)")

 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');

 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)

 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)

 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);

1
2
3
4

local open = false
local max_size = 5
local party = socket.party_create(open, max_size)
pprint(party)

 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);

You can create rules on which users can create parties in your game with before hooks using runtime code.

Update party #

Update the party’s label, open status, and hidden flag at any time. Only the party leader can make changes. All party members receive a ReceivedPartyUpdate event when an update occurs.

1
2
3
4
5
6
7
8

// Listen for party update events (all party members)
socket.ReceivedPartyUpdate += update =>
{
    System.Console.WriteLine("Party updated: " + update.PartyId + ", Label: " + update.Label);
};

// Update the party label, open status, and hidden flag (party leader only)
await socket.UpdatePartyAsync("<partyid>", open: true, hidden: false, label: "{\"mode\":\"deathmatch\"}");

Find party #

After creating a new party, make it discoverable through party search or share the party ID directly via Nakama’s social features:

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

1
2
3
4

string partyId = "<partyid>";

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

1
2
3
4

let partyId = "<partyId>"

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

1
2
3
4

const partyId = '<partyId>';

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

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")

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})

1
2
3
4

const partyId = "<partyId>";

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

1
2

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

1
2
3
4

string partyId = "<partyid>";

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

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

Search parties #

Discover open parties by searching their labels. Only parties with hidden: false appear in results. Calling the List API with an empty query returns all non-hidden parties, including those with no label. Party labels are JSON objects that use the same query syntax as match listing.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// List all open parties
var partyList = await client.ListPartiesAsync(session, limit: 10, open: true);
foreach (var party in partyList.Parties)
{
    System.Console.WriteLine("Party: " + party.PartyId + ", Label: " + party.Label);
}

// Filter by label using a query
var filteredList = await client.ListPartiesAsync(session, limit: 10, open: true, query: "+label.mode:capture_the_flag");
foreach (var party in filteredList.Parties)
{
    System.Console.WriteLine("Party: " + party.PartyId + ", Label: " + party.Label);
}

// Paginate through results
if (!string.IsNullOrEmpty(partyList.Cursor))
{
    var nextPage = await client.ListPartiesAsync(session, limit: 10, open: true, cursor: partyList.Cursor);
}

Access the party listing API from server runtime code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local nk = require("nakama")

local limit = 10
local open = true
local show_hidden = false
local query = "+label.mode:capture_the_flag"
local parties, cursor = nk.party_list(limit, open, show_hidden, query)

for _, party in ipairs(parties) do
    nk.logger_info(string.format("Party: %s", party.match_id))
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

limit := 10
open := true
showHidden := false
query := "+label.mode:capture_the_flag"

parties, cursor, err := nk.PartyList(ctx, limit, &open, showHidden, query, "")
if err != nil {
    logger.Error("Error listing parties", zap.Error(err))
    return
}

for _, party := range parties {
    logger.Info("Party: %s, Label: %s", party.PartyId, party.Label)
}

1
2
3
4
5
6
7
8
9

const limit = 10;
const open = true;
const showHidden = false;
const query = "+label.mode:capture_the_flag";
const result = nk.partyList(limit, open, showHidden, query);

result.parties.forEach(party => {
    logger.info("Party: %s, Label: %s", party.partyId, party.label);
});

Use before and after hooks to add custom logic around party listing:

1
2
3
4
5
6
7
8
9

initializer.registerBeforeListParties(async (ctx, logger, nk, payload) => {
    // Modify or validate the listing request before it executes
    return payload;
});

initializer.registerAfterListParties(async (ctx, logger, nk, data, payload) => {
    // Post-process the listing results
    logger.info("Listed %d parties", data.parties?.length ?? 0);
});

To filter by player count, include the current member count in the party label. The party leader must call update party each time a player joins or leaves to keep the label in sync, which lets you pass a range filter like +label.player_count:<10 to return only parties with available slots.

Join party #

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

1
2
3
4
5
6
7

string partyId = "<partyid>";
await socket.JoinPartyAsync(partyId);

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

1
2
3
4
5
6

let partyId = "<partyId>";
try await socket.joinParty(partyId)

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

1
2
3
4
5
6

const partyId = '<partyId>';
await socket.joinParty(partyId);

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

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])

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])

1
2
3
4
5
6

const partyId = "<partyId>";
await socket.joinParty(partyId);

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

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)

1
2
3
4
5
6

string partyId = "<partyid>";
rtClient->joinParty(partyId);

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

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

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>);

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

 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]);

 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")

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

 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>);

 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)

 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>);

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.

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2
3

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

1
2

local party_id = "<party_id>"
socket.party_leave(party_id)

1
2

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

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.

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));
};

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)")
}

 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');
});

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)

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)

 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)
};

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)

 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;
});

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.

1
2
3
4
5
6

socket.ReceivedPartyLeader += newLeader =>
{
    System.Console.WriteLine("new party leader " + newLeader);
};

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

1
2
3
4
5

socket.onPartyLeader = { newLeader in
    print("new party leader \(newLeader)")
}

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

1
2
3
4
5
6
7
8

socket.onPartyLeader.listen((newLeader) {
  print('new party leader $newLeader');
});

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

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)

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)

1
2
3
4
5
6

socket.onpartyleader += (newLeader) =>
{
    console.info("New party leader: ", newLeader);
};

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

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)

 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);
    }
}

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.

1
2

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

1
2

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

1
2

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

1
2

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

1
2

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

1
2

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

1
2

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

1
2

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

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