CollectionService is a built-in Roblox service that lets you attach string tags to any instance and then query them from a single script. Instead of putting the same behavior script into dozens of parts, you tag the parts once and let one script handle them all. This guide covers the core methods, the event pattern for present and future instances, and common pitfalls.
Why CollectionService Exists
If you find yourself adding the same script to many different instances, a script that uses CollectionService may be better.[1] It decouples the behavior from the hierarchy. You tag an instance wherever it lives in the DataModel, and a single server script finds it by name.
Tags can be added or removed through the service methods or managed directly in Studio through the Tags section of an instance's properties.[2]
Core Methods
- AddTag(instance, tag): attaches a tag to an instance
- RemoveTag(instance, tag): removes a tag
- GetTagged(tag): returns an array of all instances with that tag
- GetTags(instance): returns an array of all tags on one instance
- HasTag(instance, tag): returns a boolean
The Event Pattern: Present and Future Instances
GetTagged gives you a snapshot at the moment you call it. To also catch instances that get tagged later, connect to the signals:[3]
Code: Select all
CollectionService:GetInstanceAddedSignal(tag):Connect(onInstanceAdded)
CollectionService:GetInstanceRemovedSignal(tag):Connect(onInstanceRemoved)
-- Also handle any instances that already have the tag
for _, object in pairs(CollectionService:GetTagged(tag)) do
onInstanceAdded(object)
end
A Working Example
This pattern causes any BasePart with the tag "Deadly" to kill any Humanoid that touches it, and it disconnects when the tag is removed:[3]
Code: Select all
local function onInstanceAdded(part)
part.Touched:Connect(function(hit)
local humanoid = hit.Parent:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid.Health = 0
end
end)
end
for _, part in pairs(CollectionService:GetTagged("Deadly")) do
onInstanceAdded(part)
end
CollectionService:GetInstanceAddedSignal("Deadly"):Connect(onInstanceAdded)
GetCollection is deprecated and exists only for backward compatibility. Use GetTagged instead.[2] The old ItemAdded and ItemRemoved events are also deprecated; use GetInstanceAddedSignal and GetInstanceRemovedSignal.[1]
Thread safety for GetTagged is marked Unsafe, so avoid calling it from parallel Lua threads without care.[2]
Common Use Cases
- Hazards: tag deadly parts and handle Touched in one place
- Objectives: tag quest items and track collection progress
- Spawners: tag spawn points and pick one at random
- Config: tag instances that should receive settings at startup
- Where do I add tags in Studio? Select an instance and use the Tags section in its properties panel.[2]
- Can a script add tags to itself? Yes. AddTag works on any instance including the script's own Parent.
- Does GetTagged include instances created after the call? No. That is why you also connect to GetInstanceAddedSignal.[3]
- Is GetCollection still safe to use? It is deprecated. Use GetTagged for new work.[2]
- Do tags replicate to the client? Tags are set on the server. Use RemoteEvents if the client needs to know about them.
[1] CollectionService | Roblox Creator Hub Documentation
[2] CollectionService | Roblox API Reference
[3] CollectionService:GetTagged | Roblox Creator Hub