ue-gameplay-abilities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gameplay Ability System (GAS)

You are an expert in Unreal Engine's Gameplay Ability System (GAS).

你是Unreal Engine的Gameplay Ability System (GAS)专家。

Context Check

上下文检查

Before proceeding, read

.agents/ue-project-context.md

to determine:

Whether the GameplayAbilities plugin is enabled
Which actors own the AbilitySystemComponent (PlayerState vs Character)
The replication mode in use (Minimal, Mixed, Full)
Any existing AttributeSets or ability base classes

在开始操作前，请阅读

.agents/ue-project-context.md

以确认：

GameplayAbilities插件是否已启用
哪些Actor拥有AbilitySystemComponent（PlayerState 还是 Character）
当前使用的复制模式（Minimal、Mixed、Full）
已存在的AttributeSet或能力基类

Information Gathering

信息收集

Ask the developer:

What type of abilities are needed? (active, passive, triggered, instant)
What attributes are required? (health, mana, stamina, custom stats)
Is this multiplayer? If so, which actors carry the ASC?
Are cooldowns and costs required, or is this a passive/trigger system?
Do abilities need prediction (local-only feedback before server confirms)?

请向开发者询问以下问题：

需要哪种类型的能力？（主动、被动、触发、即时）
需要哪些属性？（生命值、法力值、耐力、自定义属性）
是否为多人游戏？如果是，哪些Actor承载ASC？
是否需要冷却时间和消耗，或者这是一个被动/触发系统？
能力是否需要预测（服务器确认前的本地反馈）？

GAS Architecture Overview

GAS架构概述

GAS has three pillars that live on

UAbilitySystemComponent

(ASC):

Pillar	Class	Purpose
Abilities	`UGameplayAbility`	Logic for what happens when activated
Effects	`UGameplayEffect`	Data-driven stat mutations (instant, duration, infinite)
Attributes	`UAttributeSet`	Float properties representing character stats

GameplayTags thread through all three as requirements, grants, and blockers.

GAS有三大核心模块，均依赖

UAbilitySystemComponent

（ASC）：

核心模块	类	用途
能力	`UGameplayAbility`	定义能力激活时的执行逻辑
效果	`UGameplayEffect`	基于数据的属性变更（即时、持续、永久）
属性	`UAttributeSet`	代表角色属性的浮点型属性集合

GameplayTags贯穿这三大模块，用于实现需求校验、权限授予和逻辑阻断。

GAS Setup

GAS设置

1. Enable the Plugin

1. 启用插件

Enable

GameplayAbilities

.uproject

Plugins array, then in

[ProjectName].Build.cs

csharp

PublicDependencyModuleNames.AddRange(new string[]
{
    "GameplayAbilities", "GameplayTags", "GameplayTasks"
});

在

.uproject

的Plugins数组中启用

GameplayAbilities

，然后在

[ProjectName].Build.cs

中添加：

csharp

PublicDependencyModuleNames.AddRange(new string[]
{
    "GameplayAbilities", "GameplayTags", "GameplayTasks"
});

2. AbilitySystemComponent Ownership

2. AbilitySystemComponent归属

PlayerState (recommended for multiplayer): ASC persists across respawns because PlayerState is not destroyed on death. Use this for player characters in networked games.

Character/Pawn: Simpler. Use for AI characters or single-player games where persistence across respawns is not required.

See

references/gas-setup-patterns.md

for full initialization sequences for both patterns.

PlayerState（多人游戏推荐）：ASC会在角色重生后保留，因为PlayerState不会在死亡时被销毁。适用于联网游戏中的玩家角色。

Character/Pawn：设置更简单。适用于AI角色或无需跨重生保留状态的单人游戏。

完整的初始化流程请参考

references/gas-setup-patterns.md

中的两种模式实现代码。

3. IAbilitySystemInterface

3. 实现IAbilitySystemInterface

Every actor that owns or exposes an ASC must implement

IAbilitySystemInterface

cpp

#include "AbilitySystemInterface.h"

UCLASS()
class AMyCharacter : public ACharacter, public IAbilitySystemInterface
{
    GENERATED_BODY()
public:
    virtual UAbilitySystemComponent* GetAbilitySystemComponent() const override
        { return AbilitySystemComponent; }
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "GAS")
    TObjectPtr<UAbilitySystemComponent> AbilitySystemComponent;
};

所有拥有或暴露ASC的Actor必须实现

IAbilitySystemInterface

：

cpp

#include "AbilitySystemInterface.h"

UCLASS()
class AMyCharacter : public ACharacter, public IAbilitySystemInterface
{
    GENERATED_BODY()
public:
    virtual UAbilitySystemComponent* GetAbilitySystemComponent() const override
        { return AbilitySystemComponent; }
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "GAS")
    TObjectPtr<UAbilitySystemComponent> AbilitySystemComponent;
};

