Skip to main content

ARPG 项目里 GameplayTag 的层次结构与使用规范

February 24, 2025About 6 minUnreal EngineGAS

ARPG 项目里 GameplayTag 的层次结构与使用规范

GameplayTag 是 GAS 的"通用语言"——状态、技能、输入、资产引用全部走标签。这篇笔记整理一个 ARPG 项目里上千个标签的组织方式：分类、文件结构、命名约定、性能要点。

1. 标签系统的几个性质

  • 层次结构：用 . 分隔的层次路径，父标签可匹配所有子标签（HasTag 和 HasTagExact 行为不同）
  • 配置驱动：标签全部定义在 .ini 文件，引擎启动时加载
  • 运行时安全：标签以哈希存储，比较是 O(1) 整数比较
  • DevComment：每个标签可附带开发注释，便于检索与文档化

标签按用途分文件

文件内容量级
Config/DefaultGameplayTags.ini核心技能/状态/动作标签~1600 行
Config/Tags/SpellRingFlightTags.ini战斗施法/近战环/飞行物标签~240 行
Config/Tags/PlayerInputTags.ini玩家输入绑定标签~300 行
Config/Tags/GameplayCueTags.iniVFX/SFX 特效触发标签~600 行
Config/Tags/CharacterTags.ini角色阵营与身份标签~110 行
Config/Tags/SkillTreeTags.ini技能树节点标签~120 行
Config/Tags/InventoryItemTags.ini道具分类与定义标签~260 行
Config/Tags/QuestGameplayTags.ini任务状态标签~220 行
Config/Tags/DialogueGameplayTags.ini对话系统标签~30 行
Config/Tags/CombatExtensionGameplayTags.iniBoss 战斗扩展标签大文件

2. INI 文件结构

[/Script/GameplayTags.GameplayTagsList]
+GameplayTagList=(Tag="AbilityTagCategory.Action.Dodge",DevComment="玩家闪避动作")
+GameplayTagList=(Tag="AbilityTagCategory.Action.Dodge.EX",DevComment="强化闪避")

DefaultGameplayTags.ini 开头还会有标签重定向（Redirects），用于版本间标签迁移：

