Open Asterune
TagService

TagService

Queries tagged instances and provides tag change signals.

Service
game:GetService("TagService")
Inherits
Instance
Replication
Never

Behavior

TagService queries instances by string tag, regardless of their parent or class. Instances own their tags. The service provides queries and signals for tagged sets.

Connect to the added signal before the initial GetTagged query to track additions during setup. Make setup safe to repeat for the same instance.

Summary

Members8
Properties3
  • Archivable: boolean = trueparallel readoverrides Instance

    Whether the service instance is included when its containing hierarchy is cloned or saved.

  • Name: string = "TagService"parallel readoverrides Instance

    The instance name.

  • Parent: Instance? = nilparallel readoverrides Instance

    The service's parent instance.

Methods5

Properties

Archivable

TagService.Archivable: boolean = true

Whether the service instance is included when its containing hierarchy is cloned or saved. The default is true.

Name

TagService.Name: string = "TagService"

The instance name. The default is "TagService".

Parent

TagService.Parent: Instance? = nil

The service's parent instance. The default is nil.

Methods

GetAddedSignal

TagService:GetAddedSignal(tag: string): AstScriptSignal

Returns a signal that fires when an instance gains the specified tag.

GetAllTags

TagService:GetAllTags(): table

Returns an array of tag names known to the service.

GetExecutionGroup

TagService:GetExecutionGroup(): ExecutionGroup?

Returns this instance if it is an ExecutionGroup. Otherwise returns the nearest ancestor ExecutionGroup, or nil when no group contains the instance.

GetRemovedSignal

TagService:GetRemovedSignal(tag: string): AstScriptSignal

Returns a signal that fires when an instance loses the tag or leaves the hierarchy.

GetTagged

TagService:GetTagged(tag: string): table

Returns an array of instances carrying the specified tag. Includes instances outside workspace.

Inherited members

Inherited44
Instance44
Properties
ClassName
Methods
AddComponent()AddTag()ClearAllChildren()ClearTags()Clone()Destroy()FindFirstAncestor()FindFirstAncestorOfClass()FindFirstAncestorWhichIsA()FindFirstChild()FindFirstChildOfClass()FindFirstChildWhichIsA()FindFirstDescendant()GetAttribute()GetAttributeChangedSignal()GetAttributes()GetChildren()GetComponent()GetComponentChangedSignal()GetComponents()GetDebugId()GetDescendants()GetFullName()GetPropertyChangedSignal()GetReferencing()GetTags()HasComponent()HasTag()IsA()IsAncestorOf()IsDescendantOf()RemoveComponent()RemoveTag()SetAttribute()WaitForChild()
Events
AncestryChangedAttributeChangedChangedChildAddedChildRemovedDescendantAddedDescendantRemovingDestroying

Examples

Luau
local TagService = game:GetService("TagService")
for _, instance in TagService:GetTagged("Checkpoint") do
  print(instance.Name)
end
Luau
-- Server Script. Records contacts with Parts tagged Checkpoint.
local TagService = game:GetService("TagService")
local Players = game:GetService("Players")

local TAG = "Checkpoint"

-- Keep checkpoint state per player across character respawns.
local reached = {}
local watched = setmetatable({}, { __mode = "k" })

local function onTouched(pad, hit)
  local character = hit.Parent
  local player = character and Players:GetPlayerFromCharacter(character)
  if not player then
    return
  end

  if reached[player] == pad then
    return
  end

  reached[player] = pad
  print(player.Name .. " reached " .. pad.Name)
end

local function watch(pad)
  if not pad:IsA("BasePart") or watched[pad] then
    return
  end
  watched[pad] = true
  pad.Touched:Connect(function(hit)
    onTouched(pad, hit)
  end)
end

TagService:GetAddedSignal(TAG):Connect(watch)

for _, pad in TagService:GetTagged(TAG) do
  watch(pad)
end

Players.PlayerRemoving:Connect(function(player)
  reached[player] = nil
end)

Related APIs

Instance · Folder · Workspace