13 Player Stats
Kyra Ma; Hasan Malik; and Rutwa Engineer
Learning Objectives
- Understand Instances & player stats.
- Learn about leaderstats and value objects for players.
- Learn to use the PlayerAdded event
- Learn to use common value instance types (
IntValue,StringValue, etc.) and their.Name,.Value, and.Parentproperties.
Introduction
What are Player Stats?
In many Roblox games, players earn rewards, level up, collect items, or progress through the game in unique ways. To track this information, developers use player stats. These stats can include anything you want to keep track of for each individual player, such as how many coins they’ve earned, how many levels they’ve completed, how much health they have, or how many enemies they’ve defeated.
Player stats are custom pieces of data that are attached to a player object when they join the game. These stats can be changed throughout gameplay as players achieve goals or interact with your game. For example, if a player touches a coin, their “Coins” stat can go up by 1. If they complete a level, their “Level” stat can increase. Oftentimes, you see this information on the top right corner of a roblox game beside your player’s name on a leaderboard!
These stats are essential for gameplay mechanics, player progression, and user experience. Stats also allow developers to save and load progress between sessions using Roblox’s DataStore system. Before we get to that, we need to understand how to create and attach these stats.
Instances
To understand player stats, you first need to understand Instances.
In Roblox, everything you see or interact with is an object, and all these objects are technically called Instances. An Instance is like a building block or an object that makes up your game world. Parts, GUIs, Scripts, Sounds, Values, and even Players themselves are all instances of different classes.
Roblox uses this system to keep everything modular and organized. Whether you’re placing a part into the workspace or creating a health bar for a character, you’re working with an Instance.
You can create new instances using the function Instance.new(). This function takes a string argument, which is the type of instance you want to create. In this case, we’re making a physical part. There are also invisible instances like “Folder” or “IntValue” that we use for organizing or storing data.
local newPart = Instance.new("Part")
This code creates a new part (a block or object in the world). But it won’t appear in the game yet! It exists in memory but hasn’t been placed in the game hierarchy. To make it visible, you must set its .Parent to something visible like the Workspace. We can also change the name of the part inside this parent folder.
newPart.Name = "NewInstancePart"
newPart.Parent = game.Workspace
Creating Instances In-Game
When scripting in Roblox, you often need to create instances dynamically — meaning while the game is running — in response to player actions or events. For example, when a new player joins the game, we can listen for that event and then generate folders or stats specifically for them.
This is done using the PlayerAdded event:
game.Players.PlayerAdded:Connect(function(player)-- Code runs when player joinsend)
Inside this function, we can create and parent new instances (like leaderstats or IntValue) to the player object. This is very important: without parenting the new instance to the correct place, it won’t function properly or may not even be visible.
When creating stats, the general approach is:
General Approach
- Create a Folder to hold all stats
- Name it “leaderstats” (this name is required for Roblox to show it on the leaderboard).
- Parent it to the player
- Create value instances (like IntValue), name them, and parent them to the folder
Data Types as Instances
To store actual data like numbers or text, we use Value instances. These are special objects that can hold a single value and be stored inside folders like leaderstats.
Here are some common types:
- IntValue: holds whole numbers (e.g., 10, 500)
- NumberValue: holds decimals or floating point numbers (e.g., 5.25, 100.01)
- StringValue: holds text strings (e.g., “Hello”, “Level 1”)
- BoolValue: holds true or false (true or false)
Each value has three important properties:
3 Important Properties
.Name: the name of the stat.Value: the actual data being stored.Parent: where the value is stored in the game hierarchy
For example, let’s create a Coins stat for our game:
Example
local coins = Instance.new("IntValue")
coins.Name = "Coins"
coins.Value = 0
coins.Parent = leaderstats
This code creates a stat called “Coins” that starts at 0 and is stored in the leaderstats folder. It will show up on the leaderboard if placed correctly.
Players Folder
Another important thing to note: we are moving away from the Workspace folder and into the Player folder! When a player joins the game, Roblox automatically creates a Player object for them inside game.Players. This object holds everything specific to that player.
Inside the Player object, you will find several built-in folders:
- Backpack: Tools the player has
- StarterGear: Items saved to respawn with
- PlayerGui: User Interface elements like health bars or menus
- PlayerScripts: Local scripts running just for that player
As developers, we usually add one more folder: leaderstats, which we use to store the player’s visible stats. It’s very important to understand that this Player object is not in game.Workspace. That’s where the player’s character model is. The Player object is in game.Players.
So:
Key Takeaway
game.Players: where we attach statsgame.Workspace: where we control their avatar (e.g., position, animations)
Creating Leaderboards with leaderstats
Finally, to show stats on the top-right leaderboard, you must follow a specific structure. Roblox looks for a folder named exactly “leaderstats” inside the Player object. Any value inside this folder with a Value property will be shown on the leaderboard.
Here’s the full code to set up a basic leaderboard with a Coins stat:
Example
game.Players.PlayerAdded:Connect(function(player) local leaderstats = Instance.new("Folder") leaderstats.Name = "leaderstats" leaderstats.Parent = player local coins = Instance.new("IntValue") coins.Name = "Coins" coins.Value = 0 coins.Parent = leaderstatsend)Let’s break this down line by line!
game.Players.PlayerAdded:Connect(function(player)
This line sets up an event listener.
game.Playersis the service that holds all the players currently in the game..PlayerAddedis an event that fires whenever a new player joins.:Connect(function(player)means we’re writing a custom function that runs every time the event happens.- The
playerparameter refers to the specific player who just joined.
Key Takeaway
Essentially, the first line means: When someone joins the game, do the following.
local leaderstats = Instance.new("Folder") leaderstats.Name = "leaderstats" leaderstats.Parent = playerNext, we’re creating a new folder object. Most importantly, we’re changing the name to leaderstats. This specific name is recognized by Roblox’s system. If you name it something else, the stats won’t appear on the leaderboard. The last line in this second moves the folder into the player’s instance.
local coins = Instance.new("IntValue") coins.Name = "Coins" coins.Value = 0 coins.Parent = leaderstats
Here, we’re making our actual coin variables to show up onto the leaderboard. Since we’re tracking the number of coins, we’re using an IntValue, which only holds whole numbers. A few key notes here: we need to set the parent to leaderstats for it to show up on the leaderboard, and we set the default value of coins as 0 when you first join the game.
To take things one step further, we can also start auto-incrementing our stats as well! For example, give a player 1 coin every second. You can do this using a loop:
game.Players.PlayerAdded:Connect(function(player) local leaderstats = Instance.new("Folder") leaderstats.Name = "leaderstats" leaderstats.Parent = player local coins = Instance.new("IntValue") coins.Name = "Coins" coins.Value = 0 coins.Parent = leaderstats while true do task.wait(1) coins.Value = coins.Value + 1 endend)Congratulations—you can now manage player stats in Roblox Studio!
