FGameplayTag
自动关联目录:FGameplayTag
可以应用于游戏对象的任意层级标识符。这些标签可用于识别、分类、筛选游戏实体,可以通过 Gameplay 效果和技能赋予或取消,并且可以影响其行为——比如 Gameplay.DamageImmunity 标签能防止对所有者的 Pawn 造成伤害。
一句话概括它在 GAS 里的地位:Tag 是 GAS 各系统之间的通用语言。UGameplayAbility、UGameplayEffect、UAbilitySystemComponent 之间几乎不直接互相引用,全靠 Tag 表达条件与关系。
两个核心类型
| 类型 | 含义 | 用途 |
|---|---|---|
FGameplayTag | 单个标签 | 标记一个状态/类别 |
FGameplayTagContainer | 标签集合 | 表达"拥有哪些标签" |
FGameplayTag Tag = FGameplayTag::RequestGameplayTag(TEXT("State.Stunned"));
if (ASC->HasMatchingGameplayTag(Tag)) { /* 处于眩晕 */ }FGameplayTag 内部只是一个句柄(索引),不是字符串。所以:
- 比较、查询是整数级别的开销,可以放进每帧逻辑
- 但构造(
RequestGameplayTag)涉及查表,不该每帧做,应该在启动时缓存成成员
层级与匹配
Tag 用 . 分层的语义是**"拥有父级即拥有子级"**:
拥有 State.Stunned.Heavy → 同时匹配 State.Stunned、State
拥有 State.Stunned → 不匹配 State.Stunned.Heavy| 匹配方式 | 语义 |
|---|---|
HasMatchingGameplayTag | 精确匹配这一个 |
HasAnyMatchingGameplayTags | 容器里有任意一个即成立 |
HasAllMatchingGameplayTags | 容器里全部都有才成立 |
FGameplayTagQuery | 组合表达式(Any/All/None),可做复杂条件 |
利用层级设计 Tag 树,能少写很多组合判断:Damage.Fire、Damage.Ice 都可以被 Damage 一次性拦截。
在 GAS 里的用途
| 位置 | 用法 |
|---|---|
UGameplayAbility | AbilityTags(自身标签)、ActivationRequiredTags、ActivationBlockedTags、CancelAbilitiesWithTag |
UGameplayEffect | GrantedTags(持续期间赋予)、ApplicationTagRequirements、OngoingTagRequirements |
UAbilitySystemComponent | AddLooseGameplayTag / RemoveLooseGameplayTag、RegisterGameplayTagEvent 监听变化 |
| Cooldown | 用 Cooldown.* Tag 做冷却标记(GE 授予冷却 Tag) |
| GameplayCue | GameplayCue.* Tag 驱动表现层 |
| Event | SendGameplayEventToActor 用 Tag 作为事件名 |
"眩晕时不能放技能"这类需求,正确做法是用 Tag 表达,而不是在 Ability 里 if 判断外部状态——这样规则是数据,不是代码。
注册与配置
| 方式 | 位置 |
|---|---|
| 项目设置 | Project Settings → Project → GameplayTags |
| 配置文件 | DefaultGameplayTags.ini |
| 数据表 | GameplayTag Table(DataTable 资产) |
| C++ 硬注册 | UGameplayTagManager(配合 FGameplayTag::RequestGameplayTag) |
未在 Tag Manager 中注册的标签,RequestGameplayTag 会返回空 Tag 并报警。用数据表管理的好处是可以随资源加载、便于多人协作与分支合并(ini 合并冲突比数据表痛苦)。
网络复制
| 类型 | 说明 |
|---|---|
ReplicatedLooseGameplayTags | ASC 上会自动复制的 Tag 集合 |
| GE 授予的 Tag | 随 GE 的复制一并同步 |
| 纯本地 Loose Tag | 客户端自己加的标签不会同步,别用它做判定依据 |
数量上要注意:复制的 Tag 集合不宜过大,每个标签的增删都会产生网络流量,通常控制在十几个以内。
设计建议
| 建议 | 说明 |
|---|---|
| 按"域 + 状态"命名 | State.Stunned、Cooldown.Fireball、Damage.Fire、Character.Class.Mage |
| 用层级表达包含关系 | 让父级 Tag 承担"这一类"的判定 |
| Tag 只表达"是什么",不表达"多少" | 数值请交给 UAttributeSet |
| 别把 Tag 当枚举滥用 | 需要穷举且固定的类型用枚举更省事 |
| 集中管理 | Tag 散落各处后,改一个名字的影响面无法评估 |
代价与权衡
| 设计 | 收益 | 代价 | 什么时候不该用 |
|---|---|---|---|
| 用 Tag 表达状态 | 规则变成数据,加一个状态不用改技能代码 | 需要先规划命名空间 | 简单的布尔开关不必上 Tag |
| 层级继承匹配 | 父级 Tag 一次拦一类 | 层级过深容易误命中 | 深度建议控制在 3 层内 |
| Loose Tag | 加/删最方便,无需 GE | 不复制(除非用 Replicated 版本) | 不能做权威判定 |
| GE 授予的 Tag | 随 GE 复制、随 GE 移除自动清理 | 需要建 GE | 长期状态用它更稳 |
| Tag 传递数值 | — | 错误用法 | 数值应走属性或 GE 堆叠 |
| 复制 Tag 集合 | 客户端能判定 | 增删都产生流量 | 控制在十几个以内 |
常见坑
| 坑 | 说明 |
|---|---|
每帧 RequestGameplayTag | 字符串查表,应缓存成成员或静态变量 |
| 拼写错导致 Tag 未注册 | 运行时静默失败,条件永不成立 |
| 用 Loose Tag 做权威判定 | 客户端自己加的标签不同步,服务端看不到 |
| Tag 层级设计过深 | 匹配语义变复杂,容易误命中 |
| 用 Tag 传递数值 | 比如 Buff.Stack5,应改用属性或 GE 的堆叠机制 |
| 删除/重命名 Tag | 数据表、蓝图、ini 里的引用不会自动更新,需要全局搜索 |
| 用 ini 管理且多人同时改 | 合并冲突频繁,改用数据表 |
| 把 Tag 当枚举穷举 | 需要遍历与顺序时用枚举更省事 |
排查顺序
1. 条件不生效?→ showdebug abilitysystem 看实际拥有的 Tag 是什么
2. Tag 是空的?→ 是否未注册(RequestGameplayTag 返回空会报警)
3. 服务端看不到?→ 用的是不是纯本地 Loose Tag
4. 误命中?→ 层级是否过深,父级是否被意外拥有
5. 改了名字失效?→ 全局搜索残留引用调试命令
| 命令 | 作用 |
|---|---|
showdebug abilitysystem | 查看当前拥有的 Tag 列表 |
GameplayTags.ListTags / GameplayTags.DumpTagTree | 列出已注册的 Tag 树 |
Log LogGameplayTags Verbose | Tag 增删的详细日志 |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/b544f9e1.html
更新于:2026年11月16日