Badges

A badge is a special award you can gift users 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 user receives a badge, it displays within the Badges category of their inventory.

Creating Badges

When you're creating an image to use for your badge, consider the following requirements:

  • Use a template of 512×512 pixels.
  • Save the image in either .jpg, .gif, .png, .tga, or .bmp format.
  • Don't include important details outside of the circular boundaries because the upload process trims and crops the final badge into a circular image.
Good circular trimming
Bad circular trimming

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 badges within the 24-hour period, it costs 100 Robux per additional badge.

To create a badge:

  1. In the Home tab of the menu bar, navigate to the Settings section and click Game Settings. The Game Settings menu displays.

  2. In the left-hand navigation, select Monetization.

  3. In the Badges section, click the Create button. A web page opens with badge options.

  4. Click the Choose File button. A file browser displays.

  5. Select the image you want to display as the icon, then click the Open button.

  6. Fill in the following fields:

    • Badge Name: A title for your badge.

    • Description: A description of what the user can do to earn the badge.

  7. Click the Preview button. A preview of your Game Pass displays.

  8. If you are satisfied with the preview, click the Purchase for 0 Robux button or Purchase for 100 Robux button if you have already created 5 badges in a 24-hour period. The badge appears in the Badges section of the experience's main page.

Locating Badge IDs

A badge ID is the unique identifier of a badge. You will need this ID when you are scripting badges.

To locate a badge ID:

  1. In the Home tab of the menu bar, navigate to the Settings section and click Game Settings. The Game Settings menu displays.

  2. In the left-hand navigation of the Game Settings menu, click Monetization. Every badge you have created displays in a table.

  3. To the right of the badge you want to find the badge ID for, click the ... button. A contextual menu displays.

  4. Select Copy ID to Clipboard. The badge ID copies to your clipboard.

Scripting Badges

Use scripting to give and keep track of badges in your experiences. Common badge scripting use cases include awarding badges, checking if a user has previously earned a badge in your experience, and getting badge information.

Awarding Badges

You can award users badges throughout your experience by calling the BadgeService:AwardBadge() function 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 user. You should call this to check before awarding a badge.

The following script contains an example of a safe function for awarding badges to users.


1local BadgeService = game:GetService("BadgeService")
2
3local function awardBadge(player, badgeId)
4 -- Fetch badge information
5 local success, badgeInfo = pcall(BadgeService.GetBadgeInfoAsync, BadgeService, badgeId)
6 if success then
7 -- Confirm that badge can be awarded
8 if badgeInfo.IsEnabled then
9 -- Award badge
10 local awarded, errorMessage = pcall(BadgeService.AwardBadge, BadgeService, player.UserId, badgeId)
11 if not awarded then
12 warn("Error while awarding badge:", errorMessage)
13 end
14 end
15 else
16 warn("Error while fetching badge info!")
17 end
18end
19

Checking Earned Badges

The following script checks when any user enters the experience, then verifies if that user owns the badge with the matching ID set in the variable badgeID. This is useful for creating a restricted area or teleporter that only works when a user owns a special badge.


1local BadgeService = game:GetService("BadgeService")
2local Players = game:GetService("Players")
3
4local BADGE_ID = 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(BadgeService.UserHasBadgeAsync, BadgeService, player.UserId, badgeID)
9
10 -- If there's an error, issue a warning and exit the function
11 if not success then
12 warn("Error while checking if player has badge!")
13 return
14 end
15
16 if hasBadge then
17 -- Handle player's badge ownership as needed
18 end
19end
20
21-- Connect "PlayerAdded" events to the "onPlayerAdded()" function
22Players.PlayerAdded:Connect(onPlayerAdded)
23

Getting Badge Info

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


1local BadgeService = game:GetService("BadgeService")
2
3local BADGE_ID = 00000000 -- Change this to your badge ID
4
5-- Fetch badge information
6local success, result = pcall(BadgeService.GetBadgeInfoAsync, BadgeService, BADGE_ID)
7print(success, result)
8
9-- Output the information
10if success then
11 print("Badge:", result.Name)
12 print("Enabled:", result.IsEnabled)
13 print("Description:", result.Description)
14 print("Icon:", "rbxassetid://" .. result.IconImageId)
15else
16 warn("Error while fetching badge info:", result)
17end
18
19