用途
Gameplay Tags 是 Unreal Engine 中一种层级化、内部化（interned）的 FName 标签，例如 State.Stunned、Ability.Attack.Melee、Event.Reset。它们集中注册，让所有系统使用同一套词汇，从而替代分散的枚举、布尔值和字符串 ID，形成单一、可扩展、可由设计人员在编辑器中维护的分类体系。该技能用于在 Unreal C++ 中正确使用 Gameplay Tags。
适用场景包括：建模状态、类别或标记（“是否被眩晕”“火焰伤害类型”“技能=冲刺”）；用可查询的标签替代脆弱的枚举/布尔/字符串；对接标签驱动系统（GAS、行为树、动画、UI）；根据角色当前激活的标签集合授予、阻止或查询行为；构建无需重新编译、可由设计人员编辑的数据驱动激活条件。
心智模型
标签是以点分隔的层级，Ability.Attack.Melee 是 Ability.Attack 的子标签。标签经过内部化处理，比较时只需做快速的 FName 相等检查，而不是字符串比较。标签在游戏开始前一次性注册（原生标签在模块加载时注册，配置标签在 ini/DataTable 加载时注册），不能在运行时随意创建。FGameplayTagContainer 保存角色当前拥有的标签集合，并缓存父标签以支持快速的层级查询。FGameplayTagQuery 把逻辑表达式（任意/全部/无 某标签集，可递归组合）编码为不透明字节流，可在 Details 面板中编辑。需要在 Build.cs 的 PublicDependencyModuleNames 中加入 "GameplayTags"。
定义标签
共有三种方式，可以混用：
-
原生 C++ 标签：编译期安全，可跨模块共享，在模块加载时注册。使用 UE_DECLARE_GAMEPLAY_TAG_EXTERN 在头文件中声明，在 .cpp 中用 UE_DEFINE_GAMEPLAY_TAG（无注释）、UE_DEFINE_GAMEPLAY_TAG_COMMENT（带编辑器可见提示）或 UE_DEFINE_GAMEPLAY_TAG_STATIC（文件私有，无需头文件声明）定义。C++ 直接引用的标签应全部使用原生标签，这样调用处无需字符串查找，变量名拼错会直接编译报错。
-
配置/编辑器标签：在 Project Settings → GameplayTags 中添加（写入 Config/DefaultGameplayTags.ini），或写入 Config/Tags/*.ini 以便按团队组织；运行时用 FGameplayTag::RequestGameplayTag(FName("...")) 按名称获取，建议缓存结果以减少映射查找；第二个参数传 false 可抑制标签不存在时的 ensure。
-
DataTable 标签：使用行类型为 FGameplayTagTableRow 的 UDataTable，并在 Project Settings → Gameplay Tag Table List 中登记，适合从 CSV 批量导入标签集。
容器操作
FGameplayTagContainer 支持 AddTag、RemoveTag、AppendTags（求并集）、Reset 等操作。层级感知查询包括 HasTag（精确或祖先匹配）、HasTagExact、HasAny、HasAll、HasAnyExact、HasAllExact。注意层级语义：若容器含有 Ability.Attack.Melee，则 HasTag(Ability.Attack) 返回 true；需要严格相等时应使用 *Exact 变体。HasAll 在空容器上返回 true（空真）。
单个标签匹配使用 MatchesTag（子标签匹配父标签）、MatchesTagExact、MatchesAny。
标签查询
FGameplayTagQuery 组合可由设计人员在 Details 面板中编写、无需重新编译的条件。可用 BuildQuery 配合 AllExprMatch/AnyTagsMatch/NoTagsMatch 构建表达式树，也可使用 MakeQuery_MatchAnyTags、MakeQuery_MatchAllTags、MakeQuery_MatchNoTags 等快捷工厂函数；通过 Q.Matches(ActorTags) 求值。
接口与编辑器暴露
在拥有标签的 Actor 或对象上实现 IGameplayTagAssetInterface，重写 GetOwnedGameplayTags，其他系统即可无需类型转换地取得标签；该接口还提供 HasMatchingGameplayTag、HasAllMatchingGameplayTags、HasAnyMatchingGameplayTags 的默认实现，仅在需要自定义逻辑时重写。FGameplayTag、FGameplayTagContainer、FGameplayTagQuery 均为 BlueprintType，在 Details 面板显示专用编辑器控件；可用 meta=(Categories="Damage") 把标签选择器限制在某个子树。
标签与枚举的取舍
固定、数量小、互斥且在 C++ 中 switch 的集合用 enum class；开放式、层级化、可由设计人员扩展的标签用 Gameplay Tags；一个对象同时拥有一组状态用标签容器；需要无需重编译即可编辑的激活条件用 FGameplayTagQuery。
常见陷阱
RequestGameplayTag 拼写错误或标签未注册会告警并返回无效标签（第二参数控制是否触发 ensure），应优先使用原生标签。HasTag 与 HasTagExact 的层级展开会导致误判，需按语义选择。HasAll 在空容器上返回 true，必要时用 !Container.IsEmpty() 防御。Build.cs 漏加 "GameplayTags" 会导致外部符号未解析。原生标签注册过晚会有问题：宏在模块启动时注册，不可在函数内或标签表锁定后定义。应直接比较 FGameplayTag 值或使用匹配函数，而不是比较 Tag.ToString()。UE_DEFINE_GAMEPLAY_TAG 不可放在头文件中，宏内 static_assert 会在编译期拒绝，定义必须位于 .cpp。
版本说明
UE_DEFINE_GAMEPLAY_TAG_STATIC 与 UE_DEFINE_GAMEPLAY_TAG_COMMENT 在 UE5.0+ 已存在，并在 5.8 中稳定。UGameplayTagsManager 上的 GetSingleTagContainer(FGameplayTag) 在 5.4 中弃用，替代为成员函数 FGameplayTag::GetSingleTagContainer()。新增 FGameplayTagQuery::MakeQuery_ExactMatchAnyTags / MakeQuery_ExactMatchAllTags，支持无需手工构建表达式树的精确匹配查询。UGameplayTagsSettings 上的 ClearInvalidTags 设置在 5.5 中弃用。
关联与参考
gameplay-ability-system 技能与本文互为配套参考：GAS 大量使用标签，包括技能激活需求、阻止/取消标签、FGameplayEffectQuery、Gameplay Cue 标签和 FGameplayTagResponseTable。
引擎源码（UE 5.8，Engine/Source/Runtime/GameplayTags/）涉及 GameplayTagContainer.h、GameplayTagsManager.h、NativeGameplayTags.h、GameplayTagAssetInterface.h、GameplayTagsSettings.h 中的相关类与函数行号。官方文档：Gameplay Tags — https://dev.epicgames.com/documentation/unreal-engine/using-gameplay-tags-in-unreal-engine ；Gameplay Systems — https://dev.epicgames.com/documentation/unreal-engine/gameplay-systems-in-unreal-engine 。本技能内含深入参考：references/native-tags.md（原生标签宏、模块注册时序、多模块共享、FNativeGameplayTag 生命周期）；references/containers-and-queries.md（容器内部结构、查询表达式树、网络序列化、性能建议）；references/tag-driven-patterns.md（标签驱动的状态机、效果门控、技能门控/GAS 集成、动画、config/ini 组织）。