Functions
Last updated
Was this helpful?
Last updated
Was this helpful?
Lobby service is currently supported with no plans for deprecation. Stay tuned for private clusters and other announcements coming soon!
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.
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.
Creating a new lobby can be done by sending a POST request to /lobbies with the following body:
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.
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 : 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.
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.
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.
You can add a player to a lobby by sending a POST request to /lobbies:join with the following body:
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.
A typical player can exit from a lobby by sending a POST request to /lobbies:leave with the following body:
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).
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:
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.
