Lobbies
GD-Sync uses lobbies as the foundation for players to connect and play together. A lobby acts as a central structure that groups multiple clients into the same shared environment, allowing them to interact and exchange data in real time. Lobbies are a core part of how GD-Sync organizes multiplayer sessions, and they include a range of built-in features that remove much of the complexity normally involved in setting up multiplayer systems.
Creating
A new lobby can be created by calling
GDSync.lobby_create(name : String, password : String, public : bool, playerlimit : int, tags : Dictionary).
The name parameter is the only one required, as this is how the lobby is identified internally and when browsing. All other parameters are optional and allow you to further configure the lobby.
The password parameter can be used to restrict access to the lobby. If it is left empty, any player can join as long as the lobby has not reached its player limit. Passwords can be up to 16 characters long.
The public parameter determines whether the lobby will be visible when browsing. A value of true means the lobby is visible to anyone, while false hides it from public listings.
The playerlimit parameter sets the maximum number of players that can join the lobby. If no value is provided, GD-Sync automatically sets it to the highest limit your plan allows.
The tags parameter is a dictionary containing public data that can be attached to the lobby, such as the selected map or game mode. Tags can be useful for showing important information before joining. See Tags for more info.
Lobby names must be between 3 and 32 characters in length. Choosing a descriptive and unique name will make it easier for other players to identify your lobby when browsing or receiving an invite.
Lobby names must be between 3 and 32 characters in length. Choosing a descriptive and unique name will make it easier for other players to identify your lobby when browsing. The password must be between 0 and 16 characters in length.
Creating a lobby does not automatically place you inside it. After calling this function, you have 5 seconds to join your newly created lobby. If no one joins during this time, the lobby will be automatically deleted.
Below is an example showing how to create a new lobby using GDSync.lobby_create. This script sets the lobby name, an optional password, its visibility, the playerlimit, and any tags you want to attach. You can adjust these parameters to fit the needs of your game.
When a lobby is successfully created, GD-Sync emits the GDSync.lobby_created(lobby_name : String) signal. The lobby_name parameter contains the name of the newly created lobby.
If the creation fails, GD-Sync emits the GDSync.lobby_creation_failed(lobby_name : String, error : int) signal instead. In this case, lobby_name is the name you attempted to create, and error is an integer error code indicating the reason for the failure. This allows you to handle errors such as invalid parameters and name conflicts.
Joining
Once a lobby has been created, you can join it.
To join a lobby, call GDSync.lobby_join(name : String, password : String). The name parameter is the exact name of the lobby you want to join. If the lobby is password-protected, you must also provide the correct password.
When the join is successful, GD-Sync emits the GDSync.lobby_joined(lobby_name : String) signal, where lobby_name is the name of the lobby you entered.
If the join fails, GD-Sync emits the GDSync.lobby_join_failed(lobby_name : String, error : int) signal instead. In this case, lobby_name is the name you attempted to join, and error is an integer error code indicating the reason for the failure.
The configuration menu also allows you to enforce unique usernames within a lobby. When this option is enabled, no two clients in the same lobby can have the same name. If a client attempts to join with a duplicate, they will be blocked until a different name is chosen.
Leaving
Leaving a lobby is straightforward. Once you are inside a lobby, you can call GDSync.lobby_leave() to exit it. This action always succeeds and does not emit any signals, so there is no need to wait for confirmation.
If every player in a lobby leaves, the lobby is automatically deleted. This ensures that empty lobbies do not remain active.
Browsing
In GD-Sync, lobbies can be public or private. Public lobbies are visible to anyone browsing and can be retrieved by calling GDSync.get_public_lobbies(). When this function is called, GD-Sync requests the list of active public lobbies from the server and then emits the GDSync.lobbies_received(lobbies : Array) signal. The lobbies array contains the details of each public lobby in the defined format, making it easy to display a joinable game list to the player.
If you only need information about a specific public lobby, you can call GDSync.get_public_lobby(lobby_name : String). This will emit the GDSync.lobby_received(lobby : Dictionary) signal, where lobby contains the details of the requested lobby.
Client Events
GD-Sync emits signals whenever a client joins or leaves a lobby.
When a client joins, the GDSync.client_joined(client_id : int) signal is emitted. The client_id parameter is the unique ID of the player who entered the lobby. This signal is triggered for every joining client, including yourself.
When a client leaves, the GDSync.client_left(client_id : int) signal is emitted. The client_id parameter is the ID of the player who left.
The GDSync.client_left signal is only triggered for other clients, not for yourself, because once you leave a lobby you are no longer connected to it and will not receive further messages from it.
Tags & Data
Each lobby has two systems for storing temporary variables, lobby tags and lobby data. Both work the same way in how they are set, retrieved, and synchronized, with one key difference. Tags are publicly visible to anyone browsing public lobbies, while lobby data is only accessible to clients currently inside the lobby.
A client can only modify the tags or data of the lobby they are currently in. To set a lobby tag, use GDSync.lobby_set_tag(key : String, value : Variant). The key is the name of the variable you want to set, and the value can be any type supported by Godot’s Variant. This function can be used both to create a new entry and to overwrite existing data. To remove a tag, use GDSync.lobby_erase_tag(key : String), which will delete the entry if it exists.
Tags can be retrieved using GDSync.lobby_get_tag(key : String, default : Variant). The default value will be returned if the given key does not exist, and defaults to null when omitted. To check if a tag exists without retrieving its value, use GDSync.lobby_has_tag(key : String). To get all tags at once, use GDSync.lobby_get_all_tags(), which returns a dictionary containing every tag for the current lobby.
Whenever a lobby tag is set or erased, GD-Sync emits the signal GDSync.lobby_tags_changed(key : String, value : Variant) to all clients in the lobby. If a tag is erased, the value parameter will be null.
Lobby data works the same way but is not visible outside the lobby. To set lobby data, call GDSync.lobby_set_data(key : String, value : Variant). The key specifies the name of the variable, and the value can be any Godot Variant. To remove a data entry, use GDSync.lobby_erase_data(key : String).You can retrieve lobby data using GDSync.lobby_get_data(key : String, default : Variant), with the default parameter working the same way as for tags. To check if a data entry exists, use GDSync.lobby_has_data(key : String). To get all data entries at once, use GDSync.lobby_get_all_data(), which returns the complete data dictionary for the lobby.
When lobby data changes, the signal GDSync.lobby_data_changed(key : String, value : Variant) is emitted to all clients in the lobby. If the data was erased, the value will be null.
Lobby tags and data are automatically synchronized across all clients in the same lobby. This synchronization is not instant and can take up to 1 second to appear for everyone. Updating tags or data too frequently can become a relatively expensive operation, as each update requires additional network transfer.
Lobby tags has a maximum size limit of 2KB per lobby. Lobby Data has a maximum size limit of 8KB per lobby. If you attempt to store data that exceeds this limit, GD-Sync will print an error message in the console. If you experience unexpected behavior or missing data, it’s a good idea to first check the console output to see if a size limit error was triggered.
The table below provides an overview of the differences between lobby tags and lobby data, along with guidance on when each should be used.