4. Replication Modes

4. 复制模式设置

Set on the ASC after creation (server-side only):

cpp

// In BeginPlay or PossessedBy on the server:
AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Mixed);

Mode	When to Use
`Minimal`	AI or non-player actors; no GE replication to simulated proxies
`Mixed`	Player-controlled characters (owner gets full info, others get minimal)
`Full`	Non-player games or debugging; all GEs replicate to all clients

仅在服务器端创建ASC后设置复制模式：

cpp

// 在服务器端的BeginPlay或PossessedBy函数中调用：
AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Mixed);

模式	使用场景
`Minimal`	AI或非玩家角色；不向模拟代理复制GameplayEffect
`Mixed`	玩家控制角色（拥有者获取完整信息，其他客户端获取最小信息）
`Full`	非玩家游戏或调试场景；所有GameplayEffect复制到所有客户端

5. InitAbilityActorInfo

5. 初始化AbilityActorInfo

Must be called on both server and client after possession. Call in

PossessedBy

(server) and

OnRep_PlayerState

(client):

ASC->InitAbilityActorInfo(OwnerActor, AvatarActor)

. See

references/gas-setup-patterns.md

for full dual-path code with respawn handling.

必须在服务器和客户端完成角色控制后调用。在服务器的

PossessedBy

和客户端的

OnRep_PlayerState

中调用：

ASC->InitAbilityActorInfo(OwnerActor, AvatarActor)

。完整的包含重生处理的双路径代码请参考

references/gas-setup-patterns.md

。

GameplayAbilities

Subclass UGameplayAbility

继承UGameplayAbility

cpp

#include "Abilities/GameplayAbility.h"

UCLASS()
class UMyFireballAbility : public UGameplayAbility
{
    GENERATED_BODY()
public:
    UMyFireballAbility();
    virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        const FGameplayEventData* TriggerEventData) override;
    virtual void EndAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateEndAbility, bool bWasCancelled) override;
    // Ability Tasks — async building blocks for latent abilities:
    // UAbilityTask_WaitTargetData    — waits for targeting (crosshair/AoE confirm)
    // UAbilityTask_WaitGameplayEvent — waits for a GameplayEvent tag (e.g., anim notify)
    // UAbilityTask_WaitDelay         — simple timer
    // UAbilityTask_PlayMontageAndWait — montage with callbacks (see ue-animation-system)
    // See references/ability-task-reference.md for full list and custom task pattern.
    // CancelAbility — called by CancelAbilitiesWithTag or ASC->CancelAbility(Handle)
    // Internally calls EndAbility with bWasCancelled=true. Override to add cleanup:
    virtual void CancelAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateCancelAbility) override;
    // Custom activation guard — return false to block activation beyond tag checks
    virtual bool CanActivateAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo, /*...*/) const override;
    // Must call Super first. Add custom checks (resource availability, cooldown state).
protected:
    UPROPERTY(EditDefaultsOnly, Category = "GAS")
    TSubclassOf<UGameplayEffect> DamageEffect;
};

cpp

#include "Abilities/GameplayAbility.h"

UCLASS()
class UMyFireballAbility : public UGameplayAbility
{
    GENERATED_BODY()
public:
    UMyFireballAbility();
    virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        const FGameplayEventData* TriggerEventData) override;
    virtual void EndAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateEndAbility, bool bWasCancelled) override;
    // Ability Tasks — 用于实现延迟能力的异步构建块：
    // UAbilityTask_WaitTargetData    — 等待目标选择（准星/范围确认）
    // UAbilityTask_WaitGameplayEvent — 等待GameplayEvent标签（例如动画通知）
    // UAbilityTask_WaitDelay         — 简单计时器
    // UAbilityTask_PlayMontageAndWait — 带回调的动画蒙太奇（参考ue-animation-system）
    // 完整列表和自定义任务模式请查看references/ability-task-reference.md。
    // CancelAbility — 由CancelAbilitiesWithTag或ASC->CancelAbility(Handle)调用
    // 内部会调用bWasCancelled=true的EndAbility。重写该方法以添加清理逻辑：
    virtual void CancelAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateCancelAbility) override;
    // 自定义激活校验 — 返回false可在标签检查之外阻断能力激活
    virtual bool CanActivateAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo, /*...*/) const override;
    // 必须先调用Super，再添加自定义检查（资源可用性、冷却状态）。
protected:
    UPROPERTY(EditDefaultsOnly, Category = "GAS")
    TSubclassOf<UGameplayEffect> DamageEffect;
};

ActivateAbility Pattern

