### Leaderboard Get Score Result Example

Source: https://www.gd-sync.com/docs/leaderboards

Example structure for the dictionary returned when retrieving a specific user's score and rank from a leaderboard.

```JSON
{
	"Code" : 0,
	"Result" :
		{
			"Score" : 100,
			"Rank" : 1
		}
}
```

--------------------------------

### Login Result Example

Source: https://www.gd-sync.com/docs/cloud-storage

Example of a dictionary returned by GDSync.account_login, showing a successful login with a ban time.

```JSON
{
	"Code" : 0,
	"BanTime" : 1719973379
}
```

--------------------------------

### Start Online Multiplayer and Handle Signals

Source: https://www.gd-sync.com/docs/getting-started

Connect to GD-Sync's online multiplayer service and set up signal handlers for connection success and failure. Ensure relevant signals are connected before starting the multiplayer session.

```GDScript
func _ready():
	GDSync.connected.connect(connected)
	GDSync.connection_failed.connect(connection_failed)
	
GDSync.start_multiplayer()

func connected():
	print("You are now connected!")

func connection_failed(error : int):
	match(error):
		ENUMS.CONNECTION_FAILED.INVALID_PUBLIC_KEY:
			push_error("The public or private key you entered were invalid.")
		ENUMS.CONNECTION_FAILED.TIMEOUT:
			push_error("Unable to connect, please check your internet connection.")
```

--------------------------------

### Browse Collection Response Example

Source: https://www.gd-sync.com/docs/cloud-storage

This is an example of the dictionary format returned by GDSync.account_browse_collection, including the response code and the list of documents or collections.

```json
{
	"Code" : 0,
	"Result" :
		[
			{"ExternallyVisible": true, "Name": "profile", "Path": "saves/profile", "Type": "Document"},
			{"ExternallyVisible": false, "Name": "save1", "Path": "saves/save1", "Type": "Document"},
			{"ExternallyVisible": false, "Name": "save2", "Path": "saves/save2", "Type": "Document"},
			{"ExternallyVisible": false, "Name": "configs", "Path": "saves/configs", "Type": "Collection"}
		]
}
```

--------------------------------

### Leaderboard Browse Scores Result Example

Source: https://www.gd-sync.com/docs/leaderboards

Example structure for the dictionary returned when browsing leaderboard scores. Includes pagination information and a list of scores.

```JSON
{
	"Code" : 0,
	"FinalPage": 7,
	"Result" :
		[
			{"Rank": 1, "Score": 828, "Username": "User1"},
			{"Rank": 2, "Score": 700, "Username": "User2"},
			{"Rank": 3, "Score": 10, "Username": "User3"}
		]
}
```

--------------------------------

### Get All Friends Response Example

Source: https://www.gd-sync.com/docs/cloud-storage

This JSON structure shows the result of retrieving the status of all friends and any pending friend requests, including lobby details for each friend.

```json
{
	"Code" : 0,
	"Result" : [
		{
			"Username" : "Epic Username",
			"FriendStatus" : 2,
			"Lobby" : {
				"Name" : "Epic Lobby",
				"HasPassword" : true
			}
		},
		{
			"Username" : "Cool Username",
			"FriendStatus" : 2,
			"Lobby" : {
				"Name" : "",
				"HasPassword" : false
			}
		},
		{
			"Username" : "Awesome Username",
			"FriendStatus" : 1
		}
	]
}
```

--------------------------------

### Document Retrieval Result Example

Source: https://www.gd-sync.com/docs/cloud-storage

This is an example of the JSON structure returned when retrieving a document using GDSync.account_get_document.

```JSON
{
	"Code" : 0,
	"Result" : {*document*}
}
```

--------------------------------

### VoiceChat Node Setup

Source: https://www.gd-sync.com/docs/custom-node-types

Set up the VoiceChat node for multiplayer voice communication. Assign ownership and connect to an AudioStreamPlayer for playback. Supports spatial audio modes.

```gdscript
spatial_mode
```

--------------------------------

### Get Friend Status Response Example

Source: https://www.gd-sync.com/docs/cloud-storage

This JSON structure represents the result of a request to get an individual friend's status, including their lobby information if applicable.

```json
{
	"Code" : 0,
	"Result" : {
		"FriendStatus" : 2,
		"Lobby" : {
			"Name" : "Epic Lobby",
			"HasPassword" : false
		}
	}
}
```

