Get started with Leaderboards#

The first step in using Leaderboards is to learn how to implement the feature. This section describes how to set up Leaderboards for your project.

Unity Cloud Dashboard#

You can set up and manage Leaderboards in the Unity Cloud Dashboard:

1. Go to cloud.unity.com.
2. Select the Products tab from the sidebar.
3. Under Community, go to Leaderboards and select Launch.

When you launch Leaderboards for the first time, this adds Leaderboards to the Shortcuts section on the sidebar and opens the Leaderboards Overview.

You can use the Unity Cloud Dashboard to create and manage your leaderboards and view their entries.

Unity SDK installation and setup#

The Leaderboards SDK requires Unity 2020.3.0 or newer.

Install Leaderboards SDK#

You can install the Package through the Unity Editor.

Navigate to Window > Package Manager and select Unity Registry in the Packages dropdown on the top left. You can either:

• Search for Leaderboards in the search bar on the top right.
• Add the package by name. Open the dropdown indicated by +, and select "Add package by name...". Search the SDK package ID, "com.unity.services.leaderboards", without its version.

After installation the Leaderboards SDK is available in Unity scripts from the Unity.Services.Leaderboards namespace:

C#

using Unity.Services.Leaderboards;

Install Authentication SDK#

The Leaderboards package relies on the Authentication package. The Unity Authentication service creates an account to persist player scores where you can use anoynymous sign-in or platform-specific authentication.

The Authentication package is installed as a dependency when you install the Leaderboards package. For information on installing packages manually, refer to Install a package from a registry.

After installation the Authentication SDK is available in Unity scripts from the Unity.Services.Authentication namespace:

C#

using Unity.Services.Authentication;

Link your Unity project#

Once installed, the Authentication package prompts you to link your Unity project to a Unity Game Services Project ID, as demonstrated below. Follow the instructions in the prompt on the screen to link your project.

If you do not see this prompt, follow these steps to link your Unity project to a Project ID:

• In the Unity Editor, select Edit > Project Settings....
• Select Services,
  • Sign in if you have an Unity ID.
  • Otherwise, select Create a Unity ID.
• Select your project.
• Select Link.

Initialize the SDKs and authenticate the player#

You must initialize the Leaderboards SDK and its dependencies from inside a Unity script lifecycle callback before use. The following example uses the Awake callback. This is done by initializing all installed services via the Core SDK by calling await UnityServices.InitializeAsync();, available from the Unity.Services.Core namespace.

After the SDK initialization is complete, the player is authenticated. The following example uses anonymous authentication to create an anonymous account for the player to persist their scores. Other methods of authentication are available as outlined in the Unity Authentication documentation.

C#

using UnityEngine;
using Unity.Services.Core;
using Unity.Services.Authentication;

public class LeaderboardsSample : MonoBehaviour
{
  private async void Awake()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }
}

Next steps#

After completing the above steps the Leaderboards SDK is now ready to use from the Unity.Services.Leaderboards namespace. Review the features, SDK documentation, and the SDK sample to find out more about the Leaderboards feature set and how to use them.

Leaderboards in the UGS CLI#

The Unity Gaming Services (UGS) command line interface provides a scalable and automatable alternative to the Unity Cloud Dashboard and improves your team's workflows and productivity. The CLI is used to manage, test and deploy your Leaderboards configuration.

See the documentation on how to install and use the CLI.

Deploy a Leaderboards configuration#

To make your Leaderboards configurations accessible to the game client, you must deploy the configuration to the Leaderboards service.

Refer to write configuration to learn more about script deployment.

Configure the UGS CLI#

Follow the steps below to get stated with the UGS CLI:

1. Install the UGS CLI.

2. Configure your Project ID and Environment as such:
   ugs config set project-id <your-project-id>
ugs config set environment-name <your-environment-name>

3. Configure a Service Account with the required roles for Leaderboards and environments management. Refer to Get Authenticated.

Deploy the script#

Run the following command:

ugs deploy <path-to-configuration-file>

Leaderboards REST API#

Developers that do not use Unity can access APIs via web endpoints or REST APIs. REST APIs provide more flexibility and allow you to automate your workflows by using your favorite language and game development engine.

The Leaderboards service provides the following REST APIs:

• Leaderboards Player API for performing player actions (e.g. submitting a score or fetching scores).
• Leaderboards Admin API for performing admin actions (e.g. creating or updating a leaderboards, deleting or resetting scores) and is also used to perform player actions on behalf of a player.

Leaderboards Authoring#

This module allows users to author, modify, and deploy Leaderboard configuration assets directly from the Unity Editor.

NOTE: Leaderboards Authoring is only supported on Unity 2021.3 and above.

Deployment Window#

The Deployment Window is a core feature of the Deployment package.

The purpose of the Deployment Window is to allow all services to have a single cohesive interface for Deployment needs.

The Deployment Window provides a uniform deployment interface for all services. It allows you to upload cloud assets for your respective cloud service.

For more information, consult the com.unity.services.deployment package documentation.

Create Leaderboards Assets#

Use the right click menu in the Project window to create a Leaderboard asset.

The Deployment Window automatically detects these files to be deployed at a later time.

For more information on how to create and modify Leaderboards Assets, please see the Leaderboards assets documentation.

Additional resources#

• Unity Cloud Dashboard
• Package Manager
• Unity Authentication