Ezcha Network for Godot 4

Looking for the Godot 3 version?

This repository contains the official Ezcha Network plugin for Godot. It allows you to integrate the Ezcha Network platform and its features into your games. This includes authentication, trophies, leaderboards and more.

Developer Applications

Applications to become a developer on the Ezcha Network are now open. Get more info here or apply now. You must be a verified developer on the platform to list your game and to access its API and features. You will not be able to use this plugin otherwise.

Documentation

Full documentation/reference for the plugin can be viewed here.

Setup

Follow the steps below to setup the plugin in your project.

1. Create a game listing on Ezcha Network.
2. Copy the game ID from its developer panel, found under the "API" tab.
3. Add the plugin to the /addons directory of your Godot project.
4. Enable the "Ezcha Network" plugin in the project settings.
5. Find the new "Ezcha" menu below the inspector.
6. Use the menu to configure your game's ID.

If you are working on a singleplayer game and want to grant trophies or update the player's leaderboard scores, you will also need to configure a signing key. If you are working on a dedicated server for a game use an API key instead. These can be created from within the "API" tab of your game's developer panel on Ezcha Network.

Usage

Singleplayer/Client-side

Authentication

Before trying to grant any trophies or updating any leaderboard scores, you must first authenticate the user. You would typically do this at the start of the game. Upon successful completion information about the current user can be accessed at Ezcha.client.user.

func do_auth() -> void:
	var success: bool = await Ezcha.client.authenticate()
	
	# Error handling
	if (!success):
		print("Failed to authenticate user!")
		return
	
	# Authentication successful
	print("Authenticated as %s!" % [Ezcha.client.user.name])

You can also use signals instead of await if preferred.

func do_auth() -> void:
	Ezcha.client.authentication_completed.connect(_on_authentication_completed)
	Ezcha.client.authenticate()

func _on_authentication_completed(success: bool) -> void:
	# Error handling
	if (!success):
		print("Failed to authenticate user!")
		return
	
	# Authentication successful
	print("Authenticated as %s!" % [Ezcha.client.user.name])

Granting a trophy

func _on_epic_accomplishment() -> void:
	Ezcha.client.grant_trophy("TROPHY_ID_GOES_HERE")

Updating a leaderboard score

func complete_level(final_score: int, cheese_consumed: int) -> void:
	# Set a score to a fixed value
	# (When there is an existing score the new one will only be saved if its an improvement)
	Ezcha.client.update_score("LEVEL_SCORE_LEADERBOARD_ID", final_score)
	
	# Add points to a total score
	Ezcha.client.update_score("CHEESE_CONSUMED_LEADERBOARD_ID", cheese_consumed, EzchaLeaderboardsAPI.UpdateMode.ADD)

Please note that for leaderboards with time elapsed formatting the submitted score should be in milliseconds, not seconds which many of the time functions built into Godot will return.

func _on_speedrun_completed(time_elapsed: float) -> void:
	# This assumes time_elapsed is a float representing seconds.
	var milliseconds: int = roundi(time_elapsed * 1000.0)
	Ezcha.client.update_score("SPEEDRUN_LEADERBOARD_ID", milliseconds)

Server-side

Authentication

When making a multiplayer game you should validate sessions server-side as players connect. This is done by having the client send the server its session token. In the server you will need to create an instance of the EzchaServerPlayer class instead of using the client helper. The client can get its session token with the Ezcha.client.get_session_token() function after local authentication.

var player_map: Dictionary = {}

@rpc("any_peer", "call_remote", "reliable")
func rpc_auth(session_token: String) -> void:
	var peer_id: int = multiplayer.get_remote_sender_id()
	
	# Block if user has already authenticated
	if (player_map.has(peer_id)):
		return

	var player: EzchaServerPlayer = EzchaServerPlayer.new()
	var success: bool = await player.authenticate(session_token)
	
	# Error handling
	if (!success):
		print("Failed to authenticate peer %s!" % [peer_id])
		return
	
	# Authentication successful
	player_map[peer_id] = player
	print("Peer %s authenticated as %s!" % [peer_id, player.user.name])

Granting a trophy

var score_map: Dictionary = {}

@rpc("any_peer", "call_remote", "reliable")
func rpc_button_pushed() -> void:
	var peer_id: int = multiplayer.get_remote_sender_id()
	
	# Block unauthenticated players
	if (!player_map.has(peer_id)):
		return
	
	# Set initial value in map if missing
	if (!score_map.has(peer_id)):
		score_map[peer_id] = 0
	
	# Increment score
	score_map[peer_id] += 1
	
	# Grant a trophy when the player reaches 100 points
	if (score_map[peer_id] == 100):
		player_map[peer_id].grant_trophy("TROPHY_ID_GOES_HERE")

Updating a leaderboard score

func _on_peer_disconnected(peer_id: int) -> void:
	# Skip if user has not authenticated
	if (!player_map.has(peer_id)):
		return
	
	# Submit score
	if (score_map.has(peer_id)):
		player_map[peer_id].update_score("LEADERBOARD_ID_GOES_HERE", score_map[peer_id])
		score_map.erase(peer_id)
	
	player_map.erase(peer_id)

API Wrappers

Listing trophies

func print_trophies() -> void:
	# Get the game's ID
	var game_id: String = Ezcha.get_game_id()
	
	# Request the information
	var trophy_resp: EzchaTrophyMetaListResponse = await Ezcha.games.get_trophies(game_id)
	
	# Error handling
	if (!trophy_resp.is_successful()):
		print("Failed to fetch trophies: %s (%s)" % [
			trophy_resp.get_error(),
			trophy_resp.get_status()
		])
		return
	
	# Print a list with the name and ID of each trophy
	for trophy: EzchaTrophyMeta in trophy_resp.trophies:
		print("%s (ID: %s)" % [
			trophy.name,
			trophy.id
		])

Listing leaderboard scores

func print_leaderboard(leaderboard_id: String, page: int = 1) -> void:
	# Request the information
	var entries_resp: EzchaPaginatedLeaderboardEntryListResponse = await Ezcha.leaderboards.get_entries(leaderboard_id, page)
	
	# Error handling
	if (!entries_resp.is_successful()):
		print("Failed to fetch leaderboard entries: %s (%s)" % [
			entries_resp.get_error(),
			entries_resp.get_status()
		])
		return
	
	# Print a list with the username and score of each entry
	for idx: int in entries_resp.entries.size():
		var entry: EzchaLeaderboardEntry = entries_resp.entries[idx]
		var ranking: int = (entries_resp.page - 1) * entries_resp.items_per_page + idx + 1
		print("#%s. %s %s" % [
			ranking,
			entry.user.name,
			entry.score
		])