--------------------------------

### Document Existence Check Result Example

Source: https://www.gd-sync.com/docs/cloud-storage

This is an example of the JSON structure returned when checking for document existence using GDSync.account_has_document.

```JSON
{
	"Code" : 0,
	"Result" : true
}
```

--------------------------------

### Listen for Player Data Changes in GDScript

Source: https://www.gd-sync.com/docs/clients

Connect to the `player_data_changed` signal to react to updates in player data. This example shows how to update a player's color when their 'Color' data changes. Ensure the script is attached to the player scene and that the `player_id` is correctly set.

```GDScript
# 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
```

--------------------------------

### Get All Lobby Data

Source: https://www.gd-sync.com/docs/lobbies

Retrieves all lobby data as a dictionary. This function returns the complete data dictionary for the lobby.

```gdscript
GDSync.lobby_get_all_data()
```

--------------------------------

### Get All Lobby Tags

Source: https://www.gd-sync.com/docs/lobbies

Retrieves all lobby tags as a dictionary. This function returns a dictionary containing every tag for the current lobby.

```gdscript
GDSync.lobby_get_all_tags()
```

--------------------------------

### Get Score

Source: https://www.gd-sync.com/docs/leaderboards

Retrieves the score and rank for a specific user on a leaderboard. Requires a valid login session.

```APIDOC
## Get Score

### Description
Retrieves the score and rank of a specific user on a leaderboard. A valid login session is required.

### Method
`GDSync.leaderboard_get_score(leaderboard: String, username: String)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```gdscript
# Example of getting a specific user's score (actual implementation depends on context)
# var result_data = await GDSync.leaderboard_get_score("Leaderboard1", "User1")
```

### Response
#### Success Response (200)
Returns a dictionary containing the response code and the user's score and rank.

#### Response Example
```json
{
	"Code" : 0,
	"Result" :
		{
			"Score" : 100,
			"Rank" : 1
		}
}
```
```

--------------------------------

### Create a New Lobby with GD-Sync

Source: https://www.gd-sync.com/docs/lobbies

Use this function to create a new lobby. Ensure you connect to the lobby_created and lobby_creation_failed signals to handle the outcome. The lobby will be deleted if no players join within 5 seconds.

```GDScript
func _ready():
	GDSync.lobby_created.connect(lobby_created)
	GDSync.lobby_creation_failed.connect(lobby_creation_failed)
	
GDSync.lobby_create(
		"Lobby Name",
		"Password123",
		true,
		10,
		{
			"Map" : "Desert",
			"Game Mode" : "Free For All"
		}
	)

func lobby_created(lobby_name : String):
	print("Succesfully created lobby "+lobby_name)
#	Now you can join the lobby!

func lobby_creation_failed(lobby_name : String, error : int):
	match(error):
		ENUMS.LOBBY_CREATION_ERROR.LOBBY_ALREADY_EXISTS:
			push_error("A lobby with the name "+lobby_name+" already exists.")
		ENUMS.LOBBY_CREATION_ERROR.NAME_TOO_SHORT:
			push_error(lobby_name+" is too short.")
		ENUMS.LOBBY_CREATION_ERROR.NAME_TOO_LONG:
			push_error(lobby_name+" is too long.")
		ENUMS.LOBBY_CREATION_ERROR.PASSWORD_TOO_LONG:
			push_error("The password for "+lobby_name+" is too long.")
		ENUMS.LOBBY_CREATION_ERROR.TAGS_TOO_LARGE:
			push_error("The tags have exceeded the 2048 byte limit.")
		ENUMS.LOBBY_CREATION_ERROR.DATA_TOO_LARGE:
			push_error("The data have exceeded the 2048 byte limit.")
		ENUMS.LOBBY_CREATION_ERROR.ON_COOLDOWN:
			push_error("Please wait a few seconds before creating another lobby.")
