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

Events

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


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


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.

Properties

Events

BadgeAwarded

Roblox Script Security

Parameters

message: string
userId: number
badgeId: number

OnBadgeAwarded

Roblox Script Security

Parameters

userId: number
creatorId: number
badgeId: number

Methods

AwardBadge

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().

See also:

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 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

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:

KeyTypeDescription
NamestringThe name of the badge.
DescriptionstringThe description of the badge.
IconImageIdint64The asset ID of the image for the badge.
IsEnabledboolIndicates whether the badge is available to be awarded.

See also:

Parameters

badgeId: number

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


Returns

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

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.

See also:

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

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)