In-Game Leaderboards

In-Game Leaderboards

10 min

A leaderboard displays information for players in a game like their scores, currency, or the fastest time in a race.

Setting Up the Leaderboard

The script in this tutorial will create a leaderboard that stores and displays a player’s gold amount, but it can be customized for different games.

Whenever a player enters the game, they’ll need to be added to the leaderboard along with code for tracking their individual stats.

  1. In the Explorer, under ServerScriptService, create a new script named PlayerSetup.
  2. In the script, add a function named onPlayerJoin() with a parameter named player.
  1. In onPlayerJoin(), create a variable named leaderstats as a new Folder instance. All the stats for the player will be stored in this folder.
  1. Name the folder leaderstats and parent it to the player. If the folder is not named leaderstats, Studio won’t know to create a leaderboard.
  1. After the closing end of the function, connect onPlayerJoin() to the Players|PlayerAdded event. Whenever a player joins the game, the onPlayerJoin() function will run.
Don't Test Yet

If you test the project now, you won’t see a leaderboard. This is because the leaderboard doesn’t yet have any stats to display.

Showing Player Information

Leaderboards use values to store and display player statistics. This script will show a player’s gold using an IntValue, a placeholder for a number.

  1. In onPlayerJoin(), under leaderstats.Parent = player, create a new variable named gold as a new IntValue instance.

A leaderboard can use IntValue, BoolValue, IntConstrainedValue, NumberValue, StringValue, and DoubleConstrainedValue.

  1. Type gold.Name = "Gold". This is the name that will appear in the leaderboard.
  1. On a new line, type gold.Value = 0. This makes it so players don’t start with any gold.
Using .Value

While variables are normally changed using = as in myNumber = 10, an IntValue is changed using its Value property, like myIntValue.Value = 10.

  1. Type gold.Parent = leaderstats. This parents the IntValue for gold to leaderstats.
  1. Play your game and notice that a leaderboard appears in the top right.
  • Make sure that .Value is capitalized.
  • Make sure that the variable for the IntValue is parented to the leaderboard like gold.Parent = leaderstats.

Leaderboards Don't Save Data

If a player leaves a game, they’ll lose any information in their leaderboard. To learn how to save data between player sessions, see Articles/Saving Player Data|Saving Player Data.

Final Leaderboard Script

  • points
  • leaderboard
  • stats