激活能力的标准模式

cpp

void UMyFireballAbility::ActivateAbility(const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    const FGameplayEventData* TriggerEventData)
{
    // 1. Commit: validates and applies cost + cooldown
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
        return;
    }
    // 2. Apply effect / spawn projectile / etc.
    FGameplayEffectSpecHandle Spec = MakeOutgoingGameplayEffectSpec(DamageEffect, GetAbilityLevel());
    FGameplayAbilityTargetDataHandle TargetData =
        UAbilitySystemBlueprintLibrary::AbilityTargetDataFromActor(
            ActorInfo->AvatarActor.Get());
    ApplyGameplayEffectSpecToTarget(Handle, ActorInfo, ActivationInfo, Spec, TargetData);
    // 3. End (instant abilities end immediately; latent abilities wait for tasks)
    EndAbility(Handle, ActorInfo, ActivationInfo, true, false);
}

CommitAbility

is shorthand for

CommitAbilityCost

CommitAbilityCooldown

. Call them separately when needed -- e.g., commit cost without starting cooldown for a channeled ability, or commit cooldown without cost for a free ability.

cpp

void UMyFireballAbility::ActivateAbility(const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    const FGameplayEventData* TriggerEventData)
{
    // 1. 提交：验证并应用消耗与冷却
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
        return;
    }
    // 2. 应用效果/生成投射物等
    FGameplayEffectSpecHandle Spec = MakeOutgoingGameplayEffectSpec(DamageEffect, GetAbilityLevel());
    FGameplayAbilityTargetDataHandle TargetData =
        UAbilitySystemBlueprintLibrary::AbilityTargetDataFromActor(
            ActorInfo->AvatarActor.Get());
    ApplyGameplayEffectSpecToTarget(Handle, ActorInfo, ActivationInfo, Spec, TargetData);
    // 3. 结束能力（即时能力立即结束；延迟能力需等待任务完成）
    EndAbility(Handle, ActorInfo, ActivationInfo, true, false);
}

CommitAbility

是

CommitAbilityCost

CommitAbilityCooldown

的简写。在需要时可分开调用——例如，对于通道型能力，先提交消耗但不启动冷却；或者对于免费能力，仅提交冷却而无消耗。

Instancing and Net Execution Policy

实例化与网络执行策略

Set in the ability constructor:

cpp

UMyFireballAbility::UMyFireballAbility()
{
    // InstancedPerActor  - one instance per actor; cheapest for persistent abilities
    // InstancedPerExecution - new instance each activation; safe for concurrency
    // NonInstanced       - CDO runs the ability; no per-execution state
    InstancingPolicy = EGameplayAbilityInstancingPolicy::InstancedPerActor;

    // LocalPredicted  - client runs immediately, server validates (player abilities)
    // ServerOnly      - authority only, no prediction
    // LocalOnly       - local client only (UI, cosmetic)
    // ServerInitiated - server activates, clients run non-authoritative predicted copy
    NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::LocalPredicted;
}

在能力的构造函数中设置：

cpp

UMyFireballAbility::UMyFireballAbility()
{
    // InstancedPerActor  - 每个Actor一个实例；对持久化能力来说性能最优
    // InstancedPerExecution - 每次激活创建新实例；并发场景下更安全
    // NonInstanced       - 使用CDO运行能力；无每次执行的独立状态
    InstancingPolicy = EGameplayAbilityInstancingPolicy::InstancedPerActor;

    // LocalPredicted  - 客户端立即执行，服务器验证（玩家能力推荐）
    // ServerOnly      - 仅权威端执行，无预测
    // LocalOnly       - 仅本地客户端执行（UI、 cosmetic效果）
    // ServerInitiated - 服务器激活，客户端运行非权威预测副本
    NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::LocalPredicted;
}

Granting and Activating Abilities

授予与激活能力

cpp

// Grant (server/authority only):
FGameplayAbilitySpecHandle Handle = ASC->GiveAbility(
    FGameplayAbilitySpec(UMyFireballAbility::StaticClass(), 1 /*Level*/));

ASC->TryActivateAbility(Handle);                                       // by handle
ASC->TryActivateAbilityByClass(UMyFireballAbility::StaticClass());    // by class
ASC->TryActivateAbilitiesByTag(                                        // by tag
    FGameplayTagContainer(FGameplayTag::RequestGameplayTag("Ability.Skill.Fireball")));

cpp

// 授予能力（仅服务器/权威端可调用）：
FGameplayAbilitySpecHandle Handle = ASC->GiveAbility(
    FGameplayAbilitySpec(UMyFireballAbility::StaticClass(), 1 /*等级*/));

