Today we have released an update to the leaderboards documentation to add examples of how to add a new score and return scores with score metadata when using Unity Leaderboards, our cross platform solution for in-game leaderboards.
We had feedback that people were not clear on how to use this feature, so we’ve provided more explicit examples to show how you can use it as well as provided clarity on how features of leaderboards work when used together
As with Unity Cloud Save, you can pass a serializable class - or a simple Dictionary object - and it will be automatically seralized and stored with the score:
[Serializable]
public class ScoreMetadata
{
public string levelName;
public int timeTaken;
}
public async void AddScoreWithMetadata(string leaderboardId, int score)
{
var scoreMetadata = new ScoreMetadata { levelName = "LEVEL_01", timeTaken = 120 };
var playerScoreEntry = await LeaderboardsService.Instance
.AddPlayerScoreAsync(
leaderboardId,
score,
new AddPlayerScoreOptions { Metadata = scoreMetadata }
);
Debug.Log(JsonConvert.SerializeObject(playerScoreEntry));
}
To preserve backwards compatibility with older versions of the SDK, score metadata is not returned by default, you must explicitly request that it is included in the response when fetching scores:
public async void GetScoresWithMetadata(string leaderboardId)
{
var scoreResponse = await LeaderboardsService.Instance
.GetScoresAsync(
leaderboardId,
new GetScoresOptions { IncludeMetadata = true }
);
Debug.Log(JsonConvert.SerializeObject(scoreResponse));
}
Example use cases for score metadata might include what type of car someone was driving when a lap time was recorded, or what game mode or flags were active, or how many special items they collected.
Note: For non-score specific data that is player scoped, you can use Leaderboards in conjunction with Unity Cloud Save to store player profile data in the Public Access Class for Player Data.
Unity Leaderboards is supported by Unity Cloud Code and fires a Trigger when a leaderboard resets to support use cases like granting rewards based on ranking, or programmatically creating new leaderboards at runtime.
If you have any questions, or if there are any example use cases you would like to solve for we would really appreciate your feedback!
Best regards,
Iain Collins