```

--------------------------------

### Create Account with GDScript

Source: https://www.gd-sync.com/docs/cloud-storage

Use this function to create a new player account. Ensure email verification is handled if enabled. Usernames and passwords must meet length and format requirements.

```GDScript
func _ready():
	var response_code : int = await GDSync.account_create("email@email.com", "username", "password")
	
	if response_code == ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.SUCCESS:
		print("Account created!")
	else:
		match(response_code):
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
				push_error("No response from server")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.DATA_CAP_REACHED:
				push_error("Data transfer cap has been reached.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
				push_error("Rate limit exceeded, please wait and try again.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.NO_DATABASE:
				push_error("API key has no linked database.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.STORAGE_FULL:
				push_error("Database is full.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.INVALID_EMAIL:
				push_error("Invalid email address.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.INVALID_USERNAME:
				push_error("Username contains illegal characters.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.EMAIL_ALREADY_EXISTS:
				push_error("An account with this email address already exists.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_ALREADY_EXISTS:
				push_error("An account with this username address already exists.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_TOO_SHORT:
				push_error("Username is too short.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_TOO_LONG:
				push_error("Username is too long.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.PASSWORD_TOO_SHORT:
				push_error("Password is too short.")
			ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.PASSWORD_TOO_LONG:
				push_error("Password is too long.")
```

--------------------------------

### Connect to GD-Sync and Create Lobbies

Source: https://www.gd-sync.com

Connects to the GD-Sync network and automatically handles NAT. Listen for connection and lobby events, then create and join a public lobby.

```gdscript
extends Node

func _ready() -> void:
	# 1. Listen for connection and lobby events
	GDSync.connected.connect(_on_connected)
	GDSync.lobby_created.connect(_on_lobby_created)
	
	# 2. Connect to the GD-Sync global network
	GDSync.start_multiplayer()

func _on_connected() -> void:
	# 3. Create a public lobby for up to 4 players
	GDSync.lobby_create("MyLobby", "", true, 4)

func _on_lobby_created(lobby_name: String) -> void:
	# 4. Join the lobby you just created.
	#    Other players can join it using the lobby_name.
	GDSync.lobby_join(lobby_name, "")
```

--------------------------------

### Account - Create

Source: https://www.gd-sync.com/docs/cloud-storage

Creates a new user account for cloud storage. Requires email, username, and password. Usernames and passwords must be between 3 and 20 characters. Email verification may be sent if enabled.

```APIDOC
## Account - Create

### Description
Accounts can be created directly from within the engine using GDSync.account_create(email : String, username : String, password : String). The function returns a response code, which will be one of the values defined in ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.

Usernames and passwords must be between 3 and 20 characters in length. Usernames must also match the configured username regex pattern from the database, and the email must be in a valid email format.

If email verification is enabled, GD-Sync will automatically send a verification email containing a code to the provided address.

Once the account has been successfully created, the user can proceed to log in.

### Method
`GDSync.account_create`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (String) - Required - The email address for the new account.
- **username** (String) - Required - The desired username for the new account.
- **password** (String) - Required - The desired password for the new account.

### Request Example
```gdscript
func _ready():
	var response_code : int = await GDSync.account_create("email@email.com", "username", "password")
```

### Response
#### Success Response (200)
- **response_code** (int) - Indicates the success or failure of the account creation.

#### Response Example
```gdscript
if response_code == ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.SUCCESS:
	print("Account created!")
else:
	match(response_code):
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
			push_error("No response from server")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.DATA_CAP_REACHED:
			push_error("Data transfer cap has been reached.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
			push_error("Rate limit exceeded, please wait and try again.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.NO_DATABASE:
			push_error("API key has no linked database.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.STORAGE_FULL:
			push_error("Database is full.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.INVALID_EMAIL:
			push_error("Invalid email address.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.INVALID_USERNAME:
			push_error("Username contains illegal characters.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.EMAIL_ALREADY_EXISTS:
			push_error("An account with this email address already exists.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_ALREADY_EXISTS:
			push_error("An account with this username address already exists.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_TOO_SHORT:
			push_error("Username is too short.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.USERNAME_TOO_LONG:
			push_error("Username is too long.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.PASSWORD_TOO_SHORT:
			push_error("Password is too short.")
		ENUMS.ACCOUNT_CREATION_RESPONSE_CODE.PASSWORD_TOO_LONG:
			push_error("Password is too long.")
```
```

--------------------------------

### Login with Email and Password

Source: https://www.gd-sync.com/docs/cloud-storage

Use this function to log in an account using email and password. Handles various response codes and displays appropriate error messages. Ensure ENUMS are correctly imported.

```GDScript
func _ready():
	var response : Dictionary = await GDSync.account_login("email@email.com", "password")
	var response_code : int = response["Code"]
	
	if response_code == ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.SUCCESS:
		print("Logged in!")
	else:
		match(response_code):
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
				push_error("No response from server")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.DATA_CAP_REACHED:
				push_error("Data transfer cap has been reached.")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
				push_error("Rate limit exceeded, please wait and try again.")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NO_DATABASE:
				push_error("API key has no linked database.")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.EMAIL_OR_PASSWORD_INCORRECT:
				push_error("Email or password incorrect.")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NOT_VERIFIED:
				push_error("Email is not verified.")
			ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.BANNED:
				var ban_time : int = response["BanTime"]
				
				if ban_time == -1:
					push_error("Account is permanently banned.")
				else:
					var ban_time_string : String = Time.get_datetime_string_from_unix_time(ban_time, true)
					push_error("Account is banned until "+ban_time_string+".")
```

--------------------------------

### Submit and Fetch Scores with GD-Sync Leaderboards

Source: https://www.gd-sync.com

Shows how to submit a player's score to a leaderboard and fetch the top global rankings.

```gdscript
# Submit score — just one line of code
func submit_score(points: int) -> void:
	var code = await GDSync.leaderboard_submit_score("GlobalHighScores", points)
	if code == ENUMS.LEADERBOARD_SUBMIT_SCORE_RESPONSE_CODE.SUCCESS:
		print("Score submitted!")

# Fetch top 10 global rankings instantly
func get_top_scores() -> void:
	var res = await GDSync.leaderboard_get_scores("GlobalHighScores", 0, 10)
	for entry in res.scores:
		print(entry.username, " — ", entry.score)
```

--------------------------------

### Save and Load Game Progress with GD-Sync Cloud Storage

Source: https://www.gd-sync.com

Demonstrates saving game progress, including level and inventory, to cloud storage and loading it back on any device.

```gdscript
# Save to cloud — any Godot Variant supported natively
func save_progress() -> void:
	var code = await GDSync.account_document_set(
		"saves/slot1", {
			"level": current_level,
			"inventory": player.inventory
		}
	)
	if code == ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.SUCCESS:
		print("Saved to cloud")

# Load your progress on any device
func load_progress() -> void:
	var res = await GDSync.account_document_get("saves/slot1")
	if res.code == OK:
		apply_save(res.document)
```

--------------------------------

### SynchronizedRigidbody Physics Synchronization

Source: https://www.gd-sync.com/docs/custom-node-types

Synchronize physics interactions using _synced versions of force and impulse functions. This node is experimental and provides basic physics synchronization.

```gdscript
apply_force_synced()
apply_impulse_synced()
apply_central_impulse_synced()
apply_central_force_synced()
apply_torque_synced()
apply_torque_impulse_synced()
```

--------------------------------

### Connect to Steam Join Request Signal

Source: https://www.gd-sync.com/docs/steam

Connect to the GDSync.steam_join_request signal in your _ready function. This signal is emitted when a friend tries to join your lobby via Steam.

```GDScript
func _ready() -> void:
	GDSync.steam_join_request.connect(steam_join_request)
```

--------------------------------

### Log in using Steam Session

Source: https://www.gd-sync.com/docs/steam

Use GDSync.steam_login() with a valid time to log into your GD-Sync account using the linked Steam session. This bypasses the need for manual email and password entry.

```GDScript
#GDSync.steam_login(valid_time : float)
```

--------------------------------

### Handle Steam Join Request

Source: https://www.gd-sync.com/docs/steam

Implement the steam_join_request function to handle incoming join requests from Steam friends. If the lobby does not have a password, you can join directly. Otherwise, prompt the user for a password.

```GDScript
func steam_join_request(lobby_name : String, has_password : bool) -> void:
	if !has_password:
		#Directly join the lobby
		#GDSync.join_lobby(lobby_name)
	else:
		#A password has to be entered first
```

--------------------------------

### Retrieve Document with GDSync

Source: https://www.gd-sync.com/docs/cloud-storage

Use GDSync.account_get_document to fetch a document. The response includes a code and the document data if successful. Handle various error codes for troubleshooting.

```GDScript
func _ready():
	var response : Dictionary = await GDSync.account_get_document("collection1/collection2/document1")
	var response_code : int = response["Code"]
	
	if response_code == ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.SUCCESS:
		var document : Dictionary = response["Result"]
		
		print("Document retrieved!")
	else:
		match(response_code):
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
				push_error("No response from server")
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.DATA_CAP_REACHED:
				push_error("Data transfer cap has been reached.")
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
				push_error("Rate limit exceeded, please wait and try again.")
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NO_DATABASE:
				push_error("API key has no linked database.")
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NOT_LOGGED_IN:
				push_error("There is not valid login session.")
			ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.DOESNT_EXIST:
				push_error("The specified path does not exist.")
```

--------------------------------

### Expose and Call Functions Remotely with GD-Sync

Source: https://www.gd-sync.com

Exposes a function to be called remotely across the network and demonstrates how to call it on all connected clients or a specific client.

```gdscript
# Easily call functions across the network
extends Node

func _ready() -> void:
	# 1. Expose the function so it can be called remotely
	GDSync.expose_func(update_health)

func _process(_delta: float) -> void:
	if Input.is_action_just_pressed("heal"):
		# 2. Call the exposed function on all connected clients
		GDSync.call_func_all(update_health, 100)
		
		# Or call it on a specific client using their ID:
		# GDSync.call_func_on(client_id, update_health, 100)

func update_health(amount: int) -> void:
	print("Health updated to: ", amount)
```

--------------------------------

### Set Account Document

Source: https://www.gd-sync.com/docs/cloud-storage

Stores a document at a specified path within the account. Collections are created automatically if they don't exist. Ensure you handle potential response codes for errors like data caps or rate limits.

```gdscript
func _ready():
	var document : Dictionary = {
		"Info" : "This is a document!",
		"Numbers" : [1, 3, 523],
		"Godot" : "Is awesome"
	}
	
	var response_code : int = await GDSync.account_document_set("collection1/collection2/document1", document)
	
	if response_code == ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.SUCCESS:
		print("Document created!")
	else:
		match(response_code):
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
				push_error("No response from server")
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.DATA_CAP_REACHED:
				push_error("Data transfer cap has been reached.")
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
				push_error("Rate limit exceeded, please wait and try again.")
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NO_DATABASE:
				push_error("API key has no linked database.")
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NOT_LOGGED_IN:
				push_error("There is not valid login session.")
			ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.STORAGE_FULL:
				push_error("Database is full.")
```

--------------------------------

### Link GD-Sync Account to Steam

Source: https://www.gd-sync.com/docs/steam

Call GDSync.steam_link_account() after logging into a GD-Sync account to link it with the active Steam session. This allows for Steam-based logins.

```GDScript
#GDSync.steam_link_account()
```

--------------------------------

### Check and Handle Host Status

Source: https://www.gd-sync.com/docs/clients

Connect to the host_changed signal and check if the current client is the host. Emitted when the host changes.

```GDScript
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.")
```

--------------------------------

### Lobby Joining API

Source: https://www.gd-sync.com/docs/lobbies

Allows clients to join existing lobbies. Handles password protection and provides feedback on success or failure.

```APIDOC
## Joining a Lobby

To join a lobby, call `GDSync.lobby_join(name : String, password : String)`.

### Method

`GDSync.lobby_join`

### Parameters

#### Path Parameters

- **name** (String) - Required - The exact name of the lobby to join.
- **password** (String) - Optional - The password for the lobby if it is password-protected.

### Signals Emitted on Join

- **`GDSync.lobby_joined(lobby_name : String)`**: Emitted when the join is successful. `lobby_name` is the name of the lobby entered.
- **`GDSync.lobby_join_failed(lobby_name : String, error : int)`**: Emitted when the join fails. `lobby_name` is the name attempted, and `error` is an integer error code.

### Notes

- The `configuration menu` can enforce unique usernames within a lobby. If enabled, duplicate usernames will prevent a client from joining until a unique name is chosen.
```

--------------------------------

### Synchronize a Variable Across Clients

Source: https://www.gd-sync.com/docs/remote-calls

Expose a variable and then synchronize its updated value to all other clients in the lobby. This script must exist on all clients.

```GDScript
# This Node with this script must exist on all clients in order to work

var test_var : int = 0

func _ready() -> void:
	# Expose the function so it may be synced remotely
	GDSync.expose_var(self, "test_var")
	
	# Edit the variable
	test_var = 10
	
	# Sync the edit to other clients
	GDSync.sync_var(self, "test_var")
	# test_var is now 10 on all clients!
```

--------------------------------

### Account Login API

Source: https://www.gd-sync.com/docs/cloud-storage

Provides endpoints for logging into user accounts, managing session validity, and handling logout.

```APIDOC
## Account - Login

### Description
Allows users to log into their accounts using email and password, or by restoring a previous session. It also provides functionality to log out and ensures proper shutdown procedures.

### Methods
- `GDSync.account_login(email : String, password : String, valid_time : float)`: Logs in a user with provided credentials. `valid_time` specifies session duration in seconds.
- `GDSync.account_login_from_session(valid_time : float)`: Attempts to restore or refresh an existing login session. `valid_time` specifies the desired session duration.
- `GDSync.account_logout()`: Logs the current user out.
- `GDSync.quit()`: Shuts down the plugin, performing necessary server callbacks. Should be used instead of `get_tree().quit()` when logged in.

### Parameters
#### `GDSync.account_login` Parameters
- **email** (String) - Required - The user's email address.
- **password** (String) - Required - The user's password.
- **valid_time** (float) - Optional - The duration in seconds for which the login session should remain valid.

#### `GDSync.account_login_from_session` Parameters
- **valid_time** (float) - Optional - The duration in seconds for which the restored or refreshed session should remain valid.

### Response
#### `GDSync.account_login` Success Response (Dictionary)
- **Code** (int) - The response code indicating the result of the login attempt. Refer to `ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE` for possible values.
- **BanTime** (int) - A Unix timestamp indicating when the account ban expires. `-1` signifies a permanent ban.

#### `GDSync.account_logout` Success Response (int)
- Response code from `ENUMS.ACCOUNT_LOGOUT_RESPONSE_CODE`.

### Request Example (GDScript)
```gdscript
func _ready():
    var response : Dictionary = await GDSync.account_login("email@email.com", "password")
    var response_code : int = response["Code"]
    
    if response_code == ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.SUCCESS:
        print("Logged in!")
    else:
        match(response_code):
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
                push_error("No response from server")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.DATA_CAP_REACHED:
                push_error("Data transfer cap has been reached.")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
                push_error("Rate limit exceeded, please wait and try again.")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NO_DATABASE:
                push_error("API key has no linked database.")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.EMAIL_OR_PASSWORD_INCORRECT:
                push_error("Email or password incorrect.")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.NOT_VERIFIED:
                push_error("Email is not verified.")
            ENUMS.ACCOUNT_LOGIN_RESPONSE_CODE.BANNED:
                var ban_time : int = response["BanTime"]
                
                if ban_time == -1:
                    push_error("Account is permanently banned.")
                else:
                    var ban_time_string : String = Time.get_datetime_string_from_unix_time(ban_time, true)
                    push_error("Account is banned until "+ban_time_string+".")
```

### Response Example (Login)
```json
{
	"Code" : 0,
	"BanTime" : 1719973379
}
```
```

--------------------------------

### Client Event Signals

Source: https://www.gd-sync.com/docs/lobbies

Signals emitted by GD-Sync to notify about clients joining or leaving a lobby.

```APIDOC
## Client Events

### Client Joined Signal

- **`GDSync.client_joined(client_id : int)`**: Emitted when a client joins a lobby. `client_id` is the unique ID of the joining player. This signal is triggered for all joining clients, including the local player.

### Client Left Signal

- **`GDSync.client_left(client_id : int)`**: Emitted when a client leaves a lobby. `client_id` is the ID of the player who left. This signal is **only** triggered for other clients, not for the local player who initiated the leave action.
```

--------------------------------

### SynchronizedAudioStreamPlayer3D Synchronization

Source: https://www.gd-sync.com/docs/custom-node-types

Synchronizes audio playback, volume, unit size, max db, pitch scale, max distance, and attenuation across clients.

```gdscript
volume_db
unit_size
max_db
pitch_scale
max_distance
attenuation
```

--------------------------------

### Expose and Emit Signal Remotely

Source: https://www.gd-sync.com/docs/remote-calls

Expose a signal for remote emission and then emit it on other clients. The Node with this script must exist on all clients in the same location.

```GDScript
# This Node with this script must exist on all clients in order to work

signal test(test_var : int)

func _ready() -> void:
	# Expose the signal so it may be called emitted
	GDSync.expose_signal(test)
	
	# Perform the remote emission
	GDSync.emit_signal_remote(test, [1])
```

--------------------------------

### Browse Collection with GDSync in GDScript

Source: https://www.gd-sync.com/docs/cloud-storage

Use this GDScript function to browse a collection. It handles success and various error codes returned by the GDSync.account_browse_collection function.

```gdscript
func _ready():
	var response : Dictionary = await GDSync.account_browse_collection("collection1")
	var response_code : int = response["Code"]
	
	if response_code == ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.SUCCESS:
		var results : Array = response["Result"]
		
		print("Collection browsed!")
	else:
		match(response_code):
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
				push_error("No response from server")
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.DATA_CAP_REACHED:
				push_error("Data transfer cap has been reached.")
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
				push_error("Rate limit exceeded, please wait and try again.")
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.NO_DATABASE:
				push_error("API key has no linked database.")
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.NOT_LOGGED_IN:
				push_error("There is not valid login session.")
			ENUMS.ACCOUNT_BROWSE_COLLECTION_RESPONSE_CODE.DOESNT_EXIST:
				push_error("The specified path does not exist.")
```

--------------------------------

### Document Storage API

Source: https://www.gd-sync.com/docs/cloud-storage

APIs for storing and managing documents and collections within GD-Sync.

```APIDOC
## Documents - Storing

### Store Document
Stores data on an account at a specified path.

### Method
`GDSync.account_document_set(path : String, document : Dictionary, externally_visible : bool)`

### Parameters
- **path** (String) - Required - The path where the document should be stored. Collections are created automatically if they don't exist.
- **document** (Dictionary) - Required - The document to store. Can contain any Godot Variant type except object encoding.
- **externally_visible** (bool) - Required - Determines if the document and its parent collections are visible externally.

### Response Codes
- `ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE`
  - `SUCCESS`
  - `NO_RESPONSE_FROM_SERVER`
  - `DATA_CAP_REACHED`
  - `RATE_LIMIT_EXCEEDED`
  - `NO_DATABASE`
  - `NOT_LOGGED_IN`
  - `STORAGE_FULL`

### Request Example
```gdscript
var document : Dictionary = {
	"Info" : "This is a document!",
	"Numbers" : [1, 3, 523],
	"Godot" : "Is awesome"
}
var response_code : int = await GDSync.account_document_set("collection1/collection2/document1", document, true)

if response_code == ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.SUCCESS:
	print("Document created!")
else:
	match(response_code):
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER:
			push_error("No response from server")
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.DATA_CAP_REACHED:
			push_error("Data transfer cap has been reached.")
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.RATE_LIMIT_EXCEEDED:
			push_error("Rate limit exceeded, please wait and try again.")
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NO_DATABASE:
			push_error("API key has no linked database.")
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.NOT_LOGGED_IN:
			push_error("There is not valid login session.")
		ENUMS.ACCOUNT_DOCUMENT_SET_RESPONSE_CODE.STORAGE_FULL:
			push_error("Database is full.")
```

### Update Document Visibility
Updates the visibility of a document or collection.

### Method
`GDSync.account_document_set_external_visible(path : String, externally_visible : bool = false)`

### Parameters
- **path** (String) - Required - The path to the document or collection.
- **externally_visible** (bool) - Optional - The desired visibility state. Defaults to false.

### Response Codes
- `ENUMS.ACCOUNT_DOCUMENT_SET_EXTERNAL_VISIBLE_RESPONSE_CODE`
```

--------------------------------

### SynchronizedAudioStreamPlayer2D Synchronization

Source: https://www.gd-sync.com/docs/custom-node-types

Synchronizes audio playback, volume, pitch scale, max distance, and attenuation across clients.

```gdscript
volume_db
pitch_scale
max_distance
attenuation
```

--------------------------------

### Connect to Ownership Changes and Set Ownership

Source: https://www.gd-sync.com/docs/remote-calls

Connects to the GDSync owner changed signal and sets the current node as owned by the local client. This is useful for ensuring that only the local player controls their character.

```GDScript
func _ready() -> void:
	# Connect so we can listen for ownership changes
	GDSync.connect_gdsync_owner_changed(self, owner_changed)
	
	# Take ownership
	GDSync.set_gdsync_owner(self, GDSync.get_client_id())

func owner_changed(new_owner : int) -> void:
	print("Ownership changed ", new_owner)
```

--------------------------------

### Retrieve Lobby Data

Source: https://www.gd-sync.com/docs/lobbies

Retrieves lobby data. If the key does not exist, the default value is returned (null by default).

```gdscript
GDSync.lobby_get_data(key : String, default : Variant = null)
```

--------------------------------

### Retrieve Document

Source: https://www.gd-sync.com/docs/cloud-storage

Retrieves data from a specified document path. Returns a dictionary containing the result and a response code.

```APIDOC
## GET /account/document

### Description
Retrieves data from a specified document path. Returns a dictionary containing the result and a response code.

### Method
GET

### Endpoint
/account/document

### Parameters
#### Query Parameters
- **path** (String) - Required - The path to the document to retrieve.

### Request Example
```json
{
  "path": "collection1/collection2/document1"
}
```

### Response
#### Success Response (200)
- **Code** (Integer) - The response code. 0 indicates success.
- **Result** (Dictionary) - The retrieved document data.

#### Response Example
```json
{
  "Code": 0,
  "Result": {
    "*document*"
  }
}
```

#### Error Responses
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NO_RESPONSE_FROM_SERVER**: No response from server.
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.DATA_CAP_REACHED**: Data transfer cap has been reached.
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.RATE_LIMIT_EXCEEDED**: Rate limit exceeded, please wait and try again.
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NO_DATABASE**: API key has no linked database.
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.NOT_LOGGED_IN**: There is not valid login session.
- **ENUMS.ACCOUNT_GET_DOCUMENT_RESPONSE_CODE.DOESNT_EXIST**: The specified path does not exist.
```

--------------------------------

### SynchronizedAnimatedSprite2D Playback

Source: https://www.gd-sync.com/docs/custom-node-types

Use _synced versions of animation functions to automatically synchronize animation changes across all clients. This includes playback, frame changes, and speed.

```gdscript
play_synced()
play_backwards_synced()
set_frame_and_progress_synced()
stop_synced()
```

--------------------------------

### Browse Scores

Source: https://www.gd-sync.com/docs/leaderboards

Retrieves a paginated list of scores from a leaderboard. Requires a valid login session.

```APIDOC
## Browse Scores

### Description
Retrieves a paginated list of scores from a leaderboard. A valid login session is required.

### Method
`GDSync.leaderboard_browse_scores(leaderboard: String, page_size: int, page: int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```gdscript
# Example of browsing scores (actual implementation depends on context)
# var result_data = await GDSync.leaderboard_browse_scores("Leaderboard1", 10, 1)
```

### Response
#### Success Response (200)
Returns a dictionary containing the response code, the final page number, and a list of scores. Each score entry includes Rank, Score, and Username.

#### Response Example
```json
{
	"Code" : 0,
	"FinalPage": 7,
	"Result" :
		[
			{"Rank": 1, "Score": 828, "Username": "User1"},
			{"Rank": 2, "Score": 700, "Username": "User2"},
			{"Rank": 3, "Score": 10, "Username": "User3"}
		]
}
```
```

--------------------------------

### Lobby Leaving API

Source: https://www.gd-sync.com/docs/lobbies

Enables clients to leave the current lobby. Lobbies are automatically deleted when all players leave.

```APIDOC
## Leaving a Lobby

To leave a lobby, call `GDSync.lobby_leave()`.

### Method

`GDSync.lobby_leave`

### Description

This action always succeeds and does not emit any signals. Once all players leave a lobby, it is automatically deleted.
```

--------------------------------

### Expose and Call Function Remotely

Source: https://www.gd-sync.com/docs/remote-calls

Expose a function for remote calls and then invoke it on other clients. The Node with this script must exist on all clients in the same location.

```GDScript
# This Node with this script must exist on all clients in order to work
func _ready() -> void:
	# Expose the function so it may be called remotely
	GDSync.expose_func(test)
	
	# Perform the remote call
	GDSync.call_func(test, [1])

func test(test_var : int) -> void:
	print("I got called remotely!")
	print(test_var)
```

--------------------------------

### Set Lobby Tag

Source: https://www.gd-sync.com/docs/lobbies

Use this function to create a new lobby tag or overwrite an existing one. The key is the variable name, and the value can be any Godot Variant.

```gdscript
GDSync.lobby_set_tag(key : String, value : Variant)
```

--------------------------------

### Check if Lobby Data Exists

Source: https://www.gd-sync.com/docs/lobbies

Returns true if a lobby data entry with the specified key exists, false otherwise.

```gdscript
GDSync.lobby_has_data(key : String)
```