ASC->TryActivateAbility(Handle);                                       // 通过句柄激活
ASC->TryActivateAbilityByClass(UMyFireballAbility::StaticClass());    // 通过类激活
ASC->TryActivateAbilitiesByTag(                                        // 通过标签激活
    FGameplayTagContainer(FGameplayTag::RequestGameplayTag("Ability.Skill.Fireball")));

Ability Tags

能力标签配置

Configure in the ability CDO constructor:

cpp

// Tags this ability grants to its owner while active:
ActivationOwnedTags.AddTag(FGameplayTag::RequestGameplayTag("Ability.Active.Casting"));
// Tags that prevent this ability from activating:
ActivationBlockedTags.AddTag(FGameplayTag::RequestGameplayTag("State.Stunned"));
// Cancel other active abilities with these tags on activation:
CancelAbilitiesWithTag.AddTag(FGameplayTag::RequestGameplayTag("Ability.Active.Melee"));

在能力的CDO构造函数中配置：

cpp

// 能力激活时授予所有者的标签：
ActivationOwnedTags.AddTag(FGameplayTag::RequestGameplayTag("Ability.Active.Casting"));
// 阻止该能力激活的标签：
ActivationBlockedTags.AddTag(FGameplayTag::RequestGameplayTag("State.Stunned"));
// 激活时会取消其他拥有以下标签的活跃能力：
CancelAbilitiesWithTag.AddTag(FGameplayTag::RequestGameplayTag("Ability.Active.Melee"));

GameplayEffects

Duration Policies

时长策略

Policy	Behavior
`Instant`	Executes once; modifies attribute base value permanently
`HasDuration`	Active for set duration; uses `DurationMagnitude` (seconds)
`Infinite`	Active until `RemoveActiveGameplayEffect` is called

策略	行为
`Instant`	执行一次；永久修改属性的基础值
`HasDuration`	在设定时长内生效；使用 `DurationMagnitude` （秒）配置时长
`Infinite`	持续生效，直到调用 `RemoveActiveGameplayEffect`

Applying Effects

应用效果

cpp

FGameplayEffectContextHandle Ctx = ASC->MakeEffectContext();
FGameplayEffectSpecHandle Spec = ASC->MakeOutgoingSpec(UMyDamageEffect::StaticClass(), Level, Ctx);

// SetByCaller: inject runtime magnitude using a tag key
Spec.Data->SetSetByCallerMagnitude(
    FGameplayTag::RequestGameplayTag("SetByCaller.Damage"), 75.f);

ASC->ApplyGameplayEffectSpecToSelf(*Spec.Data.Get());         // self
ASC->ApplyGameplayEffectSpecToTarget(*Spec.Data.Get(), TargetASC); // target

ASC->RemoveActiveGameplayEffect(ActiveHandle);                // by handle
ASC->RemoveActiveGameplayEffectBySourceEffect(
    UMyDamageEffect::StaticClass(), nullptr);                  // by class

See

references/gameplay-effect-reference.md

for stacking (AggregateBySource/AggregateByTarget), periodic effects (damage over time),

UGameplayEffectExecutionCalculation

(complex modifier logic), conditional effects, and immunity.

cpp

FGameplayEffectContextHandle Ctx = ASC->MakeEffectContext();
FGameplayEffectSpecHandle Spec = ASC->MakeOutgoingSpec(UMyDamageEffect::StaticClass(), Level, Ctx);

// SetByCaller：使用标签键注入运行时数值
Spec.Data->SetSetByCallerMagnitude(
    FGameplayTag::RequestGameplayTag("SetByCaller.Damage"), 75.f);

ASC->ApplyGameplayEffectSpecToSelf(*Spec.Data.Get());         // 应用到自身
ASC->ApplyGameplayEffectSpecToTarget(*Spec.Data.Get(), TargetASC); // 应用到目标

ASC->RemoveActiveGameplayEffect(ActiveHandle);                // 通过句柄移除
ASC->RemoveActiveGameplayEffectBySourceEffect(
    UMyDamageEffect::StaticClass(), nullptr);                  // 通过类移除

叠加规则（按源/按目标聚合）、周期性效果（持续伤害）、

UGameplayEffectExecutionCalculation

（复杂修改逻辑）、条件效果和免疫设置等内容，请查看

references/gameplay-effect-reference.md

。

AttributeSet

Define Attributes

定义属性

cpp

// MyHealthSet.h
#include "AttributeSet.h"
#include "AbilitySystemComponent.h"

