CollectionService
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 AddTag() or RemoveTag(). They can also be managed directly in Studio through the Tags section of an instance's properties, or through the built‑in Tag Editor tool.
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 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 LocalScripts to be overwritten/removed.
Summary
Methods
Applies a tag to an Instance.
Returns an array of all tags in the experience.
Returns a signal that fires when a given tag is added to an instance.
Returns a signal that fires when a given tag is removed from an instance.
Returns an array of instances in the game with a given tag.
Gets an array of all tags applied to a given instance.
Check whether an instance has a given tag.
Removes a tag from an instance.
Events
Fires when a tag is added to an instance and the added tag is the only occurrence of that tag in the place.
Fires when a tag is removed from an instance and the removed tag is no longer used anywhere in the place.
Properties
Methods
AddTag
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().
Parameters
Returns
GetInstanceAddedSignal
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.
Parameters
The tag to watch for.
Returns
An event that fires when you add the tag to an instance.
Code Samples
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
endGetInstanceRemovedSignal
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.
Parameters
The tag to watch for.
Returns
An event that fires when you remove the tag from an instance.
Code Samples
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
endGetTagged
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.
Parameters
The tag to search for.
Returns
An array of all instances with the tag.
Code Samples
This code sample causes any BasePart with the tag Deadly to kill any Humanoid that touches it. It does this using a common pattern with CollectionService to listen for all parts with the tag and make a connection, then disconnect the connection when the tag is removed.
local CollectionService = game:GetService("CollectionService")
local tag = "Deadly"
local function onDeadlyPartTouched(otherPart)
if not otherPart.Parent then
return
end
local humanoid = otherPart.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end
-- Save the connections so they can be disconnected when the tag is removed
local connections = {}
local function onInstanceAdded(object)
-- Confirm that the object with this tag is a BasePart
if object:IsA("BasePart") then
connections[object] = object.Touched:Connect(onDeadlyPartTouched)
end
end
local function onInstanceRemoved(object)
-- If there is a stored connection on this object, disconnect/remove it
if connections[object] then
connections[object]:Disconnect()
connections[object] = nil
end
end
-- Listen for this tag being applied to objects
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also detect any objects that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
endGetTags
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.
Parameters
The instance whose tags should be returned.
Returns
An array of strings which are the tags applied to the given instance.
Code Samples
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")HasTag
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.
Parameters
The instance to check for the presence of a tag.
The tag to check for.
Returns
Whether the instance has the tag.
Code Samples
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")RemoveTag
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.
Parameters
The instance to remove the tag from.
The tag to remove from the instance.
Returns
Code Samples
This code sample demonstrates adding, removing and querying a tag from an object using CollectionService.
local CollectionService = game:GetService("CollectionService")
local Workspace = game:GetService("Workspace")
local object = Workspace.Part
-- Add a tag
CollectionService:AddTag(object, "Deadly")
-- Query for a tag
if CollectionService:HasTag(object, "Deadly") then
print(object:GetFullName() .. " is deadly")
end
-- List tags on an object
local tags = CollectionService:GetTags(object)
print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-- Remove a tag
CollectionService:RemoveTag(object, "Deadly")