CollectionService

Supported Class Services NotCreatable Service

A service which manages instance collections using assigned tags.

Note: Tags and tag-change signals are supported.

10 Nova members · 6 modern Roblox members not implemented yet

Description

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.

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.

Inheritance

Object → Instance → CollectionService

Nova inheritance: Instance → CollectionService

Methods

AddTag Supported Function Applies a tag to an Instance.

CollectionService:AddTag(Instance instance, string tag)

Applies a tag to an Instance.

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().

Roblox reference signature

CollectionService:AddTag(instance: Instance, tag: string): null

Roblox documentation

GetCollection Supported Function Deprecated Returns all instances of a given class which are in the DataModel.

CollectionService:GetCollection(string class): Objects

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

Roblox reference signature

CollectionService:GetCollection(class: string): Instances

Roblox documentation

GetInstanceAddedSignal Supported Function Returns a signal that fires when a given tag is added to an instance.

GetInstanceAddedSignal(tag: string): RBXScriptSignal

Returns a signal that fires when a given tag is added to an instance.

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.

Roblox reference signature

CollectionService:GetInstanceAddedSignal(tag: string): RBXScriptSignal

Nova note: The API dump omits the custom descriptor's tag argument; the tag is required at runtime.

Roblox documentation

GetInstanceRemovedSignal Supported Function Returns a signal that fires when a given tag is removed from an instance.

GetInstanceRemovedSignal(tag: string): RBXScriptSignal

Returns a signal that fires when a given tag is removed from an instance.

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.

Roblox reference signature

CollectionService:GetInstanceRemovedSignal(tag: string): RBXScriptSignal

Nova note: The API dump omits the custom descriptor's tag argument; the tag is required at runtime.

Roblox documentation

GetTagged Supported Function Returns an array of instances in the game with a given tag.

CollectionService:GetTagged(string tag): Objects

Returns an array of instances in the game with a given tag.

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.

Roblox reference signature

CollectionService:GetTagged(tag: string): Instances

Roblox documentation

GetTags Supported Function Gets an array of all tags applied to a given instance.

CollectionService:GetTags(Instance instance): Array

Gets an array of all tags applied to a given instance.

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.

Roblox reference signature

CollectionService:GetTags(instance: Instance): Array

Roblox documentation

HasTag Supported Function Check whether an instance has a given tag.

CollectionService:HasTag(Instance instance, string tag): bool

Check whether an instance has a given 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.

Roblox reference signature

CollectionService:HasTag(instance: Instance, tag: string): bool

Roblox documentation

RemoveTag Supported Function Removes a tag from an instance.

CollectionService:RemoveTag(Instance instance, string tag): bool

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.

Roblox reference signature

CollectionService:RemoveTag(instance: Instance, tag: string): null

Roblox documentation

Events

ItemAdded Supported Event Deprecated Fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is added to the DataModel.

ItemAdded(Instance instance)

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

Roblox reference signature

ItemAdded(instance: Instance)

Roblox documentation

ItemRemoved Supported Event Deprecated Fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is removed from the DataModel.

ItemRemoved(Instance instance)

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

Roblox reference signature

ItemRemoved(instance: Instance)

Roblox documentation

Inherited members

Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.

6 modern Roblox member(s) are not implemented yet — expand to inspect

Members declared by Roblox's CollectionService class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.

Methods

Member	Signature	Status	Notes	Flags
CreateCollection	CollectionService:CreateCollection(query: string, root: Instance = nil): CollectionHandle	Not yet	Creates a Collection that tracks every instance matching a query.	—
GetAllTags	CollectionService:GetAllTags(): Array	Not yet	Returns an array of all tags in the experience.	—
GetTagAddedSignal	CollectionService:GetTagAddedSignal(instance: Instance): RBXScriptSignal	Not yet	—	RobloxScriptSecurity
GetTagRemovedSignal	CollectionService:GetTagRemovedSignal(instance: Instance): RBXScriptSignal	Not yet	—	RobloxScriptSecurity

Events

Member	Signature	Status	Notes	Flags
TagAdded	TagAdded(tag: string)	Not yet	Fires when a tag is added to an instance and the added tag is the only occurrence of that tag in the place.	—
TagRemoved	TagRemoved(tag: string)	Not yet	Fires when a tag is removed from an instance and the removed tag is no longer used anywhere in the place.	—

Roblox reference: CollectionService

Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.