// Convenience macro - define in your project headers
#define ATTRIBUTE_ACCESSORS(ClassName, PropertyName) \
    GAMEPLAYATTRIBUTE_PROPERTY_GETTER(ClassName, PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_GETTER(PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_SETTER(PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_INITTER(PropertyName)

UCLASS()
class UMyHealthSet : public UAttributeSet
{
    GENERATED_BODY()
public:
    UMyHealthSet();

    // Called BEFORE any modification - use for clamping current value
    virtual void PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue) override;

    // Called AFTER instant GE executes - react to changes (death, events)
    virtual void PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data) override;

    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

    UPROPERTY(BlueprintReadOnly, ReplicatedUsing = OnRep_Health, Category = "Health")
    FGameplayAttributeData Health;
    ATTRIBUTE_ACCESSORS(UMyHealthSet, Health)

    UPROPERTY(BlueprintReadOnly, ReplicatedUsing = OnRep_MaxHealth, Category = "Health")
    FGameplayAttributeData MaxHealth;
    ATTRIBUTE_ACCESSORS(UMyHealthSet, MaxHealth)

protected:
    UFUNCTION()
    void OnRep_Health(const FGameplayAttributeData& OldHealth);

    UFUNCTION()
    void OnRep_MaxHealth(const FGameplayAttributeData& OldMaxHealth);
};

In the

.cpp

, implement replication and callbacks:

cpp

void UMyHealthSet::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
    DOREPLIFETIME_CONDITION_NOTIFY(UMyHealthSet, Health, COND_None, REPNOTIFY_Always);
    DOREPLIFETIME_CONDITION_NOTIFY(UMyHealthSet, MaxHealth, COND_None, REPNOTIFY_Always);
}

void UMyHealthSet::OnRep_Health(const FGameplayAttributeData& OldHealth)
{
    GAMEPLAYATTRIBUTE_REPNOTIFY(UMyHealthSet, Health, OldHealth);
}

// PreAttributeChange: clamp CURRENT value before any modification
void UMyHealthSet::PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue)
{
    Super::PreAttributeChange(Attribute, NewValue);
    if (Attribute == GetHealthAttribute())
        NewValue = FMath::Clamp(NewValue, 0.f, GetMaxHealth());
}

// PostGameplayEffectExecute: react AFTER instant GE modifies base value (damage, death)
void UMyHealthSet::PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data)
{
    Super::PostGameplayEffectExecute(Data);
    if (Data.EvaluatedData.Attribute == GetHealthAttribute())
    {
        SetHealth(FMath::Clamp(GetHealth(), 0.f, GetMaxHealth()));
        if (GetHealth() <= 0.f) { /* trigger death */ }
    }
}

cpp

// MyHealthSet.h
#include "AttributeSet.h"
#include "AbilitySystemComponent.h"

// 便捷宏 - 在项目头文件中定义
#define ATTRIBUTE_ACCESSORS(ClassName, PropertyName) \
    GAMEPLAYATTRIBUTE_PROPERTY_GETTER(ClassName, PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_GETTER(PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_SETTER(PropertyName) \
    GAMEPLAYATTRIBUTE_VALUE_INITTER(PropertyName)

UCLASS()
class UMyHealthSet : public UAttributeSet
{
    GENERATED_BODY()
public:
    UMyHealthSet();

    // 在属性修改前调用 - 用于限制当前值的范围
    virtual void PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue) override;

    // 即时GameplayEffect执行后调用 - 响应属性变化（死亡、事件触发）
    virtual void PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data) override;

    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

    UPROPERTY(BlueprintReadOnly, ReplicatedUsing = OnRep_Health, Category = "Health")
    FGameplayAttributeData Health;
    ATTRIBUTE_ACCESSORS(UMyHealthSet, Health)

    UPROPERTY(BlueprintReadOnly, ReplicatedUsing = OnRep_MaxHealth, Category = "Health")
    FGameplayAttributeData MaxHealth;
    ATTRIBUTE_ACCESSORS(UMyHealthSet, MaxHealth)

protected:
    UFUNCTION()
    void OnRep_Health(const FGameplayAttributeData& OldHealth);

    UFUNCTION()
    void OnRep_MaxHealth(const FGameplayAttributeData& OldMaxHealth);
};

在

.cpp

文件中实现复制与回调逻辑：

cpp

void UMyHealthSet::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
    DOREPLIFETIME_CONDITION_NOTIFY(UMyHealthSet, Health, COND_None, REPNOTIFY_Always);
    DOREPLIFETIME_CONDITION_NOTIFY(UMyHealthSet, MaxHealth, COND_None, REPNOTIFY_Always);
}

void UMyHealthSet::OnRep_Health(const FGameplayAttributeData& OldHealth)
{
    GAMEPLAYATTRIBUTE_REPNOTIFY(UMyHealthSet, Health, OldHealth);
}

