LogoLogo
edgegap.comDashboard
  • 📘Learning Center
    • Getting Started
    • Unity Games
      • Getting Started - Servers
      • Developer Tools
    • Unreal Engine Games
      • Getting Started - Servers
      • Developer Tools
    • Matchmaking
      • Getting Started
      • Matchmaker In-Depth
      • Ping Beacons
    • Advanced Features
      • Apps and Versions
      • Deployments
      • Managed Clusters
  • API Reference
    • Dedicated Servers
    • Integration
    • Matchmaking
    • Peer to Peer
  • Release Notes
  • 📚Documentation
    • Sample Projects
      • Unity Netcodes
        • Unity NGO
        • Photon Fusion 1
        • Photon Fusion 2
        • Mirror
        • Mirror WebGL
        • Fishnet
        • Fishnet WebGL
        • Photon Bolt
      • Unreal Top-Down Sample
      • NuxtJS
      • Ruby On Rails
      • Unity Lobbies
      • Unity Matchmaker
    • Tools & Integrations
      • Container
        • What is Docker
        • Your First Docker
        • The Good Practices
        • SSH in Your Container
        • External Registries
          • Docker Hub
          • AWS ECR
          • GCP GCR
          • Gitlab registry
      • Deploy from Nakama
      • EOS Lobby Integration
      • Switch From Gamelift
      • Switch From Multiplay
      • Playfab Bridge
    • Deployment
      • Endpoint Storage
        • How to Save Logs
        • Upload File to Deployment
      • Webhooks
    • Application
      • Command and Arguments
      • 1:1 Port Mapping
    • Session
      • How They Work
      • Application Version Configuration
      • Manage Request
      • Selectors Filtering
    • Fleet
      • Fleet Policy
      • Policy Filter
      • Linking Version
      • Fleet's Deployment
    • Container Registry
    • Distributed Relay
      • Matchmaker/Lobby
      • Relay Edgegap API
      • Transport Samples
    • Lobby
      • Lobby Service
      • Functions
    • Glossary
    • SLA Terms
Powered by GitBook
On this page
  • Overview
  • Functions
  • Creating a new lobby
  • Updating a lobby
  • Getting a specific lobby's information
  • Joining a lobby
  • Leaving a lobby
  • Starting a lobby

Was this helpful?

  1. 📚Documentation
  2. Lobby

Functions

PreviousLobby ServiceNextGlossary

Last updated 2 months ago

Was this helpful?

LogoLogo

Connect with Community

  • Discord
  • Linkedin
  • X

Read More

  • Release Notes
  • Blog
  • Enterprise
  • Legal
  • edgegap.com

© 2025 Edgegap

Lobby service is currently supported with no plans for deprecation. Stay tuned for private clusters and other announcements coming soon!

Overview

Once you've deployed a service and obtained its URL, you are ready to use lobbies in your game! To better understand how our lobbies work in a general timeline and what functions can be called, here is a diagram to help you visualize it.

It begins when a host player creates a new a lobby, which other players can then join and/or leave. It is also possible to update some of the lobby's information with a PATCH.

Once everyone is ready the lobby can start, which creates a relay session that everyone in the lobby can then connect to. To do so, they will need the authorization tokens, IP address and available ports data that is added to the lobby upon starting it.

Functions

Generally speaking, there will be many lobbies available at once for your players to join. You can get a list of all of them by sending a GET request to the /lobbies endpoint of your service URL, and from then on you can even filter them by tags.

With that, your players can then decide which lobby to join, or even create their own.

{
  "count": 0,
  "data": [
    {
      "capacity": 0,
      "is_joinable": true,
      "is_started": true,
      "lobby_id": "string",
      "name": "string",
      "player_count": 0,
      "tags": ["string"]
    }
  ]
}

Creating a new lobby

Creating a new lobby can be done by sending a POST request to /lobbies with the following body:

