rojo/.cursor/rules/roblox/reference/engine/classes/BadgeService.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: BadgeService
type: class
memory_category: Instances
summary: |
  Provides information on badges and awards them.
description: |
  `BadgeService` provides information and functionality related to
  [badges](../../../production/publishing/badges.md). 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: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties: []
methods:
  - name: BadgeService:AwardBadgeAsync
    summary: |
      Award a badge to a player given the ID of each.
    description: |
      Grants a `Class.Player` a badge with the `Class.Player.UserId|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 `Class.Script` or a
        `Class.ModuleScript` eventually required by a `Class.Script`, not from a
        `Class.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 `Class.BadgeService:GetBadgeInfoAsync()`.

      Rate limit is `50 + 35 * [number of users]` per minute.
    code_samples:
      - badges---awarding-a-badge
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The `Class.Player.UserId` of the user the badge is to be awarded to.
      - name: badgeId
        type: int64
        default:
        summary: |
          The ID of the badge to be awarded.
    returns:
      - type: boolean
        summary: |
          Boolean of `true` if the badge was awarded successfully.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:AwardBadge
    summary: |
      Award a badge to a player given the ID of each.
    description: ''
    code_samples: []
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The `Class.Player.UserId` of the user the badge is to be awarded to.
      - name: badgeId
        type: int64
        default:
        summary: |
          The ID of the badge to be awarded.
    returns:
      - type: boolean
        summary: |
          Boolean of `true` if the badge was awarded successfully.
    tags:
      - Yields
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:CheckUserBadgesAsync
    summary: |
      Checks a list of badge IDs against a `Class.Player.UserId|UserId` and
      returns a list of badge IDs that the player owns.
    description: |
      Checks a list of badge IDs against a `Class.Player.UserId|UserId` and
      returns a list of badge IDs that the player owns. This method supports
      batches of up to 10 badges; use `Class.BadgeService:UserHasBadgeAsync()`
      for single badge lookups.

      Any set of badges for any experience can be queried, no matter who created
      the badges or which experiences they are for. Any
      `Class.Player.UserId|UserId` can be used in a `Class.Script`, but in a
      `Class.LocalScript`, only the `Class.Player.UserId|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.
    code_samples:
      - badges---checking-earned-badges-batch
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The `Class.Player.UserId|UserId` of the player to check for ownership
          of the specified badges.
      - name: badgeIds
        type: Array
        default:
        summary: |
          The list of IDs of the badges to check ownership of. Maximum length
          of 10.
    returns:
      - type: Array
        summary: |
          The list of badge IDs the given user owns out of the provided badge
          IDs. Empty if none of the provided badges are owned by the given user.
          Not guaranteed to be in the same order as the input list.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:GetBadgeInfoAsync
    summary: |
      Fetch information about a badge given its ID.
    description: |
      This method fetches information about a badge given its ID and returns a
      dictionary with the following fields:

      <table>
      	<thead>
      		<tr>
      			<th>Key</th>
      			<th>Type</th>
      			<th>Description</th>
      		</tr>
      	</thead>
      	<tbody>
      		<tr>
      			<td><code>Name</code></td>
      			<td>string</td>
      			<td>The name of the badge.</td>
      		</tr>
      		<tr>
      			<td><code>Description</code></td>
      			<td>string</td>
      			<td>The description of the badge.</td>
      		</tr>
      		<tr>
      			<td><code>IconImageId</code></td>
      			<td>int64</td>
      			<td>The asset ID of the image for the badge.</td>
      		</tr>
      		<tr>
      			<td><code>IsEnabled</code></td>
      			<td>boolean</td>
      			<td>Indicates whether the badge is available to be awarded.</td>
      		</tr>
      	</tbody>
      </table>

      This method takes a brief moment to load the information from Roblox;
      repeated calls will cache for a short duration.
    code_samples:
      - getbadgeinfoasync
    parameters:
      - name: badgeId
        type: int64
        default:
        summary: |
          The badge ID of the badge whose information should be fetched.
    returns:
      - type: Dictionary
        summary: |
          A dictionary of information about the specified badge.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:IsDisabled
    summary: |
      Returns whether a given badge is disabled.
    description: |
      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.
    code_samples:
      - BadgeService-IsDisabled1
    parameters:
      - name: badgeId
        type: int64
        default:
        summary: |
          The ID of the badge.
    returns:
      - type: boolean
        summary: |
          True if the specified badge is not available to be awarded.
    tags:
      - Yields
      - Deprecated
    deprecation_message: |
      This function is deprecated. Do not use it for new work. Instead, it can
      be checked by calling BadgeService:GetBadgeInfoAsync() and checking the
      IsEnabled field.
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:IsLegal
    summary: |
      Determines if a given badge is associated with the current game.
    description: |
      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.
    code_samples: []
    parameters:
      - name: badgeId
        type: int64
        default:
        summary: |
          The badge ID of the badge.
    returns:
      - type: boolean
        summary: |
          True if the badge is associated with the current game.
    tags:
      - Yields
      - Deprecated
    deprecation_message: |
      This function is deprecated and will always return true. Do not use it for
      new work.
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:UserHasBadge
    summary: |
      Checks whether a user has the badge given the `Class.Player.UserId` and
      the badge ID.
    description: |
      Checks and returns whether a `Class.Player` owns a badge given their
      `Class.Player.UserId|UserId` and the badge ID. You can call the function
      from the server in a `Class.Script` or `Class.ModuleScript` eventually
      required by a `Class.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 `Class.LocalScript`, it only works for the local user whose client is
      running the script.

      Any badge for any experience can be queried, no matter who created the
      badge or which experience it is used for.
    code_samples: []
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The user ID of the user.
      - name: badgeId
        type: int64
        default:
        summary: |
          The badge ID of the badge.
    returns:
      - type: boolean
        summary: |
          True if the user has the badge.
    tags:
      - Yields
      - Deprecated
    deprecation_message: |
      This method has been superseded by
      `Class.BadgeService:UserHasBadgeAsync()` which should be used for new
      instead.
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: BadgeService:UserHasBadgeAsync
    summary: |
      Checks whether a player has the badge given the `Class.Player.UserId` and
      the badge ID.
    description: |
      Checks and returns whether a `Class.Player` owns a badge given their
      `Class.Player.UserId|UserId` and the badge ID. You can call this method
      from the server in a `Class.Script` or `Class.ModuleScript` eventually
      required by a `Class.Script`, and the user in question must be present in
      the server for the query to run. When calling this method from the client
      in a `Class.LocalScript`, it only works for the local user whose client is
      running the script.

      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.
    code_samples:
      - badges---checking-earned-badges
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The `Class.Player.UserId` of the player to check for ownership of the
          specified badge.
      - name: badgeId
        type: int64
        default:
        summary: |
          The badge ID of the badge whose ownership will be checked.
    returns:
      - type: boolean
        summary: |
          Indicates if the specified user has the specified badge.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
events: []
callbacks: []