CollectionService

This method applies a tag to an Instance, doing nothing if the tag is already applied to that instance. Successfully adding a tag will fire a signal created by 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 RemoveTag(), calling Instance:Destroy() or in a function connected to a signal returned by GetInstanceRemovedSignal().

This method creates a Collection, a live, query-based group of instances. Unlike tag-based methods such as GetTagged() which return a fixed array at the moment they are called, a Collection continuously tracks which instances match query and notifies you as instances enter and leave the result set.

The query string is a CSS-inspired selector that follows the same selector conventions used by QueryDescendants() and the StyleRule styling selectors. Filters stack conjunctively, combinators express hierarchy, and comma-separated selectors form a union:

• ClassName — Instances of that class (uses IsA()), for example Part or Model.
• #Name — Instances with a matching Name.
• .Tag — Instances carrying a CollectionService tag.
• [Property = value] — Instances whose property equals a value.
• [$Attribute] or [$Attribute = value] — Instances that have an attribute, optionally matching a value.
• A > B (direct child) and A >> B (any descendant) combinators.
• :has(...) and :not(...) pseudoclasses.

The rightmost selector in a chain identifies the matched instance, so Folder > Part tracks the parts, not the folders.

local CollectionService = game:GetService("CollectionService")

-- Track every Part tagged "KillBrick" anywhere under Workspace
local killBricks: Collection = CollectionService:CreateCollection("Part.KillBrick")

-- When a part joins the collection, make it glow red
-- OnAdded fires once for each part already matching, then again for each new match
function killBricks.OnAdded(brick: Part)
	brick.Material = Enum.Material.Neon
	brick.Color = Color3.new(1, 0, 0)
end

-- Kill any humanoid that touches a matched part
function killBricks.OnTouched(brick: Part, otherPart: BasePart)
	local character: Instance? = otherPart.Parent
	local humanoid = character and character:FindFirstChildOfClass("Humanoid")
	if humanoid then
		humanoid.Health = 0
	end
end

-- Fires when a part stops matching (tag removed, reparented out, or destroyed)
function killBricks.OnRemoved(brick: Part)
	print("Deactivating", brick:GetFullName())
end

Notes#

• The collection remains active until you call Destroy() or its root is destroyed.
• Lifecycle callbacks are queued rather than invoked synchronously, so a newly assigned OnAdded may fire on a later resumption point rather than during the assignment itself.

Returns an array of all tags that currently have at least one tagged instance inside the DataModel. The returned array does not guarantee any particular ordering.

A tag appears in the result as soon as any instance bearing it enters the DataModel (for example by being parented to Workspace), and it is removed from the result once the last instance with that tag leaves the DataModel or has the tag removed. This means calling GetAllTags() immediately after removing the last instance with a given tag will no longer include that tag.

This function returns all instances of a given class which are in the DataModel. Only works for Configuration, CustomEvent, CustomEventReceiver, Dialog, and VehicleSeat.

Given a tag (string), this method returns a signal which fires under two conditions:

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

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

Subsequent calls to this method with the same tag return the same signal object. Consider also calling 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 DataModel).

See also GetInstanceRemovedSignal() which returns an event that fires under similar conditions.

Given a tag (string), this method returns a signal which fires under two conditions:

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

• An instance with the given tag is removed as a descendant of the DataModel, for example by un‑setting 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 GetInstanceAddedSignal() which returns an event that fires under similar conditions.

This method returns an array of instances with a given tag which are descendants of the DataModel. Removing a tag using CollectionService:RemoveTag() or 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 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 DataModel, for example its parent is nil; this method will not return such instances.

Given an 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 HasTag() to check for a single tag.

This method returns whether a given Instance has a tag.

By extension, any tags returned by a call to GetTags() on an instance will return true when used with this method.

This method removes a tag from an instance. Successfully removing a tag will fire a signal created by 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.

This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is added to the DataModel.

This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is removed from the DataModel.

This event fires when a tag transitions from being unused to being in use — specifically, when a tag is applied to an instance inside the DataModel and no other instance in the DataModel previously had that tag. The event passes the tag name as its parameter.

TagAdded fires once per tag lifetime, not once per instance. To detect every individual instance that receives a particular tag, use GetInstanceAddedSignal() instead.

The event fires asynchronously (deferred to the next resumption point), not synchronously inside the AddTag() call that triggered it.

This event fires when the last instance bearing a given tag leaves the DataModel or has the tag removed, meaning no instance in the DataModel still carries that tag. The event passes the tag name as its parameter.

TagRemoved fires once per tag lifetime, not once per instance. To detect every individual instance that loses a particular tag, use GetInstanceRemovedSignal() instead.

The event fires asynchronously (deferred to the next resumption point), not synchronously inside the removal operation that triggered it.