TagService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [TagService]（6 函数 / 2 事件）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

TagService 是全局标签管理服务，负责给 SpaceUnit 对象附加字符串标签，并从「对象查标签」和「标签查对象」两个方向提供查询能力。它既支持用 HasTag、GetTags 查看单个对象身上的标签，也支持用 GetAllTags、GetTagged 列举已注册标签或某个标签下的对象集合。此外还提供 TagAdded 与 TagRemoved 两个本端事件，便于在标签发生变化时及时响应。

适用场景

常用于为地图中的对象打上自定义分类标签，例如把同类可交互物统一标记后，再按标签批量检索并集中处理逻辑；也可与 RemoteEvent 配合，在服务端修改标签后通知客户端刷新对应的表现或状态。

使用要点

先通过 game:GetService("TagService") 获取服务实例，再调用 AddTag(unit, tag) 或 RemoveTag(unit, tag) 修改指定 SpaceUnit 的标签集合。查询时用 HasTag 判断单个标签是否存在、用 GetTags 取出该对象的全部标签，用 GetAllTags 列举当前已注册的标签，用 GetTagged(tag) 反查带有该标签的对象。需要响应变化时可监听 TagAdded 与 TagRemoved 事件；若要在服务端与客户端之间可靠同步标签改动，应额外借助 RemoteEvent 传递显式消息。

注意事项

TagService 的 AddTag/RemoveTag 当前以本端状态变更为主，跨客户端同步与事件广播语义需以运行包实测为准。当前运行包还存在客户端初始化完成后新增标签未进入 GetTagged 本地索引的反馈，无论标签由服务端还是客户端添加，都不要把客户端 GetTagged 结果视为完整动态注册表。若业务要求服务端改 Tag 后客户端稳定感知，建议同时通过 RemoteEvent/RemoteFunction 发送显式同步消息，并由业务层维护对象集合。

代码示例

安全创建临时单位并验证标签

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'DemoTag')
print('标签已添加:', TagService:HasTag(unit, 'DemoTag'))
unit:Destroy()

关联类型

• Unit

事件 (2)

TagAdded

签名：TagAdded(tag: String) 触发：local

当任意 SpaceUnit 实例首次被添加某个标签时触发，提供被添加的标签字符串。

回调参数	类型	说明
tag	String	新增的标签

示例代码

监听标签首次出现

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
local connection = TagService.TagAdded:Connect(function(tag) print('新标签:', tag) end)
TagService:AddTag(unit, 'DemoAddedTag')
connection:Disconnect()
unit:Destroy()

TagRemoved

签名：TagRemoved(tag: String) 触发：local

当任意 SpaceUnit 实例的某个标签被完全移除时触发，提供被移除的标签字符串。

回调参数	类型	说明
tag	String	移除的标签

示例代码

监听标签完全移除

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'DemoRemovedTag')
local connection = TagService.TagRemoved:Connect(function(tag) print('标签已移除:', tag) end)
TagService:RemoveTag(unit, 'DemoRemovedTag')
connection:Disconnect()
unit:Destroy()

函数 (6)

AddTag

签名：AddTag(unit: SpaceUnit, tag: String) -> void

给指定的空间组件添加一个字符串标签。调用后该组件即被标记上该标签，可通过 HasTag、GetTags 或 GetTagged 查询到。该函数没有返回值。

参数	类型	说明
unit	SpaceUnit	组件
tag	String	标签

返回值 void

示例代码

为临时单位添加标签

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'Enemy')
print('是否拥有 Enemy:', TagService:HasTag(unit, 'Enemy'))
unit:Destroy()

RemoveTag

签名：RemoveTag(unit: SpaceUnit, tag: String) -> void

从指定的空间组件上移除一个标签。移除后该组件不再拥有该标签，该函数没有返回值。

参数	类型	说明
unit	SpaceUnit	组件
tag	String	标签

返回值 void

示例代码

从临时单位移除标签

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'Temporary')
TagService:RemoveTag(unit, 'Temporary')
print('移除后仍存在:', TagService:HasTag(unit, 'Temporary'))
unit:Destroy()

HasTag

签名：HasTag(unit: SpaceUnit, tag: String) -> Bool (是否拥有标签)

判断指定空间组件是否拥有某个标签，返回布尔值，拥有为真，否则为假。

参数	类型	说明
unit	SpaceUnit	组件
tag	String	标签

返回值 Bool (是否拥有标签)

示例代码

检查临时单位的标签

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'Interactive')
print('是否可交互:', TagService:HasTag(unit, 'Interactive'))
unit:Destroy()

GetTags

签名：GetTags(unit: SpaceUnit) -> Array<String> (标签列表)

获取指定空间组件当前拥有的全部标签，返回一个字符串数组。

参数	类型	说明
unit	SpaceUnit	组件

返回值 Array<String> (标签列表)

示例代码

读取临时单位的全部标签

-- @runtime client
local TagService = game:GetService('TagService')
local World = game:GetService('World')
local unit = World:CreateUnit('WorldUnit', {})
if unit == nil then return end
TagService:AddTag(unit, 'NPC')
for _, tag in ipairs(TagService:GetTags(unit)) do print('单位标签:', tag) end
unit:Destroy()

GetAllTags

签名：GetAllTags() -> Array<String> (标签列表)

获取当前游戏中所有已存在的标签列表。

返回值 Array<String> (标签列表)

示例代码

读取当前端已有的全部标签名

-- @runtime client
local TagService = game:GetService('TagService')
for _, tag in ipairs(TagService:GetAllTags()) do
    print('当前标签:', tag)
end

GetTagged

签名：GetTagged(tag: String) -> Array<SpaceUnit> (组件列表)

获取当前拥有指定标签的全部空间组件，返回一个 SpaceUnit 数组。

⚙ GetTagged 返回当前端已建立索引的标签快照。当前运行包实测客户端初始化完成后新增的标签对象可能不会进入该结果；关键业务应维护显式对象集合或通过 RemoteEvent/RemoteFunction 同步，不能把 GetTagged 当作完整动态注册表。

参数	类型	说明
tag	String	标签

返回值 Array<SpaceUnit> (组件列表)

示例代码

读取当前端已有的标签快照

-- @runtime client
local TagService = game:GetService('TagService')
local taggedSnapshot = TagService:GetTagged('Enemy')
for _, unit in ipairs(taggedSnapshot) do
    print('当前索引中的对象:', unit.Name)
end
-- 动态新增对象请由业务层另行维护和同步，不要把该快照当作完整注册表