Current latest stable version of Leaderboard Creator is v2.81
-
Include this
usingstatement in your script where you want to handle leaderboards -
- Where is the data of the leaderboards stored?
- What if I lost my leaderboard or its secret key?
- My leaderboard entry keeps getting overridden / I can only upload one entry. Why is that?
- Does the score field in the entry store integers only?
- Why is my leaderboard "frozen"?
If you prefer to watch a video tutorial on how to integrate your leaderboard into your project, click the image below to watch it on YouTube:
Visit the itch.io page to download the Unity package containing Leaderboard Creator.
using Dan.Main;To add your leaderboard to your project, follow these steps:
- Once you import the Unity package, click the Leaderboard Creator button on the toolbar
- Press Enter New Leaderboard and enter the credentials for your leaderboard
- Click Add Leaderboard then Save to C# Script
- You will now have a new C# script in your project that contains a reference to your leaderboard by its name
Note
For the rest of this documentation, we will refer to your leaderboard as YourLeaderboard. Replace this with the name of your actual leaderboard.
• To get the entries in your leaderboard, call this function:
Leaderboards.YourLeaderboard.GetEntries(string publicKey, Action<Entry[]> callback, Action<string> errorCallback[optional])• If the function is called and the request is successful, the callback is called, an array of Entry objects is returned.
An Entry object contains:
[System.Serializable]
public struct Entry
{
public string Username { get; set; }
public int Score { get; set; }
public int Rank { get; set; }
public ulong Date { get; set; }
public string Extra { get; set; }
...
}Note
- Date - Unix timestamp of the last time the entry was uploaded/modified
- Extra - A string value for metadata, you can use this however you like depending on your game. But make sure that the length of the string does not go over 100, otherwise it will get truncated and not all your data will be saved.
• This function also has other overloads that can give you more control over the querying of your leaderboard's entries:
Leaderboards.YourLeaderboard.GetEntries(string publicKey, bool isInAscendingOrder, Action<Entry[]> callback, Action<string> errorCallback[optional])
Leaderboards.YourLeaderboard.GetEntries(string publicKey, LeaderboardSearchQuery searchQuery, Action<Entry[]> callback, Action<string> errorCallback[optional])
Leaderboards.YourLeaderboard.GetEntries(string publicKey, bool isInAscendingOrder, LeaderboardSearchQuery searchQuery, Action<Entry[]> callback, Action<string> errorCallback[optional])Note
- isInAscendingOrder - If true, the entries are sorted in ascending order, otherwise they are sorted in descending order.
- searchQuery - A
LeaderboardSearchQueryobject that can be used to filter the entries you want to get. - callback - A function that is called when the request is successful, returning an array of Entry objects.
- errorCallback - A function that is called when the request is unsuccessful.
• A LeaderboardSearchQuery object consists of:
public struct LeaderboardSearchQuery
{
public int Skip { get; set; } //amount of entries to skip
public int Take { get; set; } //amount of entries to take
public string Username { get; set; }
public TimePeriodType TimePeriod { get; set; }
}Important
- You do not have to fill out all of these fields in the query.
- There are several functions that can generate a
LeaderboardSearchQueryfor your exact needs:
LeaderboardSearchQuery.Paginated(int skip, int take)
LeaderboardSearchQuery.ByUsername(string username)
LeaderboardSearchQuery.ByUsernamePaginated(string username, int prev, int next)
LeaderboardSearchQuery.ByTimePeriod(TimePeriodType timePeriod)
LeaderboardSearchQuery.ByTimePeriodPaginated(TimePeriodType timePeriod, int skip, int take)
LeaderboardSearchQuery.ByUsernameAndTime(string username, TimePeriodType timePeriod)Note
TimePeriodType is an enum that consists of the following values:
- AllTime - All entries
- Today - Entries from today
- ThisWeek - Entries from this week
- ThisMonth - Entries from this month
- ThisYear - Entries from this year
This enum comes from a namespace called Dan.Enums, so you will need to include it in your script.
• To upload a new entry into your leaderboard, call this function:
Leaderboards.YourLeaderboard.UploadNewEntry(string username, int score, Action<bool> callback, Action<string> errorCallback[optional])• To upload a new entry, with an extra field, into your leaderboard, call this function:
Leaderboards.YourLeaderboard.UploadNewEntry(string username, int score, string extra, Action<bool> callback, Action<string> errorCallback[optional])• To delete the player's entry, call this function:
Leaderboards.YourLeaderboard.DeleteEntry(Action<bool> callback[optional], Action<string> errorCallback[optional])Note
Here are some of the parameter descriptions:
- callback - A function that is called when the request is successful, returning a boolean value.
- errorCallback - An optional function that is called when the request is unsuccessful.
Important
- If the player previously uploaded an entry, the new uploaded entry should override the old one if it has a higher score. This is intended behaviour, as it prevents players from spamming the leaderboard with lower scores. Read more about this in the FAQ section.
Here is an example of how you can display the entries in a list using Unity's UI system:
...
// A prefab containing a TextMeshPro component:
[SerializeField] private GameObject entryPrefab;
// This transform will be the parent of the instantiated prefabs
// Typically, this would be the "Content" object of a ScrollView
// You may want to add a VerticalLayoutGroup component to this object for easy and automatic alignment
[SerializeField] private Transform entryParent;
private void Start()
{
LoadEntries();
}
private void LoadEntries()
{
Leaderboards.YourLeaderboard.GetEntries(OnEntriesLoaded, OnError);
}
private void OnEntriesLoaded(Entry[] entries)
{
foreach (Entry entry in entries)
{
GameObject entryObject = Instantiate(entryPrefab, entryParent);
TextMeshProUGUI textObject = entryObject.GetComponent<TextMeshProUGUI>();
textObject.text = $"{entry.Rank}. {entry.Username} - {entry.Score}";
}
}
private void OnError(string error)
{
Debug.LogError(error);
}
...The Entry object contains a built-in method that can be used to check if the entry belongs to the player. We will build on the previous example to show how you can identify the player's entry:
private void OnEntriesLoaded(Entry[] entries)
{
foreach (Entry entry in entries)
{
GameObject entryObject = Instantiate(entryPrefab, entryParent);
TextMeshProUGUI textObject = entryObject.GetComponent<TextMeshProUGUI>();
textObject.text = $"{entry.Rank}. {entry.Username} - {entry.Score}";
// Returns true if the entry belongs to the player
bool isMine = entry.IsMine();
if (isMine)
{
textObject.color = Color.green;
}
}
}If you want to add suffixes to the rank numbers (e.g. 1st, 2nd, 3rd, 4th, etc.), the Entry object has a built-in utility method that can be used to get the rank suffix. Here is an example of how you can use it:
private void OnEntriesLoaded(Entry[] entries)
{
foreach (Entry entry in entries)
{
GameObject entryObject = Instantiate(entryPrefab, entryParent);
TextMeshProUGUI textObject = entryObject.GetComponent<TextMeshProUGUI>();
string rankSuffix = entry.GetRankSuffix();
textObject.text = $"{rankSuffix}. {entry.Username} - {entry.Score}";
// Returns true if the entry belongs to the player
bool isMine = entry.IsMine();
if (isMine)
{
textObject.color = Color.green;
}
}
}Leaderboards.YourLeaderboard.GetPersonalEntry(Action<Entry> callback, Action<string> errorCallback[optional])Note
Here are the parameter descriptions:
- callback - A function that is called when the request is successful, returning an Entry object.
- errorCallback - A function that is called when the request is unsuccessful.
Important
- If the player has not uploaded their entry, the callback will return an Entry object with a rank and score of 0.
Leaderboards.YourLeaderboard.GetEntryCount(Action<int> callback, Action<string> errorCallback[optional])Note
Here are the parameter descriptions:
- callback - A function that is called when the request is successful, returning the total count of entries in the leaderboard.
- errorCallback - A function that is called when the request is unsuccessful.
Want players to be able to submit more than one entry? Use this function to reset the player's entry, so they can submit a new one:
Leaderboards.YourLeaderboard.ResetPlayer(Action<bool> callback, Action<string> errorCallback[optional])Note
Here are the parameter descriptions:
- callback - A function that is called when the request is successful, returning the total count of entries in the leaderboard.
- errorCallback - A function that is called when the request is unsuccessful.
Important
- This function will only work correctly if the leaderboard's "Unique Usernames" setting is disabled.
- After this function is called, a player's previous entry cannot be edited nor deleted by the player themselves.
Want to disable logging for your leaderboard? Use the following line of code:
LeaderboardCreator.LoggingEnabled = false;Each entry in the leaderboard is identified by a unique identifier, which is assigned to the player upon authorization. By default, authorization occurs automatically upon the initialization of your game.
Using this identifier, the player can upload, edit, and delete their entry in the leaderboard. Without this identifier, the player will not be able to perform any of these actions. For security reasons, the player only has access to their own unique identifier, so they can only modify their own entry in the leaderboard.
Alternative way to use Leaderboard Creator functions
• To get the entries in your leaderboard, call this function:
LeaderboardCreator.GetLeaderboard(string publicKey, Action<Entry[]> callback)• This function also has other overloads that can give you more control over the querying of your leaderboard's entries:
LeaderboardCreator.GetLeaderboard(string publicKey, bool isInAscendingOrder, Action<Entry[]> callback, Action<string> errorCallback[optional])
LeaderboardCreator.GetLeaderboard(string publicKey, LeaderboardSearchQuery searchQuery, Action<Entry[]> callback, Action<string> errorCallback[optional])
LeaderboardCreator.GetLeaderboard(string publicKey, bool isInAscendingOrder, LeaderboardSearchQuery searchQuery, Action<Entry[]> callback, Action<string> errorCallback[optional])• To upload a new entry into your leaderboard, call this function:
LeaderboardCreator.UploadNewEntry(string publicKey, string username, int score, Action<bool> callback, Action<string> errorCallback[optional])• To upload a new entry, with an extra field, into your leaderboard, call this function:
LeaderboardCreator.UploadNewEntry(string publicKey, string username, int score, string extra, Action<bool> callback, Action<string> errorCallback[optional])• To delete the player's entry, call this function:
LeaderboardCreator.DeleteEntry(string publicKey, Action<bool> optionalCallback)LeaderboardCreator.GetPersonalEntry(string publicKey, Action<Entry> callback, Action<string> errorCallback[optional])LeaderboardCreator.GetEntryCount(string publicKey, Action<int> callback, Action<string> errorCallback[optional])LeaderboardCreator.ResetPlayer(string publicKey, Action<bool> callback, Action<string> errorCallback[optional])All the data is stored in a cloud-based database.
If you lose your leaderboard's secret key by accident but you still have your public key, contact me on Discord: @danqzq
Alternatively, you can email me at: dan@danqzq.games
There may only be one entry per one player. This is done to support features like name editing and deleting an entry in a safe way, such that other people don't mess around with other people's entries. If you do not want this, then disable "Unique Usernames" for your leaderboard and make use of the Leaderboards.YourLeaderboard.ResetPlayer() function during the callback from uploading an entry. Note that after this, a player's previous entry cannot be edited nor deleted by the player themselves.
Yes. If you want to store decimal numbers as the scores, you can either:
A. Before submitting an entry, multiply the score of the entry by 100, 1000 or etc. depending on amount of precision you want. When receiving entry data, divide each score by the same amount you multiplied the scores, and only then display the score for each entry.
B. Make use of the Extra field, for storing extra data, and perform manual sorting of the entries appropriately to your liking.
If an error is shown saying that your leaderboard is frozen, it is likely due to a high number of requests at the same time. You will be able to fetch the leaderboard entries, but new entries will not be submitted until the leaderboard will unfreeze, which should happen within 24 hours from the moment it entered a frozen state.