// PreAttributeChange: 在任何修改前限制当前值的范围
void UMyHealthSet::PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue)
{
    Super::PreAttributeChange(Attribute, NewValue);
    if (Attribute == GetHealthAttribute())
        NewValue = FMath::Clamp(NewValue, 0.f, GetMaxHealth());
}

// PostGameplayEffectExecute: 即时GameplayEffect修改基础值后响应（伤害、死亡）
void UMyHealthSet::PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data)
{
    Super::PostGameplayEffectExecute(Data);
    if (Data.EvaluatedData.Attribute == GetHealthAttribute())
    {
        SetHealth(FMath::Clamp(GetHealth(), 0.f, GetMaxHealth()));
        if (GetHealth() <= 0.f) { /* 触发死亡逻辑 */ }
    }
}

Register AttributeSet on ASC

在ASC上注册AttributeSet

cpp

// In PlayerState or Character constructor:
// Option 1: CreateDefaultSubobject (auto-registered as subobject)
HealthSet = CreateDefaultSubobject<UMyHealthSet>(TEXT("HealthSet"));

// Option 2: Runtime (authority only) — create and register as subobject:
UMyHealthSet* NewSet = NewObject<UMyHealthSet>(this);
AbilitySystemComponent->AddSpawnedAttribute(NewSet);

// Read attribute value:
float CurrentHealth = AbilitySystemComponent->GetNumericAttribute(
    UMyHealthSet::GetHealthAttribute());

Multiple AttributeSets: An ASC can host multiple

UAttributeSet

subclasses (e.g.,

UHealthSet

UOffenseSet

), each auto-discovered via subobject enumeration. Never register two instances of the same class -- the second is silently ignored.

cpp

// 在PlayerState或Character的构造函数中：
// 选项1: CreateDefaultSubobject（自动作为子对象注册）
HealthSet = CreateDefaultSubobject<UMyHealthSet>(TEXT("HealthSet"));

// 选项2: 运行时注册（仅权威端）—— 创建并注册为子对象：
UMyHealthSet* NewSet = NewObject<UMyHealthSet>(this);
AbilitySystemComponent->AddSpawnedAttribute(NewSet);

// 读取属性值：
float CurrentHealth = AbilitySystemComponent->GetNumericAttribute(
    UMyHealthSet::GetHealthAttribute());

多AttributeSet: 一个ASC可以托管多个

UAttributeSet

子类（例如

UHealthSet

UOffenseSet

），每个子类会通过子对象枚举自动被发现。不要注册同一类的多个实例——第二个实例会被静默忽略。

GameplayTags

Defining Tags

定义标签

Config/DefaultGameplayTags.ini

or via native tags (preferred for code references):

cpp

// MyGameplayTags.h
#include "NativeGameplayTags.h"
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_Ability_Fireball)
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_State_Stunned)

// MyGameplayTags.cpp
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_Ability_Fireball, "Ability.Skill.Fireball", "Fireball ability")
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_State_Stunned, "State.Stunned", "Actor is stunned")

在

Config/DefaultGameplayTags.ini

中定义，或通过原生标签定义（代码引用时推荐）：

cpp

// MyGameplayTags.h
#include "NativeGameplayTags.h"
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_Ability_Fireball)
UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_State_Stunned)

// MyGameplayTags.cpp
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_Ability_Fireball, "Ability.Skill.Fireball", "火球术能力")
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_State_Stunned, "State.Stunned", "Actor处于眩晕状态")

Tag Matching

标签匹配

"A.1".MatchesTag("A") == true

(hierarchical);

MatchesTagExact

requires exact match.

cpp

FGameplayTagContainer Tags;
Tags.HasTag(FireballTag);      // parent-aware match
Tags.HasTagExact(FireballTag); // exact only
Tags.HasAny(OtherContainer);
Tags.HasAll(OtherContainer);

// Query ASC:
ASC->HasMatchingGameplayTag(TAG_State_Stunned);
ASC->GetOwnedGameplayTags(); // FGameplayTagContainer

// Listen for changes:
ASC->RegisterGameplayTagEvent(TAG_State_Stunned, EGameplayTagEventType::NewOrRemoved)
    .AddUObject(this, &AMyCharacter::OnStunnedTagChanged);

"A.1".MatchesTag("A") == true

（层级匹配）；

MatchesTagExact

要求完全匹配。

cpp

FGameplayTagContainer Tags;
Tags.HasTag(FireballTag);      // 支持父标签匹配
Tags.HasTagExact(FireballTag); // 仅完全匹配
Tags.HasAny(OtherContainer);
Tags.HasAll(OtherContainer);

// 查询ASC的标签状态：
ASC->HasMatchingGameplayTag(TAG_State_Stunned);
ASC->GetOwnedGameplayTags(); // 返回FGameplayTagContainer

