Badges

A badge is a special award you can gift players when they meet a goal within your experience, such as completing a difficult objective or playing for a certain amount of time. As soon as a player receives a badge, it displays within the Badges category of their inventory.

Creating Badges

You can create up to 5 badges for free in a 24‑hour period (GMT) for each experience you own. If you want to create more within the 24‑hour period, each additional badge costs 100 Robux.

To create a badge:

1. Navigate to the Creator Dashboard.

2. Locate the associated experience, click the ⋯ in the corner of its thumbnail, and select Create Badge.

   

3. On the create page, click the Upload Image button and then select/confirm the image you want to use as the badge's icon. When creating an image to use for a badge, consider the following:

   • Use a template of 512×512 pixels.

   • The upload process trims and crops the badge image into a circular icon, so avoid putting important details outside of the circular boundaries.

     

     

4. Complete the following fields:

   • Name — A title for the badge.
   • Description — A description of what the player can do to earn the badge.
   • Badge is Enabled — Whether or not the badge will be enabled when it is created. Disabled badges are not shown under the Badges section of the experience's main page and cannot be earned by players.

5. Click the Create Badge button. The new badge displays within the Engagement → Badges section on the Creator Dashboard. If the new badge is enabled, it will also be shown under the Badges section of the experience's main page.

   

Scripting Badges

Common badge scripting workflows include awarding badges, checking if a player has previously earned a badge in your experience, and getting badge information.

Locating Badge IDs

A badge's ID is its unique identifier. You'll need this ID when implementing workflows such as awarding the badge to a player.

1. On the Creator Dashboard, navigate to the associated experience's Badges section under Engagement.

   

2. Click the ⋯ button for a badge and select Copy Asset ID.

   

Awarding Badges

You can award badges to players throughout your experience by calling the BadgeService:AwardBadge() method in a server-side Script. BadgeService:GetBadgeInfoAsync() returns properties of the badge, including IsEnabled which confirms whether or not the badge can be awarded to a player. You can enable or disable a badge from the Configure Badge form on the Creator Dashboard.

The following is an example of a safe function for awarding badges to players.

local BadgeService = game:GetService("BadgeService")

local function awardBadge(player, badgeId)
  -- Fetch badge information
  local success, badgeInfo = pcall(BadgeService.GetBadgeInfoAsync, BadgeService, badgeId)
  if success then
    -- Confirm that badge can be awarded
    if badgeInfo.IsEnabled then
      -- Award badge
      local awarded, errorMessage = pcall(BadgeService.AwardBadge, BadgeService, player.UserId, badgeId)
      if not awarded then
        warn("Error while awarding badge:", errorMessage)
      end
    end
  else
 	  warn("Error while fetching badge info!")
  end
end

Checking Earned Badges

The following script checks when any player enters the experience, then uses the BadgeService:UserHasBadgeAsync() method to verify if that player owns the badge with the matching ID set in the variable BADGE_ID. You can also verify badge ownership in batches using the BadgeService:CheckUserBadgesAsync() method.

local BadgeService = game:GetService("BadgeService")
local Players = game:GetService("Players")

local BADGE_ID = 00000000  -- Change this to your badge ID

local function onPlayerAdded(player)
  -- Check if the player has the badge
	local success, hasBadge = pcall(BadgeService.UserHasBadgeAsync, BadgeService, player.UserId, BADGE_ID)

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

-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
Players.PlayerAdded:Connect(onPlayerAdded)

Getting Badge Info

To get information about a badge, such as its description or icon asset ID, call the BadgeService:GetBadgeInfoAsync() method with a badge ID. For example:

local BadgeService = game:GetService("BadgeService")

local BADGE_ID = 00000000  -- Change this to your badge ID

-- Fetch badge information
local success, result = pcall(BadgeService.GetBadgeInfoAsync, BadgeService, BADGE_ID)

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