rojo/.cursor/rules/roblox/reference/engine/classes/CollectionService.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: CollectionService
type: class
memory_category: Instances
summary: |
  A service which manages instance collections using assigned tags.
description: |
  `CollectionService` manages groups (collections) of instances with **tags**.
  Tags are sets of strings applied to instances that replicate from the server
  to the client. They are also serialized when places are saved.

  The primary use of `CollectionService` is to register instances with specific
  tags that you can use to extend their behavior. If you find yourself adding
  the same script to many different instances, a script that uses
  `CollectionService` may be better.

  Tags can be added or removed through this class' methods such as
  `Class.CollectionService:AddTag()|AddTag()` or
  `Class.CollectionService:RemoveTag()|RemoveTag()`. They can also be managed
  directly in Studio through the
  [Tags](../../../studio/properties.md#instance-tags) section of an instance's
  properties.

  ##### Replication

  When tags replicate, **all tags on an instance replicate at the same time**.
  Therefore, if you set a tag on an instance from the client then add/remove a
  **different** tag on the same instance from the server, the client's local
  tags on the instance are overwritten. In
  `Class.Workspace.StreamingEnabled|StreamingEnabled` places, instances can be
  unloaded as they leave the client's streamed area. If such an instance
  re-enters the streamed area, properties and tags will be re-synchronized from
  the server. This can cause changes made by `Class.LocalScript|LocalScripts` to
  be overwritten/removed.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties: []
methods:
  - name: CollectionService:AddTag
    summary: |
      Applies a tag to an `Class.Instance`.
    description: |
      This method applies a tag to an `Class.Instance`, doing nothing if the tag
      is already applied to that instance. Successfully adding a tag will fire a
      signal created by
      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`
      with the given tag.

      ##### Warnings

      - An instance's tags that were added client-side will be dropped if the
        server later adds or removes a tag on that instance because the server
        replicates all tags together and overwrites previous tags.

      - When tagging an instance, it is common that some resources are used to
        give the tag its functionality, for example event connections or tables.
        To prevent memory leaks, it's a good idea to clean these up (disconnect,
        set to `nil`, etc.) when no longer needed for a tag. Do this when
        calling `Class.CollectionService:RemoveTag()|RemoveTag()`, calling
        `Class.Instance:Destroy()` or in a function connected to a signal
        returned by
        `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`.
    code_samples: []
    parameters:
      - name: instance
        type: Instance
        default:
        summary: ''
      - name: tag
        type: string
        default:
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: CollectionService:GetAllTags
    summary: |
      Returns an array of all tags in the experience.
    description: |
      Returns an array of all tags in the experience.
    code_samples: []
    parameters: []
    returns:
      - type: Array
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities:
      - Basic
  - name: CollectionService:GetCollection
    summary: |
      Returns all instances of a given class which are in the `Class.DataModel`.
    description: |
      This function returns all instances of a given class which are in the
      `Class.DataModel`. Only works for `Class.Configuration`,
      `Class.CustomEvent`, `Class.CustomEventReceiver`, `Class.Dialog`, and
      `Class.VehicleSeat`.
    code_samples:
      - CollectionService-GetCollection1
    parameters:
      - name: class
        type: string
        default:
        summary: ''
    returns:
      - type: Instances
        summary: ''
    tags:
      - Deprecated
    deprecation_message: |
      This item has been superseded by a `Class.CollectionService` tagging
      method. The equivalent function using the new method is
      `Class.CollectionService:GetTagged()` which should be used in new work.
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: CollectionService:GetInstanceAddedSignal
    summary: |
      Returns a signal that fires when a given tag is added to an instance.
    description: |
      Given a tag (string), this method returns a signal which fires under two
      conditions:

      - The tag is assigned to an instance within the `Class.DataModel` using
        `Class.CollectionService:AddTag()` or `Class.Instance:AddTag()`.

      - An instance with the given tag is added as a descendant of the
        `Class.DataModel`, for example by setting `Class.Instance.Parent` or
        similar.

      Subsequent calls to this method with the same tag return the same signal
      object. Consider also calling
      `Class.CollectionService:GetTagged()|GetTagged()` to get a list of
      instances that already have a tag (and thus won't fire the event if they
      already are in the `Class.DataModel`).

      See also
      `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`
      which returns an event that fires under similar conditions.
    code_samples:
      - Deadly-Bricks-using-CollectionService
    parameters:
      - name: tag
        type: string
        default:
        summary: |
          The tag to watch for.
    returns:
      - type: RBXScriptSignal
        summary: |
          An event that fires when you add the tag to an instance.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: CollectionService:GetInstanceRemovedSignal
    summary: |
      Returns a signal that fires when a given tag is removed from an instance.
    description: |
      Given a tag (string), this method returns a signal which fires under two
      conditions:

      - The tag is removed from an instance within the `Class.DataModel` using
        `Class.CollectionService:RemoveTag()` or `Class.Instance:RemoveTag()`.

      - An instance with the given tag is removed as a descendant of the
        `Class.DataModel`, for example by un‑setting `Class.Instance.Parent` or
        similar.

      Subsequent calls to this method with the same tag return the same signal
      object. The signal is useful for cleaning up resources used by instances
      that once had tags, such as disconnecting connections.

      See also
      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`
      which returns an event that fires under similar conditions.
    code_samples:
      - Deadly-Bricks-using-CollectionService
    parameters:
      - name: tag
        type: string
        default:
        summary: |
          The tag to watch for.
    returns:
      - type: RBXScriptSignal
        summary: |
          An event that fires when you remove the tag from an instance.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
  - name: CollectionService:GetTagged
    summary: |
      Returns an array of instances in the game with a given tag.
    description: |
      This method returns an array of instances with a given tag which are
      descendants of the `Class.DataModel`. Removing a tag using
      `Class.CollectionService:RemoveTag()` or `Class.Instance:RemoveTag()`
      ensures this method does not return them.

      If you want to detect all instances with a tag, both present **and**
      future, use this method to iterate over instances while also making a
      connection to a signal returned by
      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`.

      This method does not guarantee any ordering of the returned instances.
      Additionally, it's possible that instances can have the given tag assigned
      to them but not be a descendant of the `Class.DataModel`, for example its
      parent is `nil`; this method will not return such instances.
    code_samples:
      - Deadly-Bricks-using-CollectionService
    parameters:
      - name: tag
        type: string
        default:
        summary: |
          The tag to search for.
    returns:
      - type: Instances
        summary: |
          An array of all instances with the tag.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities:
      - Basic
  - name: CollectionService:GetTags
    summary: |
      Gets an array of all tags applied to a given instance.
    description: |
      Given an `Class.Instance`, this method returns an array of strings which
      are the tags applied to the instance.

      This method is useful when you want to do something with multiple instance
      tags at once, but it's inefficient to check for the existence of a single
      tag. For this, use `Class.CollectionService:HasTag()|HasTag()` to check
      for a single tag.
    code_samples:
      - Using-Tags-and-CollectionService
    parameters:
      - name: instance
        type: Instance
        default:
        summary: |
          The instance whose tags should be returned.
    returns:
      - type: Array
        summary: |
          An array of strings which are the tags applied to the given instance.
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities:
      - Basic
  - name: CollectionService:HasTag
    summary: |
      Check whether an instance has a given tag.
    description: |
      This method returns whether a given `Class.Instance` has a tag.

      By extension, any tags returned by a call to
      `Class.CollectionService:GetTags()|GetTags()` on an instance will return
      `true` when used with this method.
    code_samples:
      - Using-Tags-and-CollectionService
    parameters:
      - name: instance
        type: Instance
        default:
        summary: |
          The instance to check for the presence of a tag.
      - name: tag
        type: string
        default:
        summary: |
          The tag to check for.
    returns:
      - type: boolean
        summary: |
          Whether the instance has the tag.
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities:
      - Basic
  - name: CollectionService:RemoveTag
    summary: |
      Removes a tag from an instance.
    description: |
      This method removes a tag from an instance. Successfully removing a tag
      will fire a signal created by
      `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`
      with the given tag.

      When removing a tag, it's common that some resources are used to give the
      tag its functionality, for example event connections or tables. To prevent
      memory leaks, it's a good idea to clean these up (disconnect, set to
      `nil`, etc.) when no longer needed for a tag.
    code_samples:
      - Using-Tags-and-CollectionService
    parameters:
      - name: instance
        type: Instance
        default:
        summary: |
          The instance to remove the tag from.
      - name: tag
        type: string
        default:
        summary: |
          The tag to remove from the instance.
    returns:
      - type: ()
        summary: ''
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Basic
events:
  - name: CollectionService.ItemAdded
    summary: |
      Fires when a `Class.Configuration`, `Class.CustomEvent`,
      `Class.CustomEventReceiver`, `Class.Dialog`, or `Class.VehicleSeat` is
      added to the `Class.DataModel`.
    description: |
      This function fires when a `Class.Configuration`, `Class.CustomEvent`,
      `Class.CustomEventReceiver`, `Class.Dialog`, or `Class.VehicleSeat` is
      added to the `Class.DataModel`.
    code_samples:
      - CollectionService-ItemAdded1
    parameters:
      - name: instance
        type: Instance
        default:
        summary: ''
    tags:
      - Deprecated
    deprecation_message: |
      This item has been superseded by a `Class.CollectionService` tagging
      method. There is currently no means of checking when a tag is added.
    security: None
    capabilities:
      - Basic
  - name: CollectionService.ItemRemoved
    summary: |
      Fires when a `Class.Configuration`, `Class.CustomEvent`,
      `Class.CustomEventReceiver`, `Class.Dialog`, or `Class.VehicleSeat` is
      removed from the `Class.DataModel`.
    description: |
      This function fires when a `Class.Configuration`, `Class.CustomEvent`,
      `Class.CustomEventReceiver`, `Class.Dialog`, or `Class.VehicleSeat` is
      removed from the `Class.DataModel`.
    code_samples:
      - CollectionService-ItemRemoved1
    parameters:
      - name: instance
        type: Instance
        default:
        summary: ''
    tags:
      - Deprecated
    deprecation_message: |
      This item has been superseded by a `Class.CollectionService` tagging
      method. There is currently no means of checking when a tag is removed.
    security: None
    capabilities:
      - Basic
  - name: CollectionService.TagAdded
    summary: |
      Fires when a tag is added to an instance and the added tag is the only
      occurrence of that tag in the place.
    description: |
      This event fires when a tag is added to an instance and the added tag is
      the only occurrence of that tag in the place.
    code_samples: []
    parameters:
      - name: tag
        type: string
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Basic
  - name: CollectionService.TagRemoved
    summary: |
      Fires when a tag is removed from an instance and the removed tag is no
      longer used anywhere in the place.
    description: |
      This event fires when a tag is removed from an instance and the removed
      tag is no longer used anywhere in the place.
    code_samples: []
    parameters:
      - name: tag
        type: string
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Basic
callbacks: []