Skip to main content

Groups

A group is a registry of client connections used to send a message to all members at once. Groups are typically called "rooms" and they organise players based on certain criteria — a lobby chat, a game session, a clan, and so on.

A user can join and leave a group on request. The server handler can decide whether joining or leaving is allowed. Both client and server can subscribe to events to track presence in the group.

info

Join, Leave, and Close are not unconditional. The server can accept or reject each request.

SDK components used by groups​

Groups build on three SDK components:

Group use cases​

Groups are flexible enough to cover a wide range of multiplayer scenarios — matchmaking, game sessions, clans, leaderboards, chat, marketing broadcasts, and more.

Create a group​

PlayServ lets you decide whether a group exists as a single shared instance or as multiple independent instances.

Use a singleton group when you need one shared room identified only by its name:

PlayServ.Group("Game");

Use multiple instances when you need several rooms of the same type, each identified by a unique group_id:

PlayServ.Group("GameSession", group_id);

Both syntaxes work for all examples below.

Close a group​

Closing a group dismisses all participants.

Client:

PlayServ.Group("Game").Close();

Server handling:

PlayServ.Server.Group("Game")
  .DoClose(user => {
    ...
    return true;  // allow group closing
    return false; // reject
  });

Multiple instance version:

PlayServ.Server.Group("Game", group_id)
  .DoClose(user => { ... });
warning

If a group is closed, no per-user leave events will be sent for each participant. Use Closed for group-level teardown — see Signalling group lifecycle below.

User joining a group​

Join is a special RPC method. The server decides whether to accept or reject the request.

Client:

await PlayServ.Group("Game").Join();

Server handling:

PlayServ.Server.Group("Game")
  .DoJoin(user => {
    ...
    return true;  // accept the user into the group
    return false; // reject the user
  });
warning

If the server rejects the request, the client will receive JoinRejected. See Signalling users joining and leaving a group.

User leaving a group​

Leave is a special RPC method. The server can also reject a leave request.

Client:

await PlayServ.Group("Game").Leave();

Server handling:

PlayServ.Server.Group("Game")
  .DoLeave(user => {
    ...
    return true;  // allow the user to leave
    return false; // reject
  });

Get group members​

Retrieve all group members using the Data Model API:

var gameGroup = PlayServ.Group("Game");
var members = gameGroup.GetMembers();
// or
var members = gameGroup.Model<Members>();

Subscribe to changes in the member list:

members.Listen();
members.Wait<Update>(e => { ... });
members.Stop();
note

Membership tracking is a data-model subscription — you receive incremental updates the same way as in other subscribed models. See Data Subscriptions & Live Updates for how Listen, Wait<Update>, and Stop behave.

Group events​

Group events use the standard Events API.

Subscribe to a specific event:

PlayServ.Group("Game")
  .Wait<Joined>(event => {
    ...
  });

Subscribe to all events:

PlayServ.Group("Game")
  .Wait(event => {
    ...
  });

Send a custom event to the group — all members receive it except the sender:

PlayServ.Group("Game")
  .SendChatMessage("hello", 1);  // sugar
warning

Group messages are broadcast to members excluding the sender.

Signalling group lifecycle​

Closed — the group was closed. Leave events for each participant will not be sent.

warning

Do not rely on Left or SomeoneLeft to clean up when a group is closed. Use Closed for group-level teardown.

Signalling users joining and leaving a group​

EventDescription
JoinedThe current user successfully joined the group.
JoinRejectedThe server rejected the join request for the current user.
LeftThe current user left the group.
SomeoneJoined(user)Another user joined the group.
SomeoneLeft(user)Another user left the group.

Custom RPC methods​

You can extend a group with your own RPC methods to add game-specific functionality. Custom methods follow the same handler pattern used across RPC extensions — returning false aborts the pipeline.

Server:

PlayServ.Server.Group("Game")
  .DoSomething(param => {
    return false; // abort pipeline
  });

Client:

await PlayServ.Group("Game").DoSomething(stuff);

For the full handler and pipeline mechanics, see Extending SDK Components.

Next step​

For related topics: