CollectionService
A service which manages instance collections using assigned tags.
Memory category | Instances |
---|
Member index 13
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, 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.
History 43
- 648 Change ReturnType of GetTagged from Objects to Instances
- 648 Change ReturnType of GetCollection from Objects to Instances
- 637 Change Tags of RemoveTag from [] to [CustomLuaState]
- 637 Change Tags of HasTag from [] to [CustomLuaState]
- 637 Change Tags of GetTags from [] to [CustomLuaState]
- 637 Change Tags of AddTag from [] to [CustomLuaState]
- 607 Change Parameters of GetCollection from (clazz: string) to (class: string)
- 605 Change Parameters of GetCollection from (class: string) to (clazz: string)
- 573 Change ReturnType of RemoveTag from void to null
- 573 Change ReturnType of AddTag from void to null
- 553 Change PreferredDescriptor of ItemRemoved from to GetInstanceRemovedSignal
- 553 Change PreferredDescriptor of ItemAdded from to GetInstanceAddedSignal
- 553 Change PreferredDescriptor of GetCollection from to GetTagged
- 525 Add TagRemoved
- 525 Add TagAdded
- 525 Add GetAllTags
- 486 Change ThreadSafety of HasTag from ReadOnly to Safe
- 486 Change ThreadSafety of GetTags from ReadOnly to Safe
- 486 Change ThreadSafety of GetTagged from ReadOnly to Safe
- 462 Change ThreadSafety of ItemRemoved from to Unsafe
- 462 Change ThreadSafety of ItemAdded from to Unsafe
- 462 Change ThreadSafety of RemoveTag from to Unsafe
- 462 Change ThreadSafety of HasTag from to ReadOnly
- 462 Change ThreadSafety of GetTags from to ReadOnly
- 462 Change ThreadSafety of GetTagged from to ReadOnly
- 462 Change ThreadSafety of GetInstanceRemovedSignal from to Unsafe
- 462 Change ThreadSafety of GetInstanceAddedSignal from to Unsafe
- 462 Change ThreadSafety of GetCollection from to Unsafe
- 462 Change ThreadSafety of AddTag from to Unsafe
- 299 Change Tags of ItemRemoved from [] to [Deprecated]
- 299 Change Tags of ItemAdded from [] to [Deprecated]
- 299 Add RemoveTag
- 299 Add HasTag
- 299 Add GetTags
- 299 Add GetTagged
- 299 Add GetInstanceRemovedSignal
- 299 Add GetInstanceAddedSignal
- 299 Change Tags of GetCollection from [] to [Deprecated]
- 299 Add AddTag
- 47 Add ItemRemoved
- 47 Add ItemAdded
- 47 Add GetCollection
- 47 Add CollectionService
Members 13
AddTag
Parameters (2) | ||
---|---|---|
instance | Instance | |
tag | string | |
Returns (1) | ||
null |
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().
Thread safety | Unsafe |
---|
GetAllTags
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Array |
Returns an array of all tags in the experience.
Thread safety | Safe |
---|
History 1
- 525 Add GetAllTags
GetCollection
Parameters (1) | ||
---|---|---|
class | string | |
Returns (1) | ||
Instances |
This function returns all instances of a given class which are in the DataModel. Only works for Configuration, CustomEvent, CustomEventReceiver, Dialog, and VehicleSeat.
Thread safety | Unsafe |
---|
History 7
- 648 Change ReturnType of GetCollection from Objects to Instances
- 607 Change Parameters of GetCollection from (clazz: string) to (class: string)
- 605 Change Parameters of GetCollection from (class: string) to (clazz: string)
- 553 Change PreferredDescriptor of GetCollection from to GetTagged
- 462 Change ThreadSafety of GetCollection from to Unsafe
- 299 Change Tags of GetCollection from [] to [Deprecated]
- 47 Add GetCollection
GetInstanceAddedSignal
Parameters (1) | ||
---|---|---|
tag | string | |
Returns (1) | ||
RBXScriptSignal |
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.
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of GetInstanceAddedSignal from to Unsafe
- 299 Add GetInstanceAddedSignal
GetInstanceRemovedSignal
Parameters (1) | ||
---|---|---|
tag | string | |
Returns (1) | ||
RBXScriptSignal |
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.
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of GetInstanceRemovedSignal from to Unsafe
- 299 Add GetInstanceRemovedSignal
GetTagged
Parameters (1) | ||
---|---|---|
tag | string | |
Returns (1) | ||
Instances |
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.
Thread safety | Safe |
---|
GetTags
Parameters (1) | ||
---|---|---|
instance | Instance | |
Returns (1) | ||
Array |
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.
Thread safety | Safe |
---|
HasTag
Parameters (2) | ||
---|---|---|
instance | Instance | |
tag | string | |
Returns (1) | ||
bool |
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.
Thread safety | Safe |
---|
ItemAdded
Parameters (1) | |
---|---|
instance | Instance |
This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is added to the DataModel.
Thread safety | Unsafe |
---|
ItemRemoved
Parameters (1) | |
---|---|
instance | Instance |
This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is removed from the DataModel.
Thread safety | Unsafe |
---|
History 4
- 553 Change PreferredDescriptor of ItemRemoved from to GetInstanceRemovedSignal
- 462 Change ThreadSafety of ItemRemoved from to Unsafe
- 299 Change Tags of ItemRemoved from [] to [Deprecated]
- 47 Add ItemRemoved
RemoveTag
Parameters (2) | ||
---|---|---|
instance | Instance | |
tag | string | |
Returns (1) | ||
null |
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.
Thread safety | Unsafe |
---|
TagAdded
Parameters (1) | |
---|---|
tag | string |
This event fires when a tag is added to an instance and the added tag is the only occurrence of that tag in the place.
Thread safety | Unsafe |
---|
TagRemoved
Parameters (1) | |
---|---|
tag | string |
This event fires when a tag is removed from an instance and the removed tag is no longer used anywhere in the place.
Thread safety | Unsafe |
---|
History 1
- 525 Add TagRemoved