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

The following example creates an awardBadge() function that handles potential errors that may occur when awarding a badge. Using properties of the badge fetched via BadgeService:GetBadgeInfoAsync(), it confirms that the badge can be awarded and does so using BadgeService:AwardBadge().

Awarding a Badge

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local BADGE_ID = 0
local function awardBadge(player, badgeId)
-- Fetch badge information
local success, badgeInfo = pcall(function()
return BadgeService:GetBadgeInfoAsync(badgeId)
end)
if success then
-- Confirm that badge can be awarded
if badgeInfo.IsEnabled then
-- Award badge
local awardSuccess, result = pcall(function()
return BadgeService:AwardBadge(player.UserId, badgeId)
end)
if not awardSuccess then
-- the AwardBadge function threw an error
warn("Error while awarding badge:", result)
elseif not result then
-- the AwardBadge function did not award a badge
warn("Failed to award badge.")
end
end
else
warn("Error while fetching badge info: " .. badgeInfo)
end
end
local function onPlayerAdded(player)
awardBadge(player, BADGE_ID)
end
Players.PlayerAdded:Connect(onPlayerAdded)

The following script waits for any player to enter the game and checks if they own a specific badge. This is useful for creating a restricted area with collision filtering or teleportation that only works if a player owns a special badge.

Checking Earned Badges

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local badgeId = 00000000 -- Change this to your badge ID
local function onPlayerAdded(player)
-- Check if the player has the badge
local success, hasBadge = pcall(function()
return BadgeService:UserHasBadgeAsync(player.UserId, badgeId)
end)
-- If there's an error, issue a warning and exit the function
if not success then
warn("Error while checking if player has badge!")
return
end
if hasBadge then
-- Handle player's badge ownership as needed
print(player.Name, "has badge", badgeId)
end
end
-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
Players.PlayerAdded:Connect(onPlayerAdded)

This script checks which badges a user owns when they join the experience.

Checking Earned Badges in Batches

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local badgeIds = { 0000000000, 1111111111, 2222222222 } -- Change this to a list of your badge IDs
local function onPlayerAdded(player)
-- Check if the player has any of the badges
local success, result = pcall(function()
return BadgeService:CheckUserBadgesAsync(player.UserId, badgeIds)
end)
-- If there's an error, issue a warning and exit the function
if not success then
warn("Error while checking if player", player.Name, "has badges:", result)
return
end
local ownedBadgeIds = result
if #ownedBadgeIds == 0 then
print(player.Name, "does not have any of the badges")
else
print(player.Name, "has the following badges:", table.concat(ownedBadgeIds, ", "))
end
end
Players.PlayerAdded:Connect(onPlayerAdded)

This sample prints badge information fetched via BadgeService:GetBadgeInfoAsync().

Getting Badge Info

local BadgeService = game:GetService("BadgeService")
-- Fetch badge information
local success, result = pcall(function()
return BadgeService:GetBadgeInfoAsync(00000000) -- Change this to desired badge ID
end)
-- Output the information
if success then
print("Badge:", result.Name)
print("Enabled:", result.IsEnabled)
print("Description:", result.Description)
print("Icon:", "rbxassetid://" .. result.IconImageId)
else
warn("Error while fetching badge info:", result)
end

Summary

Methods

Properties

Methods

AwardBadge

Yields

Grants a Player a badge with the UserId and the badge ID. Rate limit: 50 + 35 * [number of users] per minute. In order to successfully award a badge:

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

Default Value: ""
badgeId: number

The ID of the badge to be awarded.

Default Value: ""

Returns

Boolean of true if the badge was awarded successfully.

Code Samples

The following example creates an awardBadge() function that handles potential errors that may occur when awarding a badge. Using properties of the badge fetched via BadgeService:GetBadgeInfoAsync(), it confirms that the badge can be awarded and does so using BadgeService:AwardBadge().

Awarding a Badge

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local BADGE_ID = 0
local function awardBadge(player, badgeId)
-- Fetch badge information
local success, badgeInfo = pcall(function()
return BadgeService:GetBadgeInfoAsync(badgeId)
end)
if success then
-- Confirm that badge can be awarded
if badgeInfo.IsEnabled then
-- Award badge
local awardSuccess, result = pcall(function()
return BadgeService:AwardBadge(player.UserId, badgeId)
end)
if not awardSuccess then
-- the AwardBadge function threw an error
warn("Error while awarding badge:", result)
elseif not result then
-- the AwardBadge function did not award a badge
warn("Failed to award badge.")
end
end
else
warn("Error while fetching badge info: " .. badgeInfo)
end
end
local function onPlayerAdded(player)
awardBadge(player, BADGE_ID)
end
Players.PlayerAdded:Connect(onPlayerAdded)

CheckUserBadgesAsync

Yields

Checks a list of badge IDs against a UserId and returns a list of badge IDs that the player owns.

This method supports batches of up to 10 badges. Use BadgeService:UserHasBadgeAsync() for single badge lookups.

Rate limit: 10 + 5 * [number of players] per minute in each server.

Any set of badges for any experience can be queried, no matter who created the badges or which experiences they are for. Any UserId can be used in a Script, but in a LocalScript, only the UserId of the local user whose client is running the script can be used.

Parameters

userId: number

The UserId of the player to check for ownership of the specified badges.

Default Value: ""
badgeIds: Array

The list of IDs of the badges to check ownership of. Maximum length of 10.

Default Value: ""

Returns

The list of badge IDs the given user owns out of the provided badge IDs. Empty if none of the provided badges are owned by the given user. Not guaranteed to be in the same order as the input list.

Code Samples

This script checks which badges a user owns when they join the experience.

Checking Earned Badges in Batches

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local badgeIds = { 0000000000, 1111111111, 2222222222 } -- Change this to a list of your badge IDs
local function onPlayerAdded(player)
-- Check if the player has any of the badges
local success, result = pcall(function()
return BadgeService:CheckUserBadgesAsync(player.UserId, badgeIds)
end)
-- If there's an error, issue a warning and exit the function
if not success then
warn("Error while checking if player", player.Name, "has badges:", result)
return
end
local ownedBadgeIds = result
if #ownedBadgeIds == 0 then
print(player.Name, "does not have any of the badges")
else
print(player.Name, "has the following badges:", table.concat(ownedBadgeIds, ", "))
end
end
Players.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.

Default Value: ""

Returns

A dictionary of information about the specified badge.

Code Samples

This sample prints badge information fetched via BadgeService:GetBadgeInfoAsync().

Getting Badge Info

local BadgeService = game:GetService("BadgeService")
-- Fetch badge information
local success, result = pcall(function()
return BadgeService:GetBadgeInfoAsync(00000000) -- Change this to desired badge ID
end)
-- Output the information
if success then
print("Badge:", result.Name)
print("Enabled:", result.IsEnabled)
print("Description:", result.Description)
print("Icon:", "rbxassetid://" .. result.IconImageId)
else
warn("Error while fetching badge info:", result)
end

IsDisabled

Yields
Deprecated

This function returns whether the badge with the given id is marked disabled on the Roblox website. A badge can be disabled by its owner on its page on the Roblox website, in the settings sub-menu. When a badge is disabled, this function returns true and the badge can no longer be awarded using AwardBadge. A badge may be quickly re-enabled through the same menu.

In Studio, a badge can only be tested if it is disabled. Calling this function with an enabled badge in Studio will return true and produce a warning "Sorry, badges can only be tested if they are disabled on Roblox game servers".

Note that even if a badge is enabled it may not necessarily be awardable (for example if it isn't associated with the current game). See AwardBadge for more information on the criteria required for awarding badges.

Badges that are associated with special events are a common reason for a badge to be disabled. Often, it is easier to simply disable a badge instead of hard-coding a time check for when some event ends.

Parameters

badgeId: number

The ID of the badge.

Default Value: ""

Returns

True if the specified badge is not available to be awarded.

Code Samples

[Deprecated] Checking if a Badge is Disabled

local BadgeService = game:GetService("BadgeService")
print(BadgeService:IsDisabled(17468517))
Awarding a Badge

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local BADGE_ID = 0
local function awardBadge(player, badgeId)
-- check badge can be awarded
if BadgeService:IsLegal(badgeId) and not BadgeService:IsDisabled(badgeId) then
-- award badge
BadgeService:AwardBadge(player.UserId, badgeId)
end
end
local function onPlayerAdded(player)
awardBadge(player, BADGE_ID)
end
Players.PlayerAdded:Connect(onPlayerAdded)

IsLegal

Yields
Deprecated

This function determines if a given badge is associated with the current game. It returns true if the badge is associated with the current game.

Badges can only be awarded from a place that is part of the game associated with the badge. This means, for example, a developer cannot award a badge associated with another developer's game.

Even if this returns true, a badge may still not be award-able. For example, it may be disabled. For more information on the criteria for awarding badges see AwardBadge.

Parameters

badgeId: number

The badge ID of the badge.

Default Value: ""

Returns

True if the badge is associated with the current game.

Code Samples

Awarding a Badge

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local BADGE_ID = 0
local function awardBadge(player, badgeId)
-- check badge can be awarded
if BadgeService:IsLegal(badgeId) and not BadgeService:IsDisabled(badgeId) then
-- award badge
BadgeService:AwardBadge(player.UserId, badgeId)
end
end
local function onPlayerAdded(player)
awardBadge(player, BADGE_ID)
end
Players.PlayerAdded:Connect(onPlayerAdded)

UserHasBadge

Yields
Deprecated

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 user ID of the user.

Default Value: ""
badgeId: number

The badge ID of the badge.

Default Value: ""

Returns

True if the user has the badge.

Code Samples

[Deprecated] Checking if a User Has a Badge

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local BADGE_ID = 123
Players.PlayerAdded:Connect(function(player)
if BadgeService:UserHasBadge(player.UserId, BADGE_ID) then
print("The user has this badge")
else
print("The user does not have this badge")
end
end)

UserHasBadgeAsync

Yields

Checks and returns whether a Player owns a badge given their UserId and the badge ID. Rate limit: 50 + 35 * [number of players] per minute. 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.

Default Value: ""
badgeId: number

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

Default Value: ""

Returns

Indicates if the specified user has the specified badge.

Code Samples

The following script waits for any player to enter the game and checks if they own a specific badge. This is useful for creating a restricted area with collision filtering or teleportation that only works if a player owns a special badge.

Checking Earned Badges

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")
local badgeId = 00000000 -- Change this to your badge ID
local function onPlayerAdded(player)
-- Check if the player has the badge
local success, hasBadge = pcall(function()
return BadgeService:UserHasBadgeAsync(player.UserId, badgeId)
end)
-- If there's an error, issue a warning and exit the function
if not success then
warn("Error while checking if player has badge!")
return
end
if hasBadge then
-- Handle player's badge ownership as needed
print(player.Name, "has badge", badgeId)
end
end
-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
Players.PlayerAdded:Connect(onPlayerAdded)

Events