BadgeService

Show Deprecated

Not Creatable

Service

The BadgeService class provides information and functionality related to badges. Badges are used across the platform to recognize a player's achievements and activity. Upon awarding a badge to a player, it is added to their inventory and displayed on their profile page.

Code Samples

Awarding a Badge

1local BadgeService = game:GetService("BadgeService")
2local Players = game:GetService("Players")
3
4local BADGE_ID = 0
5
6local function awardBadge(player, badgeId)
7	-- Fetch badge information
8	local success, badgeInfo = pcall(function()
9		return BadgeService:GetBadgeInfoAsync(badgeId)
10	end)
11
12	if success then
13		-- Confirm that badge can be awarded
14		if badgeInfo.IsEnabled then
15			-- Award badge
16			local awardSuccess, result = pcall(function()
17				return BadgeService:AwardBadge(player.UserId, badgeId)
18			end)
19
20			if not awardSuccess then
21				-- the AwardBadge function threw an error
22				warn("Error while awarding badge:", result)
23			elseif not result then
24				-- the AwardBadge function did not award a badge
25				warn("Failed to award badge.")
26			end
27		end
28	else
29		warn("Error while fetching badge info: " .. badgeInfo)
30	end
31end
32
33local function onPlayerAdded(player)
34	awardBadge(player, BADGE_ID)
35end
36
37Players.PlayerAdded:Connect(onPlayerAdded)

Checking Earned Badges

1local BadgeService = game:GetService("BadgeService")
2local Players = game:GetService("Players")
3
4local badgeId = 00000000 -- Change this to your badge ID
5
6local function onPlayerAdded(player)
7	-- Check if the player has the badge
8	local success, hasBadge = pcall(function()
9		return BadgeService:UserHasBadgeAsync(player.UserId, badgeId)
10	end)
11
12	-- If there's an error, issue a warning and exit the function
13	if not success then
14		warn("Error while checking if player has badge!")
15		return
16	end
17
18	if hasBadge then
19		-- Handle player's badge ownership as needed
20		print(player.Name, "has badge", badgeId)
21	end
22end
23
24-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
25Players.PlayerAdded:Connect(onPlayerAdded)

Getting Badge Info

1local BadgeService = game:GetService("BadgeService")
2
3-- Fetch badge information
4local success, result = pcall(function()
5	return BadgeService:GetBadgeInfoAsync(00000000) -- Change this to desired badge ID
6end)
7
8-- Output the information
9if success then
10	print("Badge:", result.Name)
11	print("Enabled:", result.IsEnabled)
12	print("Description:", result.Description)
13	print("Icon:", "rbxassetid://" .. result.IconImageId)
14else
15	warn("Error while fetching badge info:", result)
16end

Summary

Properties

Properties inherited from Instance

Events

BadgeAwarded(message: string, userId: number, badgeId: number): RBXScriptSignal

OnBadgeAwarded(userId: number, creatorId: number, badgeId: number): RBXScriptSignal

Events inherited from Instance

Methods

AwardBadge(userId: number, badgeId: number): boolean YIELDS

Award a badge to a player given the ID of each.

GetBadgeInfoAsync(badgeId: number): table YIELDS

Fetch information about a badge given its ID.

UserHasBadgeAsync(userId: number, badgeId: number): boolean YIELDS

Checks whether a player has the badge given the Player.UserId and the badge ID.

Methods inherited from Instance

Properties

Properties inherited from Instance

Events

BadgeAwarded

Roblox Script Security

Parameters

message: string

userId: number

badgeId: number

OnBadgeAwarded

Roblox Script Security

Parameters

userId: number

creatorId: number

badgeId: number

Events inherited from Instance

Methods

AwardBadge

boolean

Yields

AwardBadge grants a Player a badge given the player's UserId and the badge ID. In order to successfully award a badge, the following criteria must be met:

The player must be presently connected to the game.
The player must not already have the badge (note that a player may delete an awarded badge from their profile and be awarded the badge again).
The badge must be awarded from a server-side Script or a ModuleScript eventually required by a Script, not from a LocalScript.
The badge must be awarded in a place that is part of the game associated with the badge.
The owner of the place must also own the badge (for example, the owner must not have deleted the badge).
The badge must be enabled; check this using the IsEnabled property of the badge fetched through BadgeService:GetBadgeInfoAsync().

