Clients

In GD-Sync, any player who connects using the plugin is referred to as a client. Every client is assigned a unique Client ID, which takes the form of an integer value. Throughout the GD-Sync plugin, client IDs play a central role, they are used whenever you need to directly reference or interact with a specific player. Whether you are sending targeted messages or synchronizing data, the client ID serves as the key that tells the plugin exactly which player you mean.

When connected you can retrieve your own client ID using GDSync.get_client_id().

Player Data

Each client has a small dictionary assigned to them, which is used to store and retrieve custom data. This is called player data. Player data is useful for keeping information that needs to be easily accessed across all clients, such as a player’s selected color or other simple attributes.

Each client can only change the contents of their own player data dictionary and cannot directly modify the data of other clients. To set a value in your player data, use the function GDSync.player_set_data(key : String, value : Variant). The key is a string that identifies the piece of data you’re storing, and it can later be used to retrieve that value. The value can be any type supported by Godot’s Variant, giving you flexibility to store numbers, strings, arrays, or other data types.

To remove a stored entry from your player data, use GDSync.player_erase_data(key : String).

You can retrieve stored player data with GDSync.player_get_data(client_id : int, key : String, default : Variant). This function takes the client ID of the player whose data you want to access, allowing you to get information from both your own client and other clients in the same lobby. If you want to get your own data, simply pass in your own client ID. The default parameter specifies the value to return if the given key does not exist. If not provided, this defaults to null.

To check if a specific key exists for a player without retrieving the value, use GDSync.player_has_data(client_id : int, key : String).

If you need to obtain every data entry for a player at once, use GDSync.player_get_all_data(client_id : int), which will return the entire player data dictionary for that client.

When player data is modified, GD-Sync emits the signal GDSync.player_data_changed(client_id : int, key : String, value) on all connected clients. This signal is triggered both when data is set and when it is erased. If the data is erased, the value parameter will be null. Below is an example showing how a player script can listen for this signal and automatically update the player’s color across all clients whenever it changes.

When player data is updated, the changes are not immediately reflected on other clients. Synchronization can take up to 1 second before the new data is visible to everyone in the lobby. Player data is not intended for values that need to be updated every frame, frequent writes can be costly. For best performance, only update player data when necessary.

Player data has a maximum size limit of 2KB per client. 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.

When player data is modified, GD-Sync emits the signal GDSync.player_data_changed(client_id : int, key : String, value) on all connected clients. This signal is triggered both when data is set and when it is erased. If the data is erased, the value parameter will be null. Below is an example showing how a player script can listen for this signal and automatically update the player’s color across all clients whenever it changes.

# A script that is inside the player scene
var player_id : int

func _ready():
	# Connect the signal
	GDSync.player_data_changed.connect(player_data_changed)

func player_data_changed(client_id : int, key : String, value):
	if client_id != player_id: return # Data changed for a different player
	
	# Data changed for this player!
	if key == "Color" and value is Color: modulate = value

Usernames

GD-Sync includes an optional username system that lets each client set a display name visible to everyone in the lobby. To set your username, use GDSync.player_set_username(username : String). When called, this triggers the GDSync.player_data_changed(client_id : int, key : String, value) signal on all clients, with the key set to "Username" and the value containing the new name.

You can get the username of any client, including yourself, by calling GDSync.player_get_data(client_id : int, "Username", default : Variant). If the username has not been set, the function will return the default value or null if no default is given.

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.

Host Selection

In peer-to-peer games, one client is usually chosen as the host to handle authoritative logic such as spawning enemies, starting or ending matches, and other key game events.

GD-Sync has built-in host selection so you can easily determine which client should run these tasks. By default, the first player to join a lobby becomes the host. If the host leaves, a new one is automatically assigned.

You can check if you are the host by calling GDSync.is_host(), which returns true if you are the current host. Alternatively, you can listen for the GDSync.host_changed(is_host : bool) signal, which is emitted whenever the host changes, such as when the current host disconnects.

func _ready():
	GDSync.host_changed.connect(host_changed)
	
	if GDSync.is_host():
		print("I am the host!")
	else:
		print("I am not the host.")

func host_changed(is_host : bool, new_host_id : int):
	print("Client "+str(new_host_id)+" is the new host")
	if is_host:
		print("I am the new host!")
	else:
		print("I am not new the host.")

Ping

In GD-Sync, you can easily measure the network latency between clients by calling GDSync.get_client_ping(client_id : int). This function returns the ping for the specified client in seconds, giving you a clear indication of how long it takes for data to travel between you, the client and back. It can be used to display network information to players or to help diagnose connection issues.

func _ready() -> void:
	var ping : float = await GDSync.get_client_ping(client_id)
	print("Ping in seconds: ", ping)

Getting Started

Lobbies