[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagRedirects=(OldTagName="Aiming",NewTagName="AimGun")
+GameplayTagRedirects=(OldTagName="WeaponSlot.Melee",NewTagName="WeaponSlot.MeleeMain")

3. AbilityTagCategory — 技能分类标签

用途：标识一个技能的类型，用于 TagRelationshipMapping 的阻止/取消逻辑，以及能力 AbilityTags / CancelAbilitiesWithTag 配置。

3.1 通用动作

标签说明
AbilityTagCategory.Action.Dodge普通闪避
AbilityTagCategory.Action.Dodge.EXEX 闪避（强化版）
AbilityTagCategory.Action.Dodge.Perfect完美闪避（格挡时机）
AbilityTagCategory.Action.Jump跳跃
AbilityTagCategory.Action.JumpStart起跳阶段
AbilityTagCategory.Action.Equipping装备武器
AbilityTagCategory.Action.GroundedAndStandUp倒地起身
AbilityTagCategory.Action.HitRecover受击后恢复
AbilityTagCategory.Action.Performance过场/表演动作

3.2 受击反应

标签说明
AbilityTagCategory.Action.HitReaction.Micro微小受击（碰撞）
AbilityTagCategory.Action.HitReaction.Light轻度受击
AbilityTagCategory.Action.HitReaction.Medium中度受击
AbilityTagCategory.Action.HitReaction.Heavy重度受击（击退）
AbilityTagCategory.Action.GunHitBack枪击弹开
AbilityTagCategory.Action.GunHitWeakpoint枪击弱点命中

3.3 武器技能（示例：刀）

AbilityTagCategory.Action.Katana
  ├─ .Default                    刀默认连招
  ├─ .Light.01 ~ .04             轻攻击 1-4
  ├─ .Heavy.01 ~ .03             重攻击 1-3
  ├─ .JumpAttack                 跳跃攻击
  ├─ .SprintAttack               冲刺攻击
  ├─ .HitBack                    被弹反
  ├─ .HoldStand                  蓄力站立
  ├─ .Sheathe                    收刀
  ├─ .WeaponSwitchAttack         切换武器攻击
  ├─ .FinishingAttack            处决攻击
  └─ .Ougi                       奥义（大招）

3.4 枪械技能

标签说明
AbilityTagCategory.Action.AimGun通用瞄准
AbilityTagCategory.Action.AimGun.Revolver左轮瞄准
AbilityTagCategory.Action.AimGun.AssaultRifle步枪瞄准
AbilityTagCategory.Action.AimGun.Shotgun霰弹瞄准
AbilityTagCategory.Action.Gun.StepBack枪械后步
AbilityTagCategory.Action.GunOugi枪械奥义
AbilityTagCategory.Action.Reload.Revolver左轮装弹

3.5 敌人技能（示例分类）

AbilityTagCategory.Action.Enemy.<EnemyType>
  ├─ .Atk1 / .Atk2 / .Atk3 / .Atk4
  ├─ .DashAttack1 / .DashAttack2 / .DashAttack3
  ├─ .Shoot / .Grenade
  └─ .SwitchWeapon.*

4. OwnedTagsCategory — 角色状态标签

用途：直接添加到 ASC 上，表示当前状态。被 TagRelationshipMapping、能力激活条件、动画状态机广泛使用。

4.1 SpecState（特殊状态）

标签说明设置者
OwnedTagsCategory.SpecState.DISM已肢解肢解系统
OwnedTagsCategory.SpecState.DISMFalling肢解后跌落肢解系统
OwnedTagsCategory.SpecState.Break破防（Break 归零）AS_Break
OwnedTagsCategory.SpecState.KnockOut击倒AS_KnockOut
OwnedTagsCategory.SpecState.Dead死亡AS_Health
OwnedTagsCategory.SpecState.Stagger硬直AS_Stagger

Dead 由 UAbilitySystemGlobalsProject::Get().DeadTag 缓存，在 UEnemyAnimInstance 中监听并触发死亡动画。

4.2 PhysicsControl

标签说明
OwnedTagsCategory.PhysicsControl.Ragdoll布娃娃物理激活
OwnedTagsCategory.PhysicsControl.BlendToRagdoll正在过渡到布娃娃
OwnedTagsCategory.PhysicsControl.Recovery布娃娃恢复中

4.3 Identity（身份）

标签说明
OwnedTagsCategory.Identity.Player玩家角色
OwnedTagsCategory.Identity.Enemy.*敌方（含子标签）
OwnedTagsCategory.Identity.NPC非战斗 NPC

4.4 战斗状态

标签说明
OwnedTagsCategory.State.InCombat处于战斗
OwnedTagsCategory.State.Stunned眩晕中
OwnedTagsCategory.State.Invincible无敌帧
OwnedTagsCategory.State.Blocking格挡中
OwnedTagsCategory.BuffState.DefenseUp防御提升 Buff

5. Spell — 施法资产索引标签

技能（UGameplayAbilityProject）通过此标签在运行时查找对应的 USpellAsset。标签与数据资产一一对应。

Spell.<WeaponType>.<Variant>
  ├─ .01.Light ~ .08.Light    轻攻击 1-8
  ├─ .09.Heavy                重攻击
  ├─ .09.Heavy.EX             EX 版
  ├─ .10.Heavy.Fullcharged    蓄满版
  └─ .10.Heavy.Fullcharged.EX 蓄满 EX 版

6. SpellRing — 近战环标签

UAbilityTask_SpellRing 通过此标签在对象池中查找并分配 ASpellRing 实例。

SpellRing.<WeaponType>.<Variant>.<Move>.<Index>

示例：
  SpellRing.Katana.Default.01.Light.1
  SpellRing.Katana.Default.10.Heavy.1
  SpellRing.Katana.Default.10.Heavy.1.EX
  SpellRing.Katana.Default.10.Heavy.1.Fullcharged
  SpellRing.Katana.Ougi
  SpellRing.Unarmed.JumpAttack

7. SpellFlight — 飞行物标签

SpellFlight.<Faction>.<Weapon>.<Variant>

示例：
  SpellFlight.Player.Revolver
  SpellFlight.Player.Revolver.Ougi
  SpellFlight.Player.Revolver.ThroughBullet
  SpellFlight.Player.Rifle.PiercingBullet
  SpellFlight.Enemy.Grenade
  SpellFlight.Boss.ProjectileExplode

8. CollisionTrace — 碰撞检测标签

标识 Ring/Flight 使用的碰撞检测通道/Socket 类型，传递给碰撞检测系统：

标签说明
CollisionTrace.HandL / .HandR左/右手碰撞检测
CollisionTrace.WeaponL / .WeaponR左/右手武器碰撞检测
CollisionTrace.WeaponR.ActorSpace右手武器（Actor 坐标空间）
CollisionTrace.WeaponR.Extent右手武器（扩展范围）
CollisionTrace.FootL / .FootR左/右脚碰撞检测
CollisionTrace.Flight飞行物碰撞
CollisionTrace.Flight.Shuriken手里剑飞行物碰撞

9. GameplayCue — 特效音效标签

触发 UGameplayCueManageComponent 中的 VFX/SFX：

标签前缀内容
GameplayCue.AssaultRifle.*突击步枪射击/换弹音效
GameplayCue.Burning.*燃烧效果
GameplayCue.CameraShake.*镜头震动
GameplayCue.Dismember.*肢解特效（各部位）
GameplayCue.Dodge.*闪避特效
GameplayCue.Katana.*刀各招式特效与音效
GameplayCue.Gun.*枪械通用音效
GameplayCue.Revolver.*左轮专属音效特效
GameplayCue.HitReaction.*受击反应（轻/中/重）
GameplayCue.Blood.*血迹特效（类型由 SpellDamageFXTypeTag 决定）
GameplayCue.Boss.*Boss 技能特效

10. PlayerInput — 输入绑定标签

Enhanced Input 的 InputAction 通过此标签与 ProcessAbilityInput() 关联，也用于 AbilitySet 的 InputTag 字段。

武器槽

标签说明
InputTag.ActivateWeaponSlot.0 ~ .3激活武器槽 0-3

通用

标签说明
InputTag.Dodge普通闪避
InputTag.Dodge.EXEX 闪避
InputTag.Dodge.Perfect完美闪避触发
InputTag.Jump跳跃
InputTag.Reload通用装弹

武器（示例：刀）

InputTag.Weapon.Katana
  ├─ .LightAttack.01 ~ .12
  ├─ .HeavyAttack.01 ~ .12
  ├─ .EXAttack.01 ~ .04
  ├─ .JumpAttack
  ├─ .SprintAttack
  ├─ .Ougi
  ├─ .HoldStand
  └─ .WeaponSwitchAttack

枪械

标签说明
InputTag.Weapon.Gun.Aim枪械瞄准
InputTag.Weapon.Gun.Shoot射击
InputTag.Weapon.Gun.StepBack枪械后步
InputTag.Weapon.Gun.Ougi枪械奥义
InputTag.Weapon.Revolver.Reload左轮装弹

11. Attribute — 属性标签

用于 GE 的 SetByCaller，也用于 UAbilitySystemGlobalsProject 缓存常用属性引用：

标签前缀对应属性集主要属性
Attribute.HealthSet.*AS_HealthHealth, MaxHealth, MetaDelta
Attribute.StaminaSet.*AS_StaminaStamina, MaxStamina, MetaDelta
Attribute.BreakSet.*AS_BreakBreak, MaxBreak, RegenValue, TrimPercent, ResetSeconds
Attribute.PoiseSet.*AS_PoisePoise, MaxPoise, PoiseLevel
Attribute.StaggerSet.*AS_StaggerStagger, MaxStagger, RegenValue, ThresholdValue
Attribute.KnockOutSet.*AS_KnockOutKnockOut, MaxKnockOut, RegenValue
Attribute.DismemberSet.*AS_DismemberDismember, MaxDismember, RegenValue
Attribute.HatredSet.*AS_HatredHatred, MaxHatred

12. GameCharacterTag — 角色身份

每个角色实体的唯一身份标识，用于对话条件查询、任务触发、特殊交互。

阵营

Faction.<Name>
  ├─ Faction.Church
  ├─ Faction.Heros
  ├─ Faction.Survivors
  └─ Faction.<Custom>

角色

GameCharacterTag.<Name>
  ├─ GameCharacterTag.FollowNPC          跟随型 NPC
  ├─ GameCharacterTag.GuideQuestNPC      引导任务 NPC
  ├─ GameCharacterTag.InteractNPC        可交互 NPC
  └─ GameCharacterTag.<NamedNPC>         特定命名角色

13. 命名规范

层级原则

[系统].[子系统].[实体].[动作/状态].[变体]

示例：
AbilityTagCategory   . Action    . Katana    . Light . 01
SpellRing            . Katana    . Default   . Light . 01 . 1
SpellFlight          . Player    . Revolver  . Ougi
OwnedTagsCategory    . SpecState . Dead
GameplayCue          . Katana    . Light01   . Strike

约定

约定说明
全部 PascalCaseLightAttack，不用 lightattack
数字序号两位补零01、02，不用 1、2
变体用 .EX .Fullcharged .New明确标记版本
父标签表达类别AbilityTagCategory.Action.Katana 是所有刀技能的父标签
叶节点最具体每个技能唯一对应一个叶节点

新增标签步骤

  1. 确定标签所属类别和文件
  2. 在对应 .ini 末尾添加：
    +GameplayTagList=(Tag="SpellRing.NewWeapon.Attack01",DevComment="新武器攻击01近战环")
  3. 重启编辑器（或 Project Settings → Gameplay Tags → Refresh 热重载）
  4. 在相应数据资产中引用

14. 常用标签速查

技能激活条件

用途标签
检查死亡OwnedTagsCategory.SpecState.Dead
检查眩晕OwnedTagsCategory.State.Stunned
检查战斗中OwnedTagsCategory.State.InCombat
检查无敌OwnedTagsCategory.State.Invincible
检查格挡OwnedTagsCategory.State.Blocking
检查破防OwnedTagsCategory.SpecState.Break

AbilitySystemGlobals 缓存

以下标签由 UAbilitySystemGlobalsProject 启动时缓存为 FGameplayTag 成员，直接访问比 FGameplayTag::RequestGameplayTag() 更快：

成员对应标签
DeadTagOwnedTagsCategory.SpecState.Dead
StaggerTagOwnedTagsCategory.SpecState.Stagger
KnockOutTagOwnedTagsCategory.SpecState.KnockOut
DismemberTagOwnedTagsCategory.SpecState.DISM
DismemberFallingTagOwnedTagsCategory.SpecState.DISMFalling

性能建议：热路径（Tick / Hit 检测）始终使用缓存标签，避免每帧调用 FGameplayTag::RequestGameplayTag(FName(TEXT("..."))) 造成哈希表查找。