Roblox Forum

Posted: **Sun Oct 18, 2026 6:38 am**

Roblox CollectionService: Tagging, Tracking, and Querying Instances in Your Game

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

GetTagged returns instances that are descendants of the DataModel. Removing a tag ensures they are no longer returned by it.[3]

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

Subsequent calls to GetInstanceAddedSignal with the same tag return the same signal object, so you can safely call it multiple times without duplicating connections.[2]

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)

Deprecated Methods to Avoid

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

FAQ

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.

Sources

[1] CollectionService | Roblox Creator Hub Documentation
[2] CollectionService | Roblox API Reference
[3] CollectionService:GetTagged | Roblox Creator Hub