Welcome! This guide will teach you how to add a multiplayer lobby to your game. We’ll cover the basics step-by-step, assuming you’ve never built a lobby before. This guide explains the concepts in a general way that applies to any game engine. For concrete code, see the engine-specific examples at the end.

​
1. What is a Lobby System?

Think of a lobby as a virtual waiting room where players can group up before a game starts. It’s the screen where you invite your friends and wait for everyone to be ready before jumping into the action. Why use a lobby system?
  • Let players connect: It’s the easiest way for players to form parties or teams.
  • Manage game setup: Players can choose characters, teams, or game settings.
  • Launch a match: When everyone is ready, the lobby system can automatically start a game server for the players.
Here is a simple visual of the process:

​
2. The Lobby Lifecycle

A lobby has a simple lifecycle. It starts in a Waiting state and moves to an In-Game state when the match begins.
  • Waiting: The default state. Players can join, leave, and prepare for the game.
  • In-Game: The match is active. The lobby is usually locked, and a game server is running.

​
3. Managing Your Lobby

Here are the basic actions you can perform to manage a lobby.

​
Creating a Lobby

One player, the Host, creates the lobby. To do this, you’ll call a create_lobby function from the SDK. You typically need to provide a few key pieces of information:
  • Name: A public name for the lobby, like “My Awesome Game”.
  • Max Players: The total number of players allowed (e.g., 4).
  • Privacy: Whether the lobby is public (discoverable by anyone) or private (requires an invite code).

​
Joining a Lobby

Other players can join a public lobby using its unique ID or a private lobby using its secret invite code.

​
Leaving & Deleting

Any player can leave a lobby. If the host leaves, another player is automatically made the new host. Only the current host can delete the lobby for everyone.

​
4. Storing Information

You can store two kinds of information: data about the lobby itself, and data for each specific player.

​
Lobby Data (Public Info)

This is information about the game session that applies to everyone, like the selected map or game mode. The host is usually the one who sets this data by calling an update_lobby function.

​
Player Data (Per-Player Info)

This is information specific to each player, like their ready status, character, or team. Every player can update their own data. Additionally, the lobby host has the special ability to update data for any player in the lobby (for example, to assign teams).

​
5. Finding a Game

​
The Lobby List

You can get a list of all public lobbies to create a server browser. It’s best to apply filters to this search, such as only showing lobbies for a specific game mode or lobbies that are not full.

​
Matchmaking

Instead of having players pick from a list, you can use matchmaking to automatically find a good game for them. The flow is simple:
  1. A player creates a lobby (even for just themself).
  2. They set their matchmaking data (like skill level or region) using the update_player_data function.
  3. They call a find_match function.
  4. The system then finds other lobbies that are also searching and have similar data.

​
6. Handling Updates with Events

Lobbies change constantly. Your game needs to react when players join, leave, or change their status. The SDK uses events (also known as callbacks or listeners) to tell your game when something important happens. Key Events to Listen For:
  • OnLobbyUpdated: Fires when any data in the lobby changes. Use this to refresh your UI.
  • OnPlayerJoined: Fires when a new player enters the lobby.
  • OnPlayerLeft: Fires when a player leaves.
  • OnMatchStarted: Fires when the host starts the match and the game server is ready with connection info.

​
7. Tips and Best Practices

  • Securing Private Lobbies: When you create a private lobby, it’s automatically hidden from the public lobby list. The only way to join is with the secret invite_code that is generated. Share this code among friends.
  • Handling Many Lobbies: If your game is popular, always use filters when searching for lobbies. Fetching a list of thousands of lobbies can be slow. Filter by region or game mode first.

​
Next Steps

Now that you understand the core concepts, you’re ready to start building. Dive into our engine-specific guides for code examples and step-by-step instructions.

Unity Quick Start

Implement your first lobby in Unity with a 5-minute guide.

Matchmaking Guide

Add skill-based matchmaking to your Unity game.