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

Properties

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.

Events

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


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


Properties

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

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)

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

BadgeAwarded

Roblox Script Security

Parameters

message: string
userId: number
badgeId: number

OnBadgeAwarded

Roblox Script Security

Parameters

userId: number
creatorId: number
badgeId: number