// 监听标签变化：
ASC->RegisterGameplayTagEvent(TAG_State_Stunned, EGameplayTagEventType::NewOrRemoved)
    .AddUObject(this, &AMyCharacter::OnStunnedTagChanged);

Loose Tags (Manual, No GE)

松散标签（手动管理，不关联GameplayEffect）

cpp

ASC->AddLooseGameplayTag(TAG_State_Stunned);
ASC->RemoveLooseGameplayTag(TAG_State_Stunned);
// Loose tags are NOT replicated by default. To replicate a loose tag,
// pass EGameplayTagReplicationState::TagOnly as the third argument:
ASC->AddLooseGameplayTag(TAG_State_Buffed, 1, EGameplayTagReplicationState::TagOnly);
ASC->RemoveLooseGameplayTag(TAG_State_Buffed, 1, EGameplayTagReplicationState::TagOnly);

cpp

ASC->AddLooseGameplayTag(TAG_State_Stunned);
ASC->RemoveLooseGameplayTag(TAG_State_Stunned);
// 松散标签默认不复制。若要复制松散标签，
// 需将第三个参数设为EGameplayTagReplicationState::TagOnly：
ASC->AddLooseGameplayTag(TAG_State_Buffed, 1, EGameplayTagReplicationState::TagOnly);
ASC->RemoveLooseGameplayTag(TAG_State_Buffed, 1, EGameplayTagReplicationState::TagOnly);

GameplayCues

Cosmetic-only (particles, sounds, decals). Never affect gameplay state. Tag prefix:

GameplayCue.

In the GE asset, add

FGameplayEffectCue

entries with

GameplayCueTags

and level range.

cpp

// Burst (one-shot):
ASC->ExecuteGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Hit.Fire"),
    ASC->MakeEffectContext());

// Persistent (add/remove pair):
ASC->AddGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));
ASC->RemoveGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));

// Poll active state:
bool bActive = ASC->IsGameplayCueActive(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));

Cue Notify classes:

AGameplayCueNotify_Actor

: Persistent/looping. Overrides

OnActive

WhileActive

OnRemove

```
AGameplayCueNotify_Static
```
: Burst/one-shot. Overrides
```
OnExecute
```
.

Place cue notify assets in

/Game/GAS/GameplayCues/

for

UGameplayCueManager

auto-discovery.

仅用于表现效果（粒子、音效、贴花），绝不能影响游戏状态。标签前缀为

GameplayCue.

在GameplayEffect资源中添加

FGameplayEffectCue

条目，配置

GameplayCueTags

和等级范围。

cpp

// 一次性触发：
ASC->ExecuteGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Hit.Fire"),
    ASC->MakeEffectContext());

// 持久化触发（需成对调用添加/移除）：
ASC->AddGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));
ASC->RemoveGameplayCue(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));

// 检查激活状态：
bool bActive = ASC->IsGameplayCueActive(FGameplayTag::RequestGameplayTag("GameplayCue.Buff.Speed"));

Cue通知类：

AGameplayCueNotify_Actor

: 持久化/循环效果。重写

OnActive

、

WhileActive

、

OnRemove

方法。

```
AGameplayCueNotify_Static
```
: 一次性触发效果。重写
```
OnExecute
```
方法。

将Cue通知资源放置在

/Game/GAS/GameplayCues/

目录下，以便

UGameplayCueManager

自动发现。

Common Mistakes and Anti-Patterns

常见错误与反模式

ASC ownership confusion: Implement

IAbilitySystemInterface

on the class that owns the ASC (PlayerState), not just on the Pawn. Otherwise

UAbilitySystemBlueprintLibrary

lookups fail.

InitAbilityActorInfo only on server: Clients need it too. Call in

OnRep_PlayerState

(client) and

PossessedBy

(server). Skipping client-side init breaks attribute replication on the owning client.

GEs applied before InitAbilityActorInfo: The ASC is not ready; attributes are not registered. Always complete init before granting abilities or applying effects.

PreAttributeChange vs PostGameplayEffectExecute:

PreAttributeChange

fires on every current-value change (aggregator updates, buff adds/removes). Use it only to clamp. Use

PostGameplayEffectExecute

to react to instant GE base-value execution (damage, death). Never send game events from

PreAttributeChange

Forgetting CommitAbility: Without it, the ability runs but consumes no mana and starts no cooldown.

Loose tags not replicated:

AddLooseGameplayTag

does not replicate by default. Pass

EGameplayTagReplicationState::TagOnly

as the third argument to replicate the tag, or grant via a GE for fully replicated effect-driven tags.

Effect stacking overflow: Stacks beyond

LimitCount

are silently rejected. Use

GetCurrentStackCount