{
  "annotations": [
    {
      "inject": true,
      "key": "string",
      "value": "string"
    }
  ],
  "capacity": 0,
  "is_joinable": true,
  "name": "string",
  "player": {
    "id": "string"
  },
  "tags": ["string"]
}
  • annotations : a list of key/value pairs, such as environment variables, that could be injected in the deployment;

Seeing as lobbies currently only work alongside relay sessions, annotations are currently unused. We are looking into eventually making them compatible with sessions, deployments, and the likes, so it is a work in progress.

  • capacity : the maximum number of players that are able to join the lobby.

  • is_joinable : indicates whether the lobby can be joined or not. Can be used independently from the player capacit.

  • name : the lobby's displayed name.

  • player : the host player that created the lobby, depicted with a unique ID (e.g. a Steam Account ID, etc).

  • tags : a list of strings to categorize the lobby, useful when filtering them.

If successful the lobby will be given, among other things, a unique lobby_id string which is needed when using the following requests.

Updating a lobby

It is possible to update some of the lobby's information by sending a PATCH request to /lobbies/{lobby_id} with a body containing any of the following variables:

{
  "capacity": 0,
  "is_joinable": true,
  "tags": ["string"]
}
  • capacity : it is possible to set it to a lower value than the current player count, but no player will be forcibly ejected from the lobby.

  • tags : the previous tags will be overwritten by the values here, so make sure to include them if you wish to keep them.

Getting a specific lobby's information

To get the full details of a lobby, you can send a GET request to /lobbies/{lobby_id}. You can also see here what values were added upon creating it.

{
  "annotations": [
    {
      "inject": true,
      "key": "string",
      "value": "string"
    }
  ],
  "assignment": {
    "authorization_token": 0,
    "host": "string",
    "ip": "string",
    "ports": [
      {
        "name": "string",
        "port": 0,
        "protocol": "TCP"
      }
    ]
  },
  "capacity": 0,
  "is_joinable": true,
  "is_started": true,
  "lobby_id": "string",
  "name": "string",
  "player_count": 0,
  "players": [
    {
      "authorization_token": 0,
      "id": "string",
      "is_host": true
    }
  ],
  "tags": ["string"]
}
  • assignment : a collection of values used to connect the players to the session relay when the lobby starts. It will be null until the :start function has been called.

    • authorization_token : a token to authenticate the lobby's session.

    • host : the URL where the relay is located.

    • ip : the IP of the relay's location.

    • ports : a list of ports available to connect to. Typically, one will be named host, and another client.

  • lobby_id : the lobby's unique ID.

  • players : a list of all the players currently in the lobby. In addition to their ID, some values have been added to each of them.

    • authorization_token : a token to authenticate the player when connecting to the relay. It will be null until the :start function has been called.

    • is_host : indicates whether the player is the host or not. It is typically used to determine which port the player will need to connect to.

Joining a lobby

You can add a player to a lobby by sending a POST request to /lobbies:join with the following body:

{
  "lobby_id": "string",
  "player": {
    "id": "string"
  }
}

Your response won't have any content, so you usually want to follow this up by requesting the lobby's full information to be able to display it to the player in question.

Leaving a lobby

As a client

A typical player can exit from a lobby by sending a POST request to /lobbies:leave with the following body:

{
  "lobby_id": "string",
  "player": {
    "id": "string"
  }
}

As a host

Seeing as a lobby needs a host to work properly and that this status can't be transferred between players, a host can't leave the lobby the usual way. Instead, you will need to send a DELETE request to /lobbies/{lobby_id}, which will cause the other players to leave the lobby as well (you won't need to call the actual function, since the lobby will no longer exist).

Starting a lobby

Once all the players in the lobby are ready to start the match, you can send a POST request to /lobbies:start along with this simple body:

{
  "lobby_id": "string"
}

Afterwards, it will take a short time to set up the lobby's assignment as well as each player's authorization_token. Once this is done, all you need to do is use those to let your players communicate with the relay, on which you can find more information here.