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 gestiona grupos (colecciones) de instancias con etiquetas .Las etiquetas son conjuntos de cadenas aplicados a instancias que se replican desde el servidor al cliente.También se serializan cuando se guardan 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 muchas instancias diferentes, un script que use CollectionService puede ser 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 gestionar directamente en Studio a través de la sección Etiquetas de las propiedades de una instancia o a través de la herramienta Editor de etiquetas integrada.
Replicación
Cuando las etiquetas se replican, todas las etiquetas en una instancia se replican al mismo tiempo .Por lo tanto, si estableces una etiqueta en una instancia desde el cliente, luego agrega/elimina una etiqueta diferente en la misma instancia desde el servidor, las etiquetas locales de la instancia del cliente se reemplazan.En StreamingEnabled lugares, las instancias se pueden descargar cuando salen del área transmitida del cliente.Si tal instancia vuelve a entrar en el área transmitida, las propiedades y etiquetas se sincronizarán nuevamente desde el servidor.Esto puede causar que los cambios realizados por LocalScripts sean reemplazados/removidos.
Resumen
Métodos
Aplica una etiqueta a un Instance .
Devuelve un array de todas las etiquetas en la experiencia.
Devuelve una señal que se activa cuando se agrega una etiqueta dada a una instancia.
Devuelve una señal que se activa cuando se elimina una etiqueta dada de una instancia.
Devuelve un array de instancias en el juego con una etiqueta dada.
Obtiene un array de todas las etiquetas aplicadas a una instancia dada.
Compruebe si una instancia tiene una etiqueta determinada.
Elimina una etiqueta de una instancia.
Eventos
Se activa cuando se agrega una etiqueta a una instancia y la etiqueta agregada es la única ocurrencia de esa etiqueta en el lugar.
Se activa cuando se elimina una etiqueta de una instancia y la etiqueta eliminada ya no se usa en ningún lugar del lugar.
Propiedades
Métodos
AddTag
Este método aplica una etiqueta a un Instance , sin hacer nada si la etiqueta ya se aplica a esa instancia.Añadir con éxito una etiqueta disparará una señal creada por GetInstanceAddedSignal() con la etiqueta dada.
Advertencias
Las etiquetas de una instancia que se agregaron en el lado del cliente se eliminarán si el servidor luego agrega o elimina una etiqueta en esa instancia porque el servidor replica todas las etiquetas juntas y reemplaza etiquetas anteriores.
Cuando se etiqueta una instancia, es común que se utilicen algunos recursos para darle al etiqueta su funcionalidad, por ejemplo conexiones de eventos o tablas.Para evitar fugas de memoria, es una buena idea limpiarlas (desconectarse, establecer en nil , etc.) cuando ya no se necesitan para una etiqueta.Haz esto al llamar RemoveTag() , llamar Instance:Destroy() o en una función conectada a una señal devuelta por GetInstanceRemovedSignal() .
Parámetros
Devuelve
GetInstanceAddedSignal
Dada una etiqueta (cadena), este método devuelve una señal que se activa bajo dos condiciones:
La etiqueta se asigna a una instancia dentro del DataModel usando CollectionService:AddTag() o Instance:AddTag() .
Se agrega una instancia con la etiqueta dada como descendiente del DataModel, por ejemplo, al establecer Instance.Parent o similar.
Llamadas posteriores a este método con la misma etiqueta devuelven el mismo objeto de señal.Considera también llamar GetTagged() para obtener una lista de instancias que ya tienen una etiqueta (y por lo tanto no dispararán el evento si ya están en el DataModel ).
Vea también GetInstanceRemovedSignal() que devuelve un evento que se activa bajo condiciones similares.
Parámetros
La etiqueta para vigilar.
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
Dada una etiqueta (cadena), este método devuelve una señal que se activa bajo dos condiciones:
La etiqueta se elimina de una instancia dentro del DataModel usando CollectionService:RemoveTag() o Instance:RemoveTag() .
Se elimina una instancia con la etiqueta dada como descendiente del DataModel, por ejemplo, desactivando Instance.Parent o similar.
Llamadas posteriores 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 instancias que una vez tenían etiquetas, como desconectar conexiones.
Vea también GetInstanceAddedSignal() que devuelve un evento que se activa bajo condiciones similares.
Parámetros
La etiqueta para vigilar.
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
Este método devuelve un array de instancias con una etiqueta dada que son descendientes del DataModel.Eliminar una etiqueta usando CollectionService:RemoveTag() o Instance:RemoveTag() asegura que este método no los devuelva.
Si quieres detectar todas las instancias con una etiqueta, ambas presentan y futuro, usa este método para iterar sobre las instancias mientras también estableces una conexión con una señal devuelta por GetInstanceAddedSignal() .
Este método no garantiza ningún orden de las instancias devueltas.Además, es posible que las instancias puedan tener la etiqueta dada asignada a ellas pero no sean un descendiente del DataModel, por ejemplo, su padre es nil ; este método no devolverá tales instancias.
Parámetros
La etiqueta para buscar.
Devuelve
Un array de todas las instancias con la etiqueta.
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
Dada una Instance, este método devuelve un array de cadenas que son las etiquetas aplicadas a la instancia.
Este método es útil cuando quieres hacer algo con múltiples etiquetas de instancia a la vez, pero es ineficiente verificar la existencia de una sola etiqueta.Para esto, use HasTag() para verificar una etiqueta única.
Parámetros
La instancia cuyas etiquetas deben devolverse.
Devuelve
Un array de cadenas que son las etiquetas aplicadas a la instancia dada.
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
Este método devuelve si un dado Instance tiene una etiqueta.
Por extensión, cualquier etiqueta devuelta por una llamada a GetTags() en una instancia devolverá true cuando se use con este método.
Parámetros
La instancia para verificar la presencia de una etiqueta.
La etiqueta para comprobar.
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
Este método elimina una etiqueta de una instancia. Eliminar con éxito una etiqueta disparará una señal creada por GetInstanceRemovedSignal() con la etiqueta dada.
Al eliminar una etiqueta, es común que se utilicen algunos recursos para darle a la etiqueta su funcionalidad, por ejemplo, conexiones de eventos o tablas.Para evitar fugas de memoria, es una buena idea limpiarlas (desconectarse, establecer en nil , etc.) cuando ya no se necesitan para una etiqueta.
Parámetros
La instancia para eliminar la etiqueta de.
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 una instancia 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 una instancia y la etiqueta eliminada ya no se usa en ninguna parte del lugar.