Home

How to get started

There are a few simple steps to getting your leaderboard up and running. This will only take a few minutes, but using the demo code, a few seconds, though either way you may want to read through this to see how it works.

Installing and enabling addon

To get started, just install the addon either here or in the Godot editor asset library, then enable it in Project > Project Settings > Plugins and enable EasyLeaderboards.

Adding node to scene

Next, you can go to whatever scene you want to add the leaderboard to and add a node. Search for the node "BaseLeaderboard" and add it to your scene. Alternatively, you can open the scene leaderboardTemplate.tscn, which is almost the same thing, but you can change it to whatever you like. Resize and move the BaseLeaderboard node to where and what you like, and change any settings to what you prefer.

Setting up a function for when we receive data

Now go to a main script for the scene. If you don't have one, make a new one. In the _ready() function, connect the signal, Leaderboard.recieved_data, (Leaderboard is a autoload singleton that is automatically added when you enable the addon, and the signal, recieved_data is emitted every time a request to the database is completed, with the response. Also, sorry, but I spelled "received" wrong in the code, so you will have to account for that until I fix it.) to a function, where in that function you will handle the data received. The data that is received is in the form of a dictionary.

In the function connected to Leaderboard.recieved_data, perform a if statement to check if the response contains the key "Scores" then, update the visible leaderboard by setting it's scores property to the list of scores we received.
Here is a example of this function we created:

func recieved_data(data): 
	if "Scores" in data: #This means that it is a list of scores
		
		#Put the scores onto the leaderboard.
		$BaseLeaderboard.scores = data["Scores"]

Ok, now we are setup, so we can just call a few functions to get this working.

Setting a leaderboard

After connecting the signal in the _ready() function, call the function Leaderboard.set_leaderboard(NameOfLeaderboard), which will tell the Leaderboard script what leaderboard you are trying to add scores to, and enable other thing specific to the leaderboard too.

Making a new leaderboard

There are two ways to make a new leaderboard. The first is by going to adpgames.com/leaderboards or themaker6.pythonanywhere.com/leaderboards, and the second is in-editor by running two more lines of code.

First approach: Web

Let's start with the first approach. By going to either of those URLs, you will see a page with a textbox and a two buttons. This page allows you to see a leaderboard already created, but we need to make one first. Do this by clicking "Create New Leaderboard" then entering the desired name of the leaderboard you want to create in the text box. The dropdown above the box allows you to change the sorting order of the scores, so set that to whatever you need. Now, all we need to do is click "Create Leaderboard" and we are done.

Second approach: With code

Now, for the second approach. We can check if a leaderboard exists by running: await Leaderboard.leaderboard_exists(NameOfLeaderboard) Keep that last function in mind for later. There is also a function to create a leaderboard, which is Leaderboard.create_leaderboard(NameOfLeaderboard). So, then we can run this code to check if a leaderboard with a certain name exists, and if it doesn't, create a new leaderboard with that name:

if not await Leaderboard.leaderboard_exists(NameOfLeaderboard):
	Leaderboard.create_leaderboard(NameOfLeaderboard)

If you would like a custom sorting, you can do Leaderboard.create_leaderboard(NameOfLeaderboard, Sorting) "Sorting" can be "Ascending" "Descending" or "NoChange"

This will do the same thing as if we did the first approach.

Getting scores from our leaderboard

To get our scores from the leaderboard, we can call Leaderboard.get_scores(). This requires we have a leaderboard set.

When we call this, it will emit the signal, Leaderboard.recieved_data, which then in turn call our function we set up earlier. Because of the way we set up the function, every time we call Leaderboard.get_scores() our leaderboard will update automatically.

The scores are returned sorted in the order set when you created the leaderboard.

Adding scores

Scores can be added essentially effortlessly by calling Leaderboard.add_score(Name, Score). "Name" should be the name recorded for the score, and "Score" should be the score they got. The name must be a string (because Godot wouldn't understand otherwise) and the score can be string, int, or float.

Call this function whenever you need to add a score to your leaderboard.

Note: Integers and Floats will be sorted according to the leaderboard's set sorting, but strings will not be sorted, and will come before numbers when you get the scores. However, even though the string "123 abc" is technically a string, it is sorted with the numbers, not at the beginning like the strings.

Congratulations!

Congratulations! You now have a working leaderboard. If you ran into any issues, problems, bugs, would like to suggest a feature, or have feedback, raise a issue on this repository.