PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience

In-Game Leaderboards

In-Game Leaderboards

Nov 09 2018, 1:57 PM PST 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.
local function onPlayerJoin(player)

end
  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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")

end
  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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player
end
  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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player
end

game.Players.PlayerAdded:Connect(onPlayerJoin)
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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player

	local gold = Instance.new("IntValue")
end

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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player

	local gold = Instance.new("IntValue")
	gold.Name = "Gold"
end
  1. On a new line, type gold.Value = 0. This makes it so players don’t start with any gold.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player

	local gold = Instance.new("IntValue")
	gold.Name = "Gold"
	gold.Value = 0
end
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.
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player

	local gold = Instance.new("IntValue")
	gold.Name = "Gold"
	gold.Value = 0
	gold.Parent = leaderstats
end
  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

-- In 'ServerScriptService', add this into a script named 'PlayerSetup'
local function onPlayerJoin(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player

	-- Display an 'IntValue' on leaderboard
	local gold = Instance.new("IntValue")
	gold.Name = "Gold"
	gold.Value = 0
	gold.Parent = leaderstats
end

-- Run 'onPlayerJoin()' when the 'PlayerAdded' event fires
game.Players.PlayerAdded:Connect(onPlayerJoin)
Tags:
  • points
  • leaderboard
  • stats