AGameplayCueNotify_Actor
自动关联目录:AGameplayCueNotify_Actor
GameplayCue 是 GAS 的表现层:特效、音效、相机震动、屏幕闪白。它跟逻辑解耦——Cue 可以丢、可以延迟、可以不跑,游戏结果不受影响。
这条性质是刻意设计的:把表现从权威逻辑里剥离,预测与回滚时就不必操心特效。
两种实现
| 类型 | 特点 | 适用 |
|---|---|---|
AGameplayCueNotify_Actor | 放到场景里的 Actor,可复用 | 需要持续存在的效果(燃烧、护盾) |
AGameplayCueNotify_Static | 无实例,纯函数 | 一次性特效(命中火花、音效) |
优先用 Static:没有 Actor 生成开销,也不需要在世界里管理生命周期。只有需要"持续存在并响应事件"时才用 Actor 版。
回调
| 回调 | 触发 |
|---|---|
OnExecute | 一次性触发(Instant / 事件型) |
OnActive | 效果开始(Duration/Infinite) |
WhileActive | 持续期间每帧 |
OnRemove | 效果移除 |
OnExecute | OnActive / 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 |
bAutoDestroyOnRemove | Actor 版:移除时是否销毁 |
Reapply 相关回调 | 重复施加时的行为 |
扫描路径在项目设置 GameplayCueManager 里配置——Cue 类不在扫描路径下不会报错,只是不触发。
代价与权衡
| 设计 | 收益 | 代价 | 什么时候不该用 |
|---|---|---|---|
| 表现与逻辑解耦 | 预测/回滚不必操心特效;Cue 丢了也不影响结果 | 表现可能"晚一点"或"没播" | 需要严格同步的判定不能用 Cue |
Static 版 | 无 Actor 开销 | 不能持续存在、不能响应 WhileActive | 持续光环等必须用 Actor 版 |
Actor 版 | 可持续、可复用、能跟随 Owner | Actor 生成与销毁开销 | 一次性命中火花不该用 |
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 Verbose | Cue 触发日志 |
DisplayAll GameplayCueNotify | 列出已加载的 Cue 类 |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/fad64f1c.html
更新于:2026年11月16日