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. 四种数值运算

运算公式用途
AdditiveResult += Magnitude加攻击力、扣血
MultiplicativeResult *= Magnitude百分比加成
DivisionResult /= Magnitude减伤
OverrideResult = 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 TypeNone / 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
客户端看不到 GEReplicationMode 是 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

参考