Nakama Leaderboards Sample Project

The official sample project for the Nakama Leaderboards system. Built with minimal boilerplate so you can easily copy the code into your project and adapt the scripts and UI to suit your game.

Features

• Create weekly resetting leaderboards or global persistent leaderboards.
• Real-time score updates.
• Different ways to submit scores (best, set, increment, decrement).
• Primary and sub-scores for tie-breaking.
• Built-in account switcher for quick multi-account testing.

Installation

The installation steps and resulting folder structure will vary depending on if you downloaded the project from Github or the Unity Asset Store.

The project connects to our demo server so you can see the features in action immediately.
Note: The server is reset on the 1st of every month at 00:00 UTC.

Folder structure

Assets/
├── UnityNakamaLeaderboards/
    ├── HeroicUI/           # UI assets and styling
    ├── Scripts/            # Main project code
    ├── UI/                 # UI Builder files
    └── ...                 # Everything else
├── Packages/               # Contains the Nakama Unity package

Code overview #

Main controller (NakamaLeaderboardsController.cs) #

Handles all core operations including calling the Nakama Leaderboards API.

Authentication

1
2

// Connects to Nakama server and authenticates with device ID
await AuthenticateWithDevice();

Leaderboard operations

1
2
3
4
5
6
7
8

// Fetch leaderboard records
var result = await Client.ListLeaderboardRecordsAsync(Session, leaderboardId, ...);

// Submit a new score
await Client.WriteLeaderboardRecordAsync(Session, leaderboardId, score, subscore, ...);

// Delete player's record
await Client.DeleteLeaderboardRecordAsync(Session, leaderboardId);

Record view (LeaderboardRecordView.cs) #

Simple class that displays individual leaderboard entries:

1
2
3
4

public void SetLeaderboardRecord(IApiLeaderboardRecord record)
{
    // Shows player rank, username, score, and subscore
}

Account Switcher

The Account Switcher lets you explore the project as different players without managing multiple builds. Use it to submit scores from different accounts.

How to use:

1. Open the Account Switcher panel (Tools > Nakama > Account Switcher).
2. Select different accounts from the dropdown to switch between up to four test users.
3. Each account is automatically created the first time you select it.

Key points:

• Only works while your game is running in Play mode.
• Usernames will display in the panel after switching to an account for the first time.

Setting up your own Nakama server

While this project works with our demo server, you'll want to set up your own Nakama instance to customize the features and configurations. Using Docker, you can get up and running in minutes.

Read the full setup guide: Nakama Installation Docs

Connect this Unity Project to your Server

After installing Nakama and running it locally, edit these settings in the Unity Editor to connect it to your server:

1. Select the main controller component from the scene hierarchy panel.
2. Open the Inspector tab.
3. Look for the field inputs under Nakama Settings and replace them with the following:
   1. Scheme: http
   2. Host: 127.0.0.1
   3. Port: 7350
   4. Server Key: defaultkey

In the controller script, update the leaderboard IDs:

1
2

private const string WeeklyLeaderboardId = "your_weekly_leaderboard";
private const string GlobalLeaderboardId = "your_global_leaderboard";

Additional resources

• Nakama Leaderboards concept guide
• Nakama Unity SDK guide
• Community forum