# Introduction

In this guide, you’ll learn…

- What are Client Leaderboards?

- Configuring Client Leaderboards

* * *

# Configuring Client Leaderboards

Client Leaderboards allow you to create competitive ranking systems within your game, featuring both players and bots. You can configure bot participation to enhance player engagement. Additionally, leaderboard rewards can be customised based on ranking positions.


Scoring rules and visual effects are possible for the leaderboards, however these are configured via leaderboard parameters. You need to contact the Hawk Team to configure any parameter. The visuals control needs to be carefully discussed with the client developers and/or react team to ensure that it will not affect the application performance.

In your game, navigate to **Events \> Client Leaderboards**.

1. Click **[+ Add Client Leaderboard]** on the upper right corner.

2. Give your new leaderboard a name, and assign an availability.

3. Under **Leaderboards Configuration,** add the number of bots that will participate in the leaderboard.
You can input a number between 1 and 1000.

You can assign names to leaderboard bots if your application supports this feature. This functionality is handled through Game Server, where a CSV file with bot names is first uploaded to **Files** , and then selected in **Game Settings**. Please note that availability may vary depending on your app’s configuration.

1. Enable/Disable the **Win Flow Animation** toggle switch.
You can choose whether to enable or disable the Win Flow Animation. When enabled, this setting is passed to the client, which may use it to trigger animations such as when a player climbs the leaderboard or earns a new rank. When disabled, the client may skip these animations and simply update the player’s status or position visually.

2. Leaderboard Configuration Parameters are automatically populated in the Leaderboard Configuration section with default values.

3. You can modify the value of the parameters. The rest of the fields remain non-editable.

4. Next, to configure the score of the bots, create a Bot Set.

5. Click **[+ Add Bot Set]**, and input the number of bots, and a minimum and maximum range.
Hawk serves the minimum/maximum value to the client. The Client assigns the random score based on the ranges configured.
The range you can input cannot be lower than -10000 and bigger than 10000.

6. Bots Configuration Parameters are populated in all Bots Sets with default values.

7. You can modify the value of the parameters. The rest of the fields remain non-editable.

8. To create the rewards for players who finish the Event, click **[+Add Rank]**, and select a game item to provide as a reward.
You can add more than 1 reward, and you can also create more than one Rank. Rank represents rewards for different positions in the leaderboard and includes rewards list per each position. You can change the rank with arrows on the side.

Please remember that the sum of the number of bots in all sets **must be equal** to the number of bots in Leaderboard configuration.

**Leaderboards** can be used across any game to rank players based on performance in a configured event. In Hawk, leaderboards are defined at the event level, where you specify the tracked activity, scoring method, ranking logic, and reward distribution.

To understand how the client processes leaderboard data from Hawk, refer to the example below. It illustrates how the client consumes and displays leaderboard information based on the event’s configuration.

- Leaderboard event becomes available when the player reaches a specific progress milestone, configured in **"Level to unlock Leaderboard"** Game Setting.

- Event will not appear if the **“New Win Flow”** toggle is OFF in Game Settings.

- When the event is active for a player:

- Player’s current score is shown and can be manually edited in the Debug Menu.

- On the first completion of a new level, player earns +1 point toward the leaderboard.

- Replaying levels does not affect leaderboard score.

- At the start of the event, leaderboard order is randomised until players make progress.

- Bots progress using a natural-looking algorithm once the event starts (even before player sees the intro).

- Some bots may be paused randomly for a random period.

- If multiple bots have the same score, their ranks are randomly ordered.

- If the player and a bot have the same score, the player is ranked higher.

- When the event ends, positions are finalised based on current scores.

- If the player finishes on any of the configured rankings, a reward is given based on Hawk \> Rewards settings. If fewer ranks are configured then the ranks the player reaches, fallback logic from defaults will apply.

- Rewards are delivered silently (no UI feedback for now).

- All standard game items are supported as rewards.

## **Selecting Client Leaderboards as an Activity**

- Users can select the activity type: **"Client Leaderboards"** while configuring an event.

- Once selected, an **Activity Configuration** dropdown allows choosing from the configured client leaderboards.