AGameplayCueNotify_Actor

自动关联目录:AGameplayCueNotify_Actor

GameplayCue 是 GAS 的表现层:特效、音效、相机震动、屏幕闪白。它跟逻辑解耦——Cue 可以丢、可以延迟、可以不跑,游戏结果不受影响。

这条性质是刻意设计的:把表现从权威逻辑里剥离,预测与回滚时就不必操心特效。

两种实现

类型特点适用
AGameplayCueNotify_Actor放到场景里的 Actor,可复用需要持续存在的效果(燃烧、护盾)
AGameplayCueNotify_Static无实例,纯函数一次性特效(命中火花、音效)

优先用 Static:没有 Actor 生成开销,也不需要在世界里管理生命周期。只有需要"持续存在并响应事件"时才用 Actor 版。

回调

回调触发
OnExecute一次性触发(Instant / 事件型)
OnActive效果开始(Duration/Infinite)
WhileActive持续期间每帧
OnRemove效果移除
OnExecuteOnActive / OnRemove
是否配对否(触发即忘)是(有开始就有结束)
典型用途命中特效、播放音效持续光环、燃烧状态

触发方式

// 立即触发(不走复制的持续状态)
ASC->ExecuteGameplayCue(GameplayCueTag);

// 添加/移除(有持续状态,可复制)
ASC->AddGameplayCue(GameplayCueTag);
ASC->RemoveGameplayCue(GameplayCueTag);

也可以在 UGameplayEffect 上配置 Gameplay Cues,让 GE 生效/结束时自动触发——这是最省事的做法,绝大多数 Buff 特效都该这么配。

路由与网络

要点说明
按 GameplayTag 路由标签 → Cue 类的映射在 GameplayCueManager 里
复制AddGameplayCue 会复制;ExecuteGameplayCue 走多播事件
模拟端会执行,可在 WhileActive 里做表现
bAutoAttachToOwner是否跟随 Owner 移动
bAllowMultipleOnActiveEvents是否允许多次 OnActive

路径约定:Cue 类需要被引擎扫描到,通常放在能被 GameplayCueManager 找到的路径下(项目设置里可配扫描目录)。

参数(Cue 上的常用设置)

设置作用
GameplayCue Tag路由用的 Tag,必须在 Tag Manager 注册且以 GameplayCue. 开头
bAutoAttachToOwner是否跟随 Owner 移动
bAllowMultipleOnActiveEvents是否允许多次 OnActive
bAutoDestroyOnRemoveActor 版:移除时是否销毁
Reapply 相关回调重复施加时的行为

扫描路径在项目设置 GameplayCueManager 里配置——Cue 类不在扫描路径下不会报错,只是不触发。

代价与权衡

设计收益代价什么时候不该用
表现与逻辑解耦预测/回滚不必操心特效;Cue 丢了也不影响结果表现可能"晚一点"或"没播"需要严格同步的判定不能用 Cue
Static 版无 Actor 开销不能持续存在、不能响应 WhileActive持续光环等必须用 Actor 版
Actor 版可持续、可复用、能跟随 OwnerActor 生成与销毁开销一次性命中火花不该用
ExecuteGameplayCue触发即忘,最省无状态,无法精确移除需要"开/关"语义时用 Add/Remove
AddGameplayCue有状态、会复制需要配对 Remove一次性表现不必用

常见坑

坑说明
把逻辑写进 Cue(比如在这里扣血)Cue 不保证执行,结果会不一致
用 Actor 版做一次性特效多余的 Actor 生成与销毁
忘记 RemoveGameplayCue特效永久残留
标签没注册 / 路径没被扫描Cue 不触发,且不报错
在 OnActive 里不做幂等保护多次添加会叠加多个特效
依赖 Cue 的到达顺序网络下顺序无保证
在 Cue 里做权威判定服务端可能根本没这个 Cue
大量同时触发特效峰值,应做池化与预算

排查顺序

1. Cue 完全不触发?→ 先看 Tag 是否注册、类是否在扫描路径下
2. 触发了但表现不对?→ 是 OnExecute 还是 OnActive(语义不同)
3. 特效残留?→ 是否有配对的 RemoveGameplayCue
4. 叠加多个?→ OnActive 是否幂等;bAllowMultipleOnActiveEvents
5. 表现但结果不对?→ 逻辑不该写在 Cue 里

调试

命令作用
showdebug abilitysystem看当前活跃的 GameplayCue
GameplayCue.Debug / Log LogAbilitySystem VerboseCue 触发日志
DisplayAll GameplayCueNotify列出已加载的 Cue 类