BadgeService
Provides information on badges and awards them.
| Memory category | Instances |
|---|
Member index 9
Removed member index 6
| History | Member | |
|---|---|---|
| 310 | SetAwardBadgeUrl(url: string): void | |
| 310 | SetHasBadgeCooldown(seconds: int): void | |
| 310 | SetHasBadgeUrl(url: string): void | |
| 310 | SetIsBadgeDisabledUrl(url: string): void | |
| 310 | SetIsBadgeLegalUrl(url: string): void | |
| 310 | SetPlaceId(placeId: int): void |
Description
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.
History 41
- 615 Add CheckUserBadgesAsync
- 462 Change ThreadSafety of OnBadgeAwarded from to Unsafe
- 462 Change ThreadSafety of BadgeAwarded from to Unsafe
- 462 Change ThreadSafety of UserHasBadgeAsync from to Unsafe
- 462 Change ThreadSafety of UserHasBadge from to Unsafe
- 462 Change ThreadSafety of IsLegal from to Unsafe
- 462 Change ThreadSafety of IsDisabled from to Unsafe
- 462 Change ThreadSafety of GetBadgeInfoAsync from to Unsafe
- 462 Change ThreadSafety of AwardBadge from to Unsafe
- 409 Add OnBadgeAwarded
- 358 Change Tags of IsLegal from [Yields] to [Yields, Deprecated]
- 358 Change Tags of IsDisabled from [Yields] to [Yields, Deprecated]
- 345 Change Tags of UserHasBadge from [Yields] to [Yields, Deprecated]
- 339 Add GetBadgeInfoAsync
- 336 Add UserHasBadgeAsync
- 319 Change Parameters of BadgeAwarded from (message: string, userId: int, badgeId: int) to (message: string, userId: int64, badgeId: int64)
- 319 Change Parameters of UserHasBadge from (userId: int, badgeId: int) to (userId: int64, badgeId: int64)
- 319 Change Parameters of IsLegal from (badgeId: int) to (badgeId: int64)
- 319 Change Parameters of IsDisabled from (badgeId: int) to (badgeId: int64)
- 319 Change Parameters of AwardBadge from (userId: int, badgeId: int) to (userId: int64, badgeId: int64)
- 310 Remove SetPlaceId
- 310 Remove SetIsBadgeLegalUrl
- 310 Remove SetIsBadgeDisabledUrl
- 310 Remove SetHasBadgeUrl
- 310 Remove SetHasBadgeCooldown
- 310 Remove SetAwardBadgeUrl
- 168 Change Parameters of BadgeAwarded from (message: string) to (message: string, userId: int, badgeId: int)
- 91 Add BadgeAwarded
- 90 Remove BadgeAwarded
- 91 Add BadgeAwarded
- 47 Add UserHasBadge
- 47 Add SetPlaceId
- 47 Add SetIsBadgeLegalUrl
- 47 Add SetIsBadgeDisabledUrl
- 47 Add SetHasBadgeUrl
- 47 Add SetHasBadgeCooldown
- 47 Add SetAwardBadgeUrl
- 47 Add IsLegal
- 47 Add IsDisabled
- 47 Add AwardBadge
- 47 Add BadgeService
Members 9
AwardBadge
| Parameters (2) | ||
|---|---|---|
| userId | int64 | |
| badgeId | int64 | |
| Returns (1) | ||
| bool | ||
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
IsEnabledproperty of the badge fetched through BadgeService:GetBadgeInfoAsync().
See also:
| Thread safety | Unsafe |
|---|
History 3
- 462 Change ThreadSafety of AwardBadge from to Unsafe
- 319 Change Parameters of AwardBadge from (userId: int, badgeId: int) to (userId: int64, badgeId: int64)
- 47 Add AwardBadge
BadgeAwarded
| Parameters (3) | |
|---|---|
| message | string |
| userId | int64 |
| badgeId | int64 |
| Security | RobloxScriptSecurity |
|---|---|
| Thread safety | Unsafe |
History 6
- 462 Change ThreadSafety of BadgeAwarded from to Unsafe
- 319 Change Parameters of BadgeAwarded from (message: string, userId: int, badgeId: int) to (message: string, userId: int64, badgeId: int64)
- 168 Change Parameters of BadgeAwarded from (message: string) to (message: string, userId: int, badgeId: int)
- 91 Add BadgeAwarded
- 90 Remove BadgeAwarded
- 91 Add BadgeAwarded
CheckUserBadgesAsync
| Parameters (2) | ||
|---|---|---|
| userId | int64 | |
| badgeIds | Array | |
| Returns (1) | ||
| Array | ||
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.
| Thread safety | Unsafe |
|---|
History 1
GetBadgeInfoAsync
| Parameters (1) | ||
|---|---|---|
| badgeId | int64 | |
| Returns (1) | ||
| Dictionary | ||
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:
| Key | Type | Description |
|---|---|---|
| Name | string | The name of the badge. |
| Description | string | The description of the badge. |
| IconImageId | int64 | The asset ID of the image for the badge. |
| IsEnabled | bool | Indicates whether the badge is available to be awarded. |
See also:
| Thread safety | Unsafe |
|---|
History 2
- 462 Change ThreadSafety of GetBadgeInfoAsync from to Unsafe
- 339 Add GetBadgeInfoAsync
IsDisabled
| Parameters (1) | ||
|---|---|---|
| badgeId | int64 | |
| Returns (1) | ||
| bool | ||
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.
| Thread safety | Unsafe |
|---|
History 4
- 462 Change ThreadSafety of IsDisabled from to Unsafe
- 358 Change Tags of IsDisabled from [Yields] to [Yields, Deprecated]
- 319 Change Parameters of IsDisabled from (badgeId: int) to (badgeId: int64)
- 47 Add IsDisabled
IsLegal
| Parameters (1) | ||
|---|---|---|
| badgeId | int64 | |
| Returns (1) | ||
| bool | ||
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.
| Thread safety | Unsafe |
|---|
OnBadgeAwarded
| Parameters (3) | |
|---|---|
| userId | int64 |
| creatorId | int64 |
| badgeId | int64 |
| Security | RobloxScriptSecurity |
|---|---|
| Thread safety | Unsafe |
History 2
- 462 Change ThreadSafety of OnBadgeAwarded from to Unsafe
- 409 Add OnBadgeAwarded
UserHasBadge
| Parameters (2) | ||
|---|---|---|
| userId | int64 | |
| badgeId | int64 | |
| Returns (1) | ||
| bool | ||
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.
| Thread safety | Unsafe |
|---|
History 4
- 462 Change ThreadSafety of UserHasBadge from to Unsafe
- 345 Change Tags of UserHasBadge from [Yields] to [Yields, Deprecated]
- 319 Change Parameters of UserHasBadge from (userId: int, badgeId: int) to (userId: int64, badgeId: int64)
- 47 Add UserHasBadge
UserHasBadgeAsync
| Parameters (2) | ||
|---|---|---|
| userId | int64 | |
| badgeId | int64 | |
| Returns (1) | ||
| bool | ||
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:
| Thread safety | Unsafe |
|---|
History 2
- 462 Change ThreadSafety of UserHasBadgeAsync from to Unsafe
- 336 Add UserHasBadgeAsync
Removed members 6
SetAwardBadgeUrl
| Parameters (1) | ||
|---|---|---|
| url | string | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetAwardBadgeUrl
- 47 Add SetAwardBadgeUrl
SetHasBadgeCooldown
| Parameters (1) | ||
|---|---|---|
| seconds | int | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetHasBadgeCooldown
- 47 Add SetHasBadgeCooldown
SetHasBadgeUrl
| Parameters (1) | ||
|---|---|---|
| url | string | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetHasBadgeUrl
- 47 Add SetHasBadgeUrl
SetIsBadgeDisabledUrl
| Parameters (1) | ||
|---|---|---|
| url | string | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetIsBadgeDisabledUrl
- 47 Add SetIsBadgeDisabledUrl
SetIsBadgeLegalUrl
| Parameters (1) | ||
|---|---|---|
| url | string | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetIsBadgeLegalUrl
- 47 Add SetIsBadgeLegalUrl
SetPlaceId
| Parameters (1) | ||
|---|---|---|
| placeId | int | |
| Returns (1) | ||
| void | ||
| Security | LocalUserSecurity |
|---|
History 2
- 310 Remove SetPlaceId
- 47 Add SetPlaceId