Gameplay Events - 游戏事件#

核心机制#

1. 事件声明 (Event Declaration): 【重点】事件本身通常由一个 Gameplay Tag 来定义和标识。你需要在项目设置中（Project Settings -> Gameplay Tags）创建这些事件标签（例如 Event.Player.TookDamage, Event.Ability.ProjectileHit, Event.Montage.AttackHit）。

2. 事件发送 (Sending Events): 事件通常发送给一个特定的 ASC。

   • 从 C++: 调用 UAbilitySystemComponent::HandleGameplayEvent。

     1
     FGameplayEventData Payload;
     2
     // 填充 Payload ...
     3
     Payload.EventTag = FGameplayTag::RequestGameplayTag(FName("Event.Player.TookDamage"));
     4
     Payload.EventMagnitude = 25.0f;
     5
     Payload.Instigator = DamageCauserActor;
     6
     Payload.Target = DamagedActor;
     7
     
     8
     UAbilitySystemComponent* TargetASC = UAbilitySystemBlueprintLibrary::GetAbilitySystemComponent(DamagedActor);
     9
     if (TargetASC)
     10
     {
     11
         TargetASC->HandleGameplayEvent(Payload.EventTag, &Payload);
     12
     }
     

   • 从蓝图: 调用 Send Gameplay Event to Actor 节点。
   • 从 AnimNotify: 使用 AnimNotify_SendGameplayEvent （见 MontageEvent）。

3. 事件监听/接收 (Listening/Receiving Events):

   • 在 GameplayAbility 中: 【重点】
     • 使用 [[w/unreal/abilitytask_waitgameplayevent|AbilityTask_WaitGameplayEvent]] 任务来等待特定的事件标签。
     • 使用 [[w/unreal/abilitytask_playmontageandwait|AbilityTask_PlayMontageAndWait]] 任务的 EventReceived 委托来接收来自 Montage 的事件。
     • 将 GameplayAbility 配置为通过 Ability Trigger 由特定事件标签自动激活。
   • 在 ASC 中: 可以绑定委托到 UAbilitySystemComponent::GenericGameplayEventCallbacks 来监听所有发送到该 ASC 的事件（【注意】不常用，通常在能力中处理更方便）。
   • 在 Actor 中: Actor 可以获取其 ASC 并绑定到上述委托，或者更常见的是，Actor 拥有一个监听特定事件的能力，并在该能力内部处理逻辑。

4. 事件数据 (Event Data - Payload): 【重点】事件可以附带一个 FGameplayEventData 结构体作为Payload，用于传递上下文信息，如发起者、目标、数值、标签、EffectContext，甚至复杂的目标数据 (FGameplayAbilityTargetData)。

应用场景示例#

• 伤害通知: 当 Actor 受到伤害时，其 ASC 发送 Event.Character.TookDamage 事件，附带伤害值和来源信息。一个用于触发受击动画或音效的 GameplayAbility 可以通过 Ability Trigger 监听此事件自动激活。
• 技能触发: 一个投射物击中目标时，发送 Event.Ability.ProjectileHit 事件给被击中的 Actor。目标 Actor 上的 GameplayAbility（如应用减速效果）可以监听此事件。
• 动画同步: MontageEvent 中解释的，通过 Montage 中的 AnimNotify 发送事件来同步动画和逻辑。
• UI 反馈: UI 可以监听特定的 Gameplay Event (例如 Event.Quest.Completed) 来更新显示。

与 C++ 委托/事件的区别#

• 解耦: Gameplay Events 基于标签，发送者和接收者不需要直接了解对方，耦合度更低。
• GAS 集成: Gameplay Events 与 GameplayAbility、AbilityTask、ASC 深度集成，使用更方便。
• 数据传递: FGameplayEventData 提供了标准化的数据负载结构。
• 性能: 对于高频事件，直接 C++ 委托可能略快，但 Gameplay Events 的开销通常可以接受，且灵活性带来的好处更大。

重要概念链接#

• Gameplay Tags：定义和标识事件的核心。
• ASC：事件的主要发送目标和处理中心。
• GameplayAbility：事件的主要监听者和逻辑处理器。
• AbilityTask_WaitGameplayEvent / [[w/unreal/abilitytask_playmontageandwait|AbilityTask_PlayMontageAndWait]]：监听事件的标准任务。
• GameplayEventData：事件传递的数据结构。
• MontageEvent：通过动画触发 Gameplay Event 的方式。
• FGameplayAbilityTargetData：可以包含在 Payload 中传递复杂目标信息。

注意事项#

• 【重点】规划标签体系: 清晰、一致的 Gameplay Event Tag 命名规则非常重要。
• 【注意】事件发送是单向广播给目标 ASC，如果需要多个系统响应，它们都需要监听同一个事件标签。
• 【技巧】FGameplayEventData 非常灵活，善用其字段（特别是 Instigator, Target, EventMagnitude, ContextHandle, TargetData）可以传递丰富的上下文。
• 【注意】虽然可以监听所有事件，但通常更推荐在能力中使用 WaitGameplayEvent 任务精确监听你关心的事件，避免不必要的处理开销。