Parameters

userId: number

The Player.UserId of the user the badge is to be awarded to.

badgeId: number

The ID of the badge to be awarded.

Returns

boolean

Boolean of true if the badge was awarded successfully.

Code Samples

Awarding a Badge

1local BadgeService = game:GetService("BadgeService")
2local Players = game:GetService("Players")
3
4local BADGE_ID = 0
5
6local function awardBadge(player, badgeId)
7	-- Fetch badge information
8	local success, badgeInfo = pcall(function()
9		return BadgeService:GetBadgeInfoAsync(badgeId)
10	end)
11
12	if success then
13		-- Confirm that badge can be awarded
14		if badgeInfo.IsEnabled then
15			-- Award badge
16			local awardSuccess, result = pcall(function()
17				return BadgeService:AwardBadge(player.UserId, badgeId)
18			end)
19
20			if not awardSuccess then
21				-- the AwardBadge function threw an error
22				warn("Error while awarding badge:", result)
23			elseif not result then
24				-- the AwardBadge function did not award a badge
25				warn("Failed to award badge.")
26			end
27		end
28	else
29		warn("Error while fetching badge info: " .. badgeInfo)
30	end
31end
32
33local function onPlayerAdded(player)
34	awardBadge(player, BADGE_ID)
35end
36
37Players.PlayerAdded:Connect(onPlayerAdded)

GetBadgeInfoAsync

table

Yields

This function fetches information about a badge given its ID. It takes a brief moment to load the information from the Roblox website; repeated calls will cache for a short duration. It returns a dictionary with the following fields:

Key	Type	Description
Name	string	The name of the badge.
Description	string	The description of the badge.
IconImageId	int64	The asset ID of the image for the badge.
IsEnabled	bool	Indicates whether the badge is available to be awarded.

Parameters

badgeId: number

The badge ID of the badge whose information should be fetched.

Returns

table

A dictionary of information about the specified badge.

Code Samples

Getting Badge Info

1local BadgeService = game:GetService("BadgeService")
2
3-- Fetch badge information
4local success, result = pcall(function()
5	return BadgeService:GetBadgeInfoAsync(00000000) -- Change this to desired badge ID
6end)
7
8-- Output the information
9if success then
10	print("Badge:", result.Name)
11	print("Enabled:", result.IsEnabled)
12	print("Description:", result.Description)
13	print("Icon:", "rbxassetid://" .. result.IconImageId)
14else
15	warn("Error while fetching badge info:", result)
16end

UserHasBadgeAsync

boolean

Yields

Checks and returns whether a Player owns a badge given their UserId and the badge ID. You can call the function from the server in a Script or ModuleScript eventually required by a Script, and the user in question must be present in the server for the query to run. When calling the method from the client in a LocalScript, it only works for the local user whose client is running the script.

Any badge for any game can be queried, no matter who created the badge or which experience it is used for.

Parameters

userId: number

The Player.UserId of the player to check for ownership of the specified badge.

badgeId: number

The badge ID of the badge whose ownership will be checked.

Returns

boolean

Indicates if the specified user has the specified badge.

Code Samples

Checking Earned Badges

1local BadgeService = game:GetService("BadgeService")
2local Players = game:GetService("Players")
3
4local badgeId = 00000000 -- Change this to your badge ID
5
6local function onPlayerAdded(player)
7	-- Check if the player has the badge
8	local success, hasBadge = pcall(function()
9		return BadgeService:UserHasBadgeAsync(player.UserId, badgeId)
10	end)
11
12	-- If there's an error, issue a warning and exit the function
13	if not success then
14		warn("Error while checking if player has badge!")
15		return
16	end
17
18	if hasBadge then
19		-- Handle player's badge ownership as needed
20		print(player.Name, "has badge", badgeId)
21	end
22end
23
24-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
25Players.PlayerAdded:Connect(onPlayerAdded)

Methods inherited from Instance