CollectionService
*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.
CollectionService gerencia grupos (coleções) de instâncias com tags .Tags são conjuntos de strings aplicados a instâncias que se replicam do servidor para o cliente.Eles também são serializados quando os locais são salvos.
O uso principal de CollectionService é registrar instâncias com tags específicas que você pode usar para estender seu comportamento.Se você se encontrar adicionando o mesmo script a muitas instâncias diferentes, um script que use CollectionService pode ser melhor.
Tags podem ser adicionadas ou removidas através dos métodos desta classe, como AddTag() ou RemoveTag().Eles também podem ser gerenciados diretamente no Studio através da seção Tags das propriedades de uma instância ou através da ferramenta Editor de Tags Incorporado.
Replicação
Quando as etiquetas se replicam, todas as etiquetas em uma instância se replicam ao mesmo tempo .Portanto, se você definir uma etiqueta em uma instância do cliente, então adicione/remova uma etiqueta diferente na mesma instância do servidor, as etiquetas locais do cliente na instância são substituídas.Em StreamingEnabled lugares, instâncias podem ser descarregadas enquanto deixam a área transmitida do cliente.Se tal instância reentrar na área transmitida, propriedades e tags serão re sincronizadas do servidor.Isso pode causar alterações feitas por LocalScripts serem substituídas/removidas.
Resumo
Métodos
Aplica uma etiqueta a um Instance .
Retorna um array de todas as tags na experiência.
Retorna um sinal que dispara quando uma tag dada é adicionada a uma instância.
Retorna um sinal que dispara quando uma tag dada é removida de uma instância.
Retorna um conjunto de instâncias no jogo com uma tag dada.
Obtém um array de todas as tags aplicadas a uma dada instância.
Verifique se uma instância tem uma tag dada.
Remove uma etiqueta de uma instância.
Eventos
Incêndios quando uma tag é adicionada a uma instância e a tag adicionada é a única ocorrência dessa tag no local.
Incêndios quando uma tag é removida de uma instância e a tag removida não é mais usada em nenhum lugar no local.
Propriedades
Métodos
AddTag
Este método aplica uma etiqueta a um Instance , não fazendo nada se a etiqueta já for aplicada a essa instância.Adicionar com sucesso uma tag disparará um sinal criado por GetInstanceAddedSignal() com a tag fornecida.
Avertimentos
As tags de uma instância que foram adicionadas do lado do cliente serão descartadas se o servidor adicionar ou remover uma tag nessa instância mais tarde, pois o servidor replica todas as tags juntas e substitui as tags anteriores.
Ao rotular uma instância, é comum que alguns recursos sejam usados para dar à etiqueta sua funcionalidade, por exemplo, conexões de eventos ou tabelas.Para evitar vazamentos de memória, é uma boa ideia limpar esses (desconectar, definir como nil , etc.) quando não forem mais necessários para uma etiqueta.Faça isso ao chamar RemoveTag() , chamando Instance:Destroy() ou em uma função conectada a um sinal retornado por GetInstanceRemovedSignal() .
Parâmetros
Devolução
GetInstanceAddedSignal
Dada uma tag (string / cadeia / texto), este método retorna um sinal que dispara sob duas condições:
A etiqueta é atribuída a uma instância dentro do DataModel usando CollectionService:AddTag() ou Instance:AddTag() .
Uma instância com a tag dada é adicionada como descendente do DataModel, por exemplo, definindo Instance.Parent ou similar.
Chamadas subsequentes a este método com a mesma tag retornam o mesmo Objetode sinal.Considere também chamar GetTagged() para obter uma lista de instâncias que já possuem uma tag (e, portanto, não dispararão o evento se já estiverem no DataModel ).
Veja também GetInstanceRemovedSignal() que retorna um evento que dispara em condições semelhantes.
Parâmetros
A etiqueta para observar.
Devolução
Um evento que dispara quando você adiciona a tag a uma instância.
Amostras 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 uma tag (string / cadeia / texto), este método retorna um sinal que dispara sob duas condições:
A etiqueta é removida de uma instância dentro do DataModel usando CollectionService:RemoveTag() ou Instance:RemoveTag() .
Uma instância com a tag dada é removida como descendente do DataModel, por exemplo, ao desativar Instance.Parent ou similar.
Chamadas subsequentes a este método com a mesma tag retornam o mesmo Objetode sinal.O sinal é útil para limpar recursos usados por instâncias que, uma vez, tinham tags, como desconectar conexões.
Veja também GetInstanceAddedSignal() que retorna um evento que dispara em condições semelhantes.
Parâmetros
A etiqueta para observar.
Devolução
Um evento que dispara quando você remove a tag de uma instância.
Amostras 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 retorna um conjunto de instâncias com uma tag dada que são descendentes do DataModel.Remover uma etiqueta usando CollectionService:RemoveTag() ou Instance:RemoveTag() garante que este método não os retorne.
Se você quiser detectar todas as instâncias com uma tag, ambas apresentam e futuro, use este método para iterar sobre instâncias enquanto também faz uma conexão com um sinal retornado por GetInstanceAddedSignal() .
Este método não garante qualquer ordem das instâncias retornadas.Além disso, é possível que as instâncias possam ter a tag dada atribuída a elas, mas não serem descendentes do DataModel, por exemplo, seu pai é nil ; este método não retornará tais instâncias.
Parâmetros
A tag para procurar.
Devolução
Um array de todas as instâncias com a tag.
Amostras 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 uma Instance , este método retorna um array de strings que são as tags aplicadas à instância.
Este método é útil quando você quer fazer algo com várias tags de instância de uma só vez, mas é ineficiente verificar a existência de uma única tag.Para isso, use HasTag() para verificar uma única tag.
Parâmetros
A instância cujas tags devem ser retornadas.
Devolução
Um conjunto de strings que são as tags aplicadas à instância dada.
Amostras 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 retorna se um dado Instance tem uma tag.
Por extensão, quaisquer tags retornadas por uma chamada para GetTags() em uma instância retornarão true quando usadas com este método.
Parâmetros
A instância para verificar a presença de uma tag.
A tag para verificar.
Devolução
Se a instância tem a tag.
Amostras 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 remove uma tag de uma instância. A remoção bem-sucedida de uma tag disparará um sinal criado por GetInstanceRemovedSignal() com a tag fornecida.
Ao remover uma tag, é comum que alguns recursos sejam usados para dar à tag sua funcionalidade, por exemplo, conexões de eventos ou tabelas.Para evitar vazamentos de memória, é uma boa ideia limpar esses (desconectar, definir como nil , etc.) quando não forem mais necessários para uma etiqueta.
Parâmetros
A instância para remover a tag de.
A tag para remover da instância.
Devolução
Amostras 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 dispara quando uma tag é adicionada a uma instância e a tag adicionada é a única ocorrência dessa tag no local.
Parâmetros
TagRemoved
Este evento dispara quando uma tag é removida de uma instância e a tag removida não é mais usada em nenhum lugar no local.