Collection

A Collection is a live, query-based group of instances created by CollectionService:CreateCollection() using a selector string and an optional root instance. From then on, membership is automatic such that an instance is added the moment it matches the query and removed the moment it stops matching. You never add or remove instances manually.

You can interact with a Collection by assigning callbacks to it. Rather than connecting a signal for each instance and remembering to disconnect it, you declare behavior once on the collection and it is applied to every matching instance for you. The collection owns those connections and tears them down automatically when an instance leaves the set. See the accompanying code sample for a collection that uses each kind of callback together.

A collection's lifetime is tied to the root instance passed to CreateCollection() (defaulting to Workspace). When that root is destroyed or when you call Destroy(), the collection is torn down.

Callback Assignment Syntax#

Callbacks are assigned as fields on the collection using function-statement syntax, which reads like the contents of a ModuleScript. Both of the following forms are equivalent and assign through the collection's overloaded __newindex:

local CollectionService = game:GetService("CollectionService")

local collection = CollectionService:CreateCollection("Part")

function collection.OnAdded(instance)

end

local CollectionService = game:GetService("CollectionService")

local collection = CollectionService:CreateCollection("Part")

collection.OnAdded = function(instance)

end

Each callback can be assigned only once; reassigning the same callback raises an error. This keeps a collection's behavior declarative at its definition so that it cannot be silently replaced elsewhere.

Core Members and Aliases#

OnAdded, OnRemoved, and ForEach() are the collection's primitive members:

• OnAdded(instance: Instance) — Fires when an instance begins matching the query. When you first assign OnAdded, it immediately fires once for every instance already in the collection, so a single callback handles both current and future members.
• OnRemoved(instance: Instance) — Fires when an instance that was in the collection stops matching, for example its tag is removed, it is reparented out of the collection's root, it is destroyed, or the collection's Enabled property is set to false.
• ForEach() — Imperatively iterates the instances currently in the collection, operating on a snapshot taken at call time.

A collection can also bind a callback to non-deprecated RunService steps through aliases which exist for performance as well as convenience:

The collection subscribes to each RunService event once and dispatches to its members internally, rather than every instance holding its own connection. The callback fires once per step for each instance in the collection and receives the instance followed by the step's deltaTime:

local CollectionService = game:GetService("CollectionService")

local collection = CollectionService:CreateCollection("Part")

function collection.OnHeartbeat(instance, deltaTime)

end

Event, Property, and Attribute Wrappers#

Beyond the RunService aliases, a collection can wrap any signal on its member instances. In these callbacks, X stands for the name of an event, property, or attribute.

• function collection.OnX(instance, ...) wraps the X event on each member and the callback receives the instance followed by that event's arguments. For example, OnTouched wraps BasePart.Touched.

  LuauCopy

  local CollectionService = game:GetService("CollectionService")
  
  local collection = CollectionService:CreateCollection("Part")
  
  function collection.OnTouched(part, otherPart)
      print(part, otherPart)
  end

• function collection.OnPropertyChanged.X(instance) fires when property X changes on a member, equivalent to connecting GetPropertyChangedSignal() on each instance.

  LuauCopy

  local CollectionService = game:GetService("CollectionService")
  
  local collection = CollectionService:CreateCollection("Part")
  
  function collection.OnPropertyChanged.Color(instance)
      print(instance)
  end

• function collection.OnAttributeChanged.X(instance) fires when attribute X changes on a member, equivalent to GetAttributeChangedSignal().

  LuauCopy

  local CollectionService = game:GetService("CollectionService")
  
  local collection = CollectionService:CreateCollection("Humanoid")
  
  function collection.OnAttributeChanged.CharacterHealth(instance)
      print(instance)
  end

Note that a single collection can match instances of different classes, so a wrapped signal may not apply to every member:

• If a member does not have the signal or property named by the callback, that member silently ignores the assignment. For example, a collection matching both Part and Folder can safely define OnTouched, but only the Parts respond.
• If a callback names an event or property that exists nowhere in the API (for example a misspelled OnToched), an error is raised at assignment time.

Typing and Autocomplete#

When the query constrains the class of its matches, the collection is typed accordingly and callbacks are typed to match. For example, CreateCollection("Part.TagName") yields a collection whose callbacks receive a Part, and autocomplete only suggests callbacks relevant to that class (so collection.OnTouched(part: Part, other: BasePart) is suggested, but not for a query that cannot match a BasePart). When no type can be inferred from the query, the first argument defaults to Instance.