Reference API Roblox

Engine API

Website

Related

Reference API Roblox

BadgeService

Provides information on badges and awards them.

This class is not creatable. Instances of this class cannot be created with Instance.new.
This class is a service. It is a singleton that may be acquired with GetService.
Tags: [NotCreatable, Service]

Member index 10

HistoryMember
726AwardBadge(userId: User, badgeId: int64): bool
725AwardBadgeAsync(userId: User, badgeId: int64): bool
725CheckUserBadgesAsync(userId: User, badgeIds: Array): Array
462GetBadgeInfoAsync(badgeId: int64): Dictionary
462IsDisabled(badgeId: int64): bool
462IsLegal(badgeId: int64): bool
725UserHasBadge(userId: User, badgeId: int64): bool
725UserHasBadgeAsync(userId: User, badgeId: int64): bool
462BadgeAwarded(message: string, userId: int64, badgeId: int64)
462OnBadgeAwarded(userId: int64, creatorId: int64, badgeId: int64)
inherited from Instance
726Archivable: bool
726Capabilities: SecurityCapabilities
726IsInSandbox: bool
726Name: string
726Parent: Instance
726PredictionMode: PredictionMode
726Sandboxed: bool
726UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
707GetDescendants(): Instances
486GetFullName(): string
706GetStyled(name: string, selector: string?): Variant
657GetStyledPropertyChangedSignal(property: string): RBXScriptSignal
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
664IsPropertyModified(property: string): bool
698QueryDescendants(selector: string): Instances
573Remove(): null
576RemoveTag(tag: string): null
664ResetPropertyToDefault(property: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
726children(): Instances
726clone(): Instance
726destroy(): null
726findFirstChild(name: string, recursive: bool = false): Instance
726getChildren(): Instances
726isDescendantOf(ancestor: Instance): bool
726remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
657StyledPropertiesChanged()
726childAdded(child: Instance)
inherited from Object
726ClassName: string
726className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
726isA(className: string): bool
647Changed(property: string)

Removed member index 6

HistoryMember
310SetAwardBadgeUrl(url: string): void
310SetHasBadgeCooldown(seconds: int): void
310SetHasBadgeUrl(url: string): void
310SetIsBadgeDisabledUrl(url: string): void
310SetIsBadgeLegalUrl(url: string): void
310SetPlaceId(placeId: int): void

Description

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

Members 10

AwardBadge

Parameters (2)
userIdUser
badgeIdint64
Returns (1)
bool
This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 11

Tags: [Yields, Deprecated]

AwardBadgeAsync

Parameters (2)
userIdUser
badgeIdint64
Returns (1)
bool

Grants a Player a badge with the UserId and the badge ID.

In order to successfully award a badge:

  • The player must be presently connected to the experience.
  • 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 experience associated with the badge.
  • The badge must be enabled; check this using the IsEnabled property of the badge fetched through BadgeService:GetBadgeInfoAsync().

Rate limit is 50 + 35 * [number of users] per minute.

This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields]

BadgeAwarded

Parameters (3)
messagestring
userIdint64
badgeIdint64

History 6

CheckUserBadgesAsync

Parameters (2)
userIdUser
badgeIdsArray
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.

When called from a Script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked, and any badge IDs that are not associated with the requesting experience will not be included in the response (as if they were not owned).

For users that have recently been in the server, any badges for any experiences can be queried, no matter who created the badge or which experience it is used for.

In a LocalScript, only the UserId of the local user whose client is running the script can be used.

Rate limit is 10 + 5 * [number of players] per minute in each server.

This function yields. It will block the calling thread until completion.

History 2

Tags: [Yields]

GetBadgeInfoAsync

Parameters (1)
badgeIdint64
Returns (1)
Dictionary

This method fetches information about a badge given its ID and 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.
IsEnabledbooleanIndicates whether the badge is available to be awarded.

This method takes a brief moment to load the information from Roblox; repeated calls will cache for a short duration.

This function yields. It will block the calling thread until completion.

History 2

Tags: [Yields]

IsDisabled

Parameters (1)
badgeIdint64
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. 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).

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.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields, Deprecated]

IsLegal

Parameters (1)
badgeIdint64
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.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 4

Tags: [Yields, Deprecated]

OnBadgeAwarded

Parameters (3)
userIdint64
creatorIdint64
badgeIdint64

History 2

UserHasBadge

Parameters (2)
userIdUser
badgeIdint64
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. When calling the method from the client in a LocalScript, it only works for the local user whose client is running the script.

When called from a Script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked. If the requested badge ID is not associated with the requesting experience and the target user has not recently been in the server, the method behaves as if the badge is not owned.

For users that have recently been in the server, any badge for any experience can be queried, no matter who created the badge or which experience it is used for.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work.
This function yields. It will block the calling thread until completion.

History 5

Tags: [Yields, Deprecated]

UserHasBadgeAsync

Parameters (2)
userIdUser
badgeIdint64
Returns (1)
bool

Checks and returns whether a Player owns a badge given their UserId and the badge ID. You can call this method from the server in a Script or ModuleScript eventually required by a Script. When calling this method from the client in a LocalScript, it only works for the local user whose client is running the script.

When called from a Script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked. If the requested badge ID is not associated with the requesting experience and the target user has not recently been in the server, the method behaves as if the badge is not owned.

For users that have recently been in the server, any badge for any experience can be queried, no matter who created the badge or which experience it is used for.

Rate limit is 50 + 35 * [number of players] per minute.

This function yields. It will block the calling thread until completion.

History 3

Tags: [Yields]

Removed members 6

SetAwardBadgeUrl

Parameters (1)
urlstring
Returns (1)
void

History 2

SetHasBadgeCooldown

Parameters (1)
secondsint
Returns (1)
void

History 2

SetHasBadgeUrl

Parameters (1)
urlstring
Returns (1)
void

History 2

SetIsBadgeDisabledUrl

Parameters (1)
urlstring
Returns (1)
void

History 2

SetIsBadgeLegalUrl

Parameters (1)
urlstring
Returns (1)
void

History 2

SetPlaceId

Parameters (1)
placeIdint
Returns (1)
void

History 2

Settings