35. leaderstats and value objects

Almost every Roblox game shows a scoreboard in the top-right corner: coins, points, wins. Roblox builds it automatically — if you set up the data right. The trick: value objects in a folder named leaderstats.

Value objects hold a single value

You have stored numbers and text in variables. Roblox also has Instances whose only job is to hold one value, living in the tree for the game to see:

Make one like any Instance, and read or change it through .Value:

local coins = Instance.new("IntValue")
coins.Name = "Coins"
coins.Value = 0
-- later:
coins.Value = coins.Value + 1

The leaderstats rule

The magic rule: if a Player has a child folder named exactly leaderstats, Roblox shows every value object inside it on the leaderboard, each object's Name becoming a column heading.

So a "Coins" score per player means:

Player
 └─ leaderstats   (a Folder)
     └─ Coins     (an IntValue, starting at 0)

Building it when a player joins

Players appear over time, so build their leaderstats in a PlayerAdded handler (Chapter 33), a Script in ServerScriptService:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local leaderstats = Instance.new("Folder")
    leaderstats.Name = "leaderstats"      -- the exact name matters
    leaderstats.Parent = player

    local coins = Instance.new("IntValue")
    coins.Name = "Coins"                  -- becomes the column heading
    coins.Value = 0
    coins.Parent = leaderstats
end)

Two names do all the work: the folder must be leaderstats, and the value object's name becomes the column. Get them right and the board appears.

Changing a score

Once the value object exists, scoring is one line. From a coin's touch handler, find the player's Coins and add:

local leaderstats = player:FindFirstChild("leaderstats")
local coins = leaderstats:FindFirstChild("Coins")
coins.Value = coins.Value + 1

FindFirstChild (Chapter 32) is the safe way into the tree: it returns nil instead of erroring when something is missing, so check it first.

Homework

The last homework of the book. Roblox snippets — write them, check solutions, try them in Studio.

Stuck or finished? Open the homework solutions page.