CollectionService
*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.
CollectionService administra grupos (colecciones) de instancias con etiquetas . Las etiquetas son conjuntos de cadenas aplicadas a los objetos que se replican desde el servidor al cliente. También son serializadas cuando se guardan los lugares.
El uso principal de CollectionService es registrar instancias con etiquetas específicas que puedes usar para extender su comportamiento. Si te encuentras agregando el mismo script a muchos objetos diferentes, tal vez un script que usa CollectionService sería mejor.
Las etiquetas se pueden agregar o eliminar a través de los métodos de esta clase, como AddTag() o RemoveTag(). También se pueden administrar directamente en Studio a través de la sección Etiquetas de las propiedades de una instancia, o a través de la herramienta de 1>Editor de etiquetas</
Replicación
Cuando las etiquetas se replican, todas las etiquetas en un objeto se replican al mismo tiempo . Por lo tanto, si estableces una etiqueta en un objeto desde el cliente,
Resumen
Métodos
Aplica una etiqueta a un Instance .
Devuelve una señal que se activa cuando se agrega una etiqueta a un objeto.
Devuelve una señal que se activa cuando se elimina una etiqueta específica de una instancia.
Devuelve un arreglo de objetos en el juego con una etiqueta especificada.
Obtiene un arreglo de todas las etiquetas aplicadas a un objeto específico.
Compruebe si un objeto tiene una etiqueta especificada.
Elimina una etiqueta de una instancia.
Eventos
Se activa cuando se agrega una etiqueta a un objeto y la etiqueta agregada es la única ocasión de esa etiqueta en el lugar.
Se activa cuando se elimina una etiqueta de un objeto y la etiqueta eliminada ya no se usa en ninguna parte del lugar.
Propiedades
Métodos
AddTag
AddTag aplicará una etiqueta a un Instance , no haciendo nada si la etiqueta ya se ha aplicado a la instancia. El éxito de añadir una etiqueta se activará con el lanzamiento de un mensaje creado por CollectionService:GetInstanceAddedSignal() con la etiqueta proporcionada.
Atención/advertencia: Cuando se etiqueta una instancia, es común que se utilicen algunos recursos para proporcionar la funcionalidad de la etiqueta, como conexiones de eventos o tablas. Para evitar fugas de memoria, es una buena idea limpiar estos (desconectar, establecer a
Parámetros
Devuelve
GetInstanceAddedSignal
GetInstanceAdded se da una etiqueta (una cadena) y devuelve un mensaje que se activa bajo dos condiciones:
- La etiqueta se asigna a una instancia dentro del DataModel (juego) usando CollectionService:AddTag() o Instance:AddTag() .
- Se agrega una instancia con la etiqueta proporcionada como descendiente del DataModel , por ejemplo, al establecer Instance.Parent o similar.
Las siguientes llamadas a este método con la misma etiqueta devuelven el mismo objeto de señal. Considere también llamar CollectionService:GetTagged() para obtener una lista de objetos que ya tienen una etiqueta (y por lo tanto no disparar el evento si ya están en el DataModel ).
También se vea CollectionService:GetInstanceRemovedSignal(), que devuelve un evento que se activa bajo condiciones similares.
Parámetros
La etiqueta para mirar.
Devuelve
Un evento que se activa cuando agregas la etiqueta a una instancia.
Muestras de código
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
GetInstanceRemoved tiene una etiqueta (una cadena) y devuelve una señal que se activa bajo dos condiciones:
- La etiqueta se elimina de una instancia dentro del DataModel (juego) usando CollectionService:RemoveTag() o Instance:RemoveTag() .
- Una instancia con el atributo dado se elimina como descendiente del DataModel, por ejemplo, al desactivar Instance.Parent o similar.
Las llamadas siguientes a este método con la misma etiqueta devuelven el mismo objeto de señal. La señal es útil para limpiar los recursos utilizados por los objetos que una vez tenían etiquetas, como desconectar conexiones.
También se vea CollectionService:GetInstanceAddedSignal(), que devuelve un evento que se activa bajo condiciones similares.
Parámetros
La etiqueta para mirar.
Devuelve
Un evento que se activa cuando eliminas la etiqueta de una instancia.
Muestras de código
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
GetTagged返回一个拥有指定标签的对象阵列，其子是DataModel (game). Estos tags se han agregado使用CollectionService:AddTag()，并使用1>Class.CollectionService
Si desea detectar todos los objetos con una etiqueta, tanto los presentes como los futuros, use este método para repasar los objetos mientras también se hace una conexión a un señal devuelta por CollectionService.GetInstanceAddedSignal .
Este método no garantiza ninguna orden de los objetos devueltos. Además, es posible que los objetos puedan tener la etiqueta asignada a ellos, pero no ser un descendiente del DataModel , es decir, su padre es nulo. Este método no devolverá tales objetos.
Parámetros
La etiqueta para buscar.
Devuelve
Un arreglo de todas las instancias con el tag.
Muestras de código
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
GetTags recibe una instancia y devuelve un arreglo de cadenas, que son las etiquetas aplicadas al objeto dado.
Este método es útil cuando quieres hacer algo con múltiples etiquetas a la vez en un objeto. Sin embargo, sería ineficiente usar este método para verificar la existencia de una sola etiqueta. Para esto, usa CollectionService:HasTag() para verificar una sola etiqueta.
Parámetros
El objeto cuyas etiquetas se deben返回。
Devuelve
Un arreglo de cadenas que son las etiquetas aplicadas al objeto dado.
Muestras de código
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
HasTag返回给定对象是否有标签。
- Usar CollectionService:AddTag() para agregar la etiqueta causará que este método devuelva true.
- Usar CollectionService:RemoveTag() para eliminar la etiqueta causará que este método devuelva false.
Por extensión, cualquier etiqueta devuelta por una llamada a CollectionService:GetTags() en un objeto devolverá true cuando se usa con este método.
Parámetros
La instancia para verificar la presencia de una etiqueta.
La etiqueta para chequear.
Devuelve
Si la instancia tiene la etiqueta.
Muestras de código
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
Eliminar etiqueta eliminará una etiqueta de una instancia. Este método no lanzará un error si el objeto no tenía la etiqueta en primer lugar. El éxito de la eliminación de una etiqueta creará una señal creada por CollectionService:GetInstanceRemovedSignal() con la etiqueta proporcionada.
Al eliminar una etiqueta, es común que se utilicen algunos recursos para proporcionar la funcionalidad de la etiqueta, por ejemplo, conexiones de eventos o tablas. Para evitar fugas de memoria, es una buena idea limpiar estos (desconectar, establecer a cero, etc) cuando ya no se necesitan para una etiqueta.
Parámetros
La instancia para eliminar la etiqueta.
La etiqueta para eliminar de la instancia.
Devuelve
Muestras de código
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")
Eventos
TagAdded
Este evento se activa cuando se agrega una etiqueta a un objeto y la etiqueta agregada es la única ocurrencia de esa etiqueta en el lugar.
Parámetros
TagRemoved
Este evento se activa cuando se elimina una etiqueta de un objeto y la etiqueta eliminada ya no se usa en ninguna parte del lugar.