UGameplayEffect
自动关联目录:UGameplayEffect
GE 是"对属性的一次修改"的数据描述,不是代码。理解这一点,GAS 就顺了一半——技能写的是流程,GE 写的是数据。
一句话定位:GAS 里所有属性变更都应该走 GE。直接 SetHealth 会绕过 Modifier、Tag、归因与复制,是 GAS 项目里最典型的"看起来能跑但全是坑"的写法。
1. 三种时长策略(Duration Policy)
| 策略 | 行为 | 典型用途 |
|---|---|---|
| Instant | 立即修改基础值,不留痕 | 伤害、消耗、瞬间治疗 |
| Has Duration | 期间持续生效,到期移除 | Buff/Debuff、持续回血 |
| Infinite | 直到被显式移除 | 被动、装备加成、状态标签 |
关键区分:Instant 改的是 BaseValue,后两者改的是 CurrentValue(Modifier 叠加在 Base 之上,见 UAttributeSet)。
这决定了伤害是"真的扣血",而 Buff 是"临时加上去"。用 Duration GE 做伤害,到期会把血"还回去"——这是最高频的 GE 配置错误。
2. 四种数值运算
| 运算 | 公式 | 用途 |
|---|---|---|
Additive | Result += Magnitude | 加攻击力、扣血 |
Multiplicative | Result *= Magnitude | 百分比加成 |
Division | Result /= Magnitude | 减伤 |
Override | Result = Magnitude | 强制设定(慎用,会覆盖一切) |
聚合顺序固定:先算所有 Additive,再算乘除。设计数值时必须知道——两个 +50% 的乘算叠加是 2.25 倍而不是 2 倍,而它们和 +50 的加算混在一起时,顺序会影响结果。
3. Magnitude 的三种来源
| 类型 | 说明 |
|---|---|
Scalable Float | 直接填值,或查曲线表(Curve Table)做按等级成长 |
Attribute Based | 基于某个属性计算(按攻击力百分比等) |
Custom Calculation Class | 自定义 UGameplayModMagnitudeCalculation,写公式 |
复杂公式(护甲减伤、暴击)应该用 Custom Calculation Class,不要硬塞进 Attribute Based——后者只能做线性组合。
4. 堆叠(Stacking)
| 设置 | 说明 |
|---|---|
Stacking Type | None / Aggregate by Source / Aggregate by Target |
Stack Limit Count | 最多几层 |
Stack Duration Refresh Policy | 刷新时是否重置持续时间 |
Stack Period Reset Policy | 是否重置周期(Periodic GE) |
Stack Expiration Policy | 到期是全部清除还是减一层 |
Stack Overflow Effects | 满层后再施加时触发的额外 GE |
典型配置:中毒叠 5 层 → Aggregate by Target + Limit 5 + 刷新时长。
Aggregate by Source vs by Target:按来源聚合意味着"每个人给我上的中毒各算一份";按目标聚合意味着"我身上总共只能有 5 层中毒"。选错会让多人副本的 Debuff 层数失控。
5. 标签与阻断
| 字段 | 作用 |
|---|---|
Granted Tags | 生效期间授予目标(如 State.Stun) |
Asset Tags | 描述这个 GE 自身(不授予) |
Ongoing Tag Requirements | 需要目标有/没有某些标签才持续生效 |
Application Tag Requirements | 应用条件 |
Removal Tag Requirements | 满足则移除 |
Granted Application Immunity | 免疫带某些标签的 GE |
状态类效果的通用做法:眩晕 = 一个 Infinite/Duration GE 授予 State.Stun,配合技能的 Activation Blocked Tags(见 UGameplayAbility)。这样加一个状态不需要改任何技能代码。
Asset Tags 与 Granted Tags 的区别常被搞混:前者是"这个 GE 是什么"(用于查询与免疫匹配),后者是"它给目标加了什么"。
6. 周期与执行
| 字段 | 说明 |
|---|---|
Period | 每隔多久执行一次(持续回血/持续伤害) |
Execute Periodic Effect on Application | 应用时立刻先触发一次 |
Periodic Inhibition Policy | 被抑制时周期如何计算 |
Modifiers | 属性修改 |
Executions | 自定义 UGameplayEffectExecutionCalculation,可做复杂结算 |
Execution Calculation 是数值计算的主战场:在这里可以读多个属性、做夹取(Clamp)、实现护甲/暴击公式,并且能拿到 Source 与 Target 的标签。
// Execution Calculation 里能做的事(示意)
void UMyDamageExec::Execute_Implementation(
const FGameplayEffectCustomExecutionParameters& Params,
FGameplayEffectCustomExecutionOutput& Out) const
{
float Armor = 0.f;
Params.AttemptCalculateCapturedAttributeMagnitude(ArmorDef, EvalParams, Armor);
float Damage = FMath::Max(BaseDamage - Armor, 0.f);
Out.AddOutputModifier(DamageDef, EGameplayModOp::Additive, -Damage);
}7. 应用与移除
// 给自己
FGameplayEffectContextHandle Ctx = ASC->MakeEffectContext();
FGameplayEffectSpecHandle Spec = ASC->MakeOutgoingSpec(GEClass, Level, Ctx);
ASC->ApplyGameplayEffectSpecToSelf(*Spec.Data.Get());
// 给目标
ASC->ApplyGameplayEffectToTarget(GEClass, TargetASC, Level, Ctx);
// 按标签移除(服务端权威)
ASC->RemoveActiveGameplayEffectWithTags(FGameplayTagContainer(StunTag));| 要点 | 说明 |
|---|---|
MakeEffectContext | 携带 Instigator / 命中结果等上下文(用于归因) |
SetByCaller | 运行时传动态数值(伤害值)给 GE |
| 移除 | 服务端权威,客户端直接移除无效 |
// SetByCaller:把运行时算出的伤害值传给 GE
Spec.Data->SetSetByCallerMagnitude(FGameplayTag::RequestGameplayTag("Data.Damage"), FinalDamage);8. 代价与权衡
| 设计 | 收益 | 代价 | 什么时候不该用 |
|---|---|---|---|
| 所有修改走 GE | 统一的 Modifier/Tag/归因/复制 | 简单的一次性赋值也要建 GE,略繁琐 | 纯本地表现数值可以不走 |
| Instant 改 Base | 伤害是真的扣 | 无法自动回退 | 想要"临时的伤害"要用 Duration |
| Infinite GE 做被动 | 装备/天赋加成统一 | 需要显式管理移除 | 简单项目可能过度设计 |
| Execution Calculation | 复杂公式集中、可复用 | 比 Modifier 难调试 | 简单加减用 Modifier 就够 |
| Stacking | 层数规则统一 | 配置维度多,容易配错 | 不需要叠层时别开 |
| Override | 强制设定 | 覆盖一切,破坏其它 Modifier | 几乎总是应该避免 |
9. 踩坑与排查
| 坑 | 现象 | 怎么验证 |
|---|---|---|
| 用 Duration GE 做伤害 | 到期血"还回去" | 伤害必须用 Instant |
| 多个乘算叠加以为相加 | 数值与设计不符 | 记住聚合顺序:先加后乘 |
忘了设 Stacking | 同类 Buff 无限叠加 | 配 Stack Limit Count |
Aggregate by Source/Target 选错 | 多人副本层数失控 | 明确"每个来源各算"还是"目标身上总共" |
客户端直接 RemoveActiveGameplayEffect | 无效 | 必须服务端 |
| 用 Instant GE 做"持续掉血" | 只掉一次 | 应 Duration + Period |
Granted Tags 写成 Asset Tags | 状态不生效 | 检查字段 |
| Cooldown GE 的 Tag 与 Ability 不匹配 | 冷却查询失效 | Cooldown GE 需带与 Ability 对应的 Cooldown Tag |
| SetByCaller 的 Tag 拼错 | 数值为 0 | 开 Log LogAbilitySystem Verbose |
| Execution 里没做 Clamp | 负数或超上限 | 在 Execution 里夹取 |
| GE 应用了但没生效 | 被 Tag Requirements 挡住 | showdebug abilitysystem 看 GE 列表与 Tag |
| 客户端看不到 GE | ReplicationMode 是 Minimal | 见 UAbilitySystemComponent |
10. 排查顺序
1. showdebug abilitysystem → GE 有没有被应用、Tag 对不对
2. 数值不对?→ 检查 Duration Policy 与聚合顺序
3. 层数不对?→ Stacking 配置与聚合维度
4. 状态不生效?→ Granted Tags 而非 Asset Tags;技能侧 Activation Blocked Tags
5. 客户端不同步?→ ReplicationMode
6. 复杂公式?→ 移到 Execution Calculation