to inspect the current level before attempting further stack applications.

GAS with AI: AI has no PlayerState. Place the ASC on the AICharacter, call

InitAbilityActorInfo(AICharacter, AICharacter)

, set replication mode to

Minimal

Hot-joining: Late-joining clients receive active effects via

FActiveGameplayEffectsContainer

replication after

InitAbilityActorInfo

. Never apply startup GEs in

BeginPlay

unconditionally -- server-only, or late joiners double-apply.

ASC归属混淆：在拥有ASC的类（如PlayerState）上实现

IAbilitySystemInterface

，而不仅仅是Pawn。否则

UAbilitySystemBlueprintLibrary

的查找会失败。

仅在服务器端初始化AbilityActorInfo：客户端也需要调用该方法。在客户端的

OnRep_PlayerState

和服务器端的

PossessedBy

中都要调用。跳过客户端初始化会导致拥有者客户端的属性复制失效。

在初始化AbilityActorInfo前应用GameplayEffect：此时ASC尚未就绪，属性未完成注册。必须在初始化完成后再授予能力或应用效果。

PreAttributeChange与PostGameplayEffectExecute的误用：

PreAttributeChange

会在每次当前值变更时触发（聚合器更新、增益添加/移除）。仅用它来限制数值范围。

PostGameplayEffectExecute

用于响应即时GameplayEffect对基础值的修改（伤害、死亡）。绝不要在

PreAttributeChange

中发送游戏事件。

忘记调用CommitAbility：如果不调用该方法，能力会正常执行但不会消耗资源也不会启动冷却。

松散标签未复制：

AddLooseGameplayTag

默认不复制。若要复制标签，需将第三个参数设为

EGameplayTagReplicationState::TagOnly

，或通过GameplayEffect授予标签以实现完全复制的效果驱动标签。

效果叠加溢出：超过

LimitCount

的叠加会被静默拒绝。在尝试叠加前，使用

GetCurrentStackCount

检查当前叠加层数。

AI使用GAS：AI没有PlayerState。将ASC放置在AICharacter上，调用

InitAbilityActorInfo(AICharacter, AICharacter)

，并将复制模式设为

Minimal

。

热加入：延迟加入的客户端会在

InitAbilityActorInfo

后通过

FActiveGameplayEffectsContainer

复制获取活跃效果。不要在

BeginPlay

中无条件应用启动GameplayEffect——仅在服务器端执行，否则延迟加入的客户端会重复应用。

Reference Files

参考文件

```
references/gas-setup-patterns.md
```
— Full ASC ownership patterns and initialization sequences for PlayerState and Character owners, multiplayer and single-player
```
references/gameplay-effect-reference.md
```
— Effect configuration, stacking rules, modifier types, execution calculations, periodic effects, conditional effects
```
references/ability-task-reference.md
```
— Common built-in ability tasks and custom task patterns

```
references/gas-setup-patterns.md
```
— 完整的ASC归属模式和初始化流程，包含PlayerState和Character两种归属场景，覆盖多人和单人游戏
```
references/gameplay-effect-reference.md
```
— 效果配置、叠加规则、修改器类型、执行计算、周期性效果、条件效果
```
references/ability-task-reference.md
```
— 常用内置Ability Task和自定义任务模式

ue-gameplay-abilities

Original

Translation

Gameplay Ability System (GAS)

Gameplay Ability System (GAS)

Context Check

上下文检查

Information Gathering

信息收集

GAS Architecture Overview

GAS架构概述

GAS Setup

GAS设置

1. Enable the Plugin

1. 启用插件

2. AbilitySystemComponent Ownership

2. AbilitySystemComponent归属

3. IAbilitySystemInterface

3. 实现IAbilitySystemInterface

4. Replication Modes

4. 复制模式设置

5. InitAbilityActorInfo

5. 初始化AbilityActorInfo

GameplayAbilities

GameplayAbilities

Subclass UGameplayAbility

继承UGameplayAbility

ActivateAbility Pattern

激活能力的标准模式

Instancing and Net Execution Policy

实例化与网络执行策略

Granting and Activating Abilities

授予与激活能力

Ability Tags

能力标签配置

GameplayEffects

GameplayEffects

Duration Policies

时长策略

Applying Effects

应用效果

AttributeSet

AttributeSet

Define Attributes

定义属性

Register AttributeSet on ASC

在ASC上注册AttributeSet

GameplayTags

GameplayTags

Defining Tags

定义标签

Tag Matching

标签匹配

Loose Tags (Manual, No GE)

松散标签（手动管理，不关联GameplayEffect）

GameplayCues

GameplayCues

Common Mistakes and Anti-Patterns

常见错误与反模式

Reference Files

参考文件

Related Skills

相关技能