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

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

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

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.

badgeIds: Array

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


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

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.


Returns

A dictionary of information about the specified badge.

Code Samples

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

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.

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

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