1010 lines
37 KiB
Markdown
1010 lines
37 KiB
Markdown
---
|
||
tags:
|
||
- GAS
|
||
- UE5
|
||
- 重构
|
||
- 技术文档
|
||
- RPGGameplayAbility
|
||
created: 2026-05-30
|
||
status: draft
|
||
project: MusicFighterGame
|
||
---
|
||
|
||
# RPGGameplayAbility GAS 插件重构文档
|
||
|
||
> 基于 Lyra Starter Game、GASShooter、UE5 GAS Aura 深度研究的全面重构方案
|
||
|
||
---
|
||
|
||
## 执行摘要
|
||
|
||
本文档基于对三个工业级 Unreal Engine 5 GAS 项目的深度代码研究，对现有 `RPGGameplayAbility` 插件进行全面评估，并提出系统性重构方案。
|
||
|
||
### 核心发现
|
||
|
||
| 维度 | 现状 | 目标 |
|
||
|------|------|------|
|
||
| 属性系统 | 1 个属性集 20 属性，混合三种游戏类型 | 三层属性体系，按职责拆分 |
|
||
| 输入绑定 | 枚举 `EGSAbilityInputID` 硬编码游戏动作 | GameplayTag 驱动，数据资产配置 |
|
||
| 能力激活策略 | 3 个布尔值分散控制 | 统一 `ActivationPolicy` + `ActivationGroup` 枚举 |
|
||
| 命名规范 | GS/RPG 前缀混用，GASShooter 残留 | 统一 RPG 前缀，清理全部残留 |
|
||
| Tag 管理 | 分散在5个 DataTable | 集中式原生 Tag 单例 |
|
||
| UI 架构 | 直接调用 BlueprintImplementableEvent | WidgetController MVC 模式 |
|
||
| Cost 系统 | 仅蓝图层 `RPGCheckCost/RPGApplyCost` | 可扩展 `ULyraAbilityCost` 模式 |
|
||
|
||
### 优先级总结
|
||
|
||
- **P0（立即修复）**：PURE_VIRTUAL 宏类名错误、GS 前缀残留清理
|
||
- **P1（核心重构）**：属性集拆分、输入系统 Tag 化、Activation Policy 引入
|
||
- **P2（架构升级）**：WidgetController MVC、Tag Relationship Mapping、Cost 系统扩展
|
||
- **P3（新功能）**：连击系统、全局 Ability 分发、GamePhase 系统
|
||
|
||
---
|
||
|
||
## 一、现有插件深度分析
|
||
|
||
### 1.1 插件概述
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 名称 | RPGGameplayAbility |
|
||
| 版本 | 1.0 |
|
||
| 作者 | BlueRose |
|
||
| 起源 | 基于 GASShooter 示例项目改编 |
|
||
| 模块数 | 5 个（主模块 + LoadingScreen + GameplayMessage × 2） |
|
||
|
||
**依赖插件**：GameplayAbilities、GameplayTagsEditor、EnhancedInput、CommonUI、ModelViewViewModel
|
||
|
||
### 1.2 模块结构
|
||
|
||
```
|
||
Source/
|
||
├── RPGGameplayAbility/ [主模块 - Runtime, PreLoadingScreen]
|
||
│ ├── Public/Abilities/ 核心 GAS 类（ASC/Globals/Types/CueManager）
|
||
│ ├── Public/AbilityTasks/ 10 个自定义 AbilityTask
|
||
│ ├── Public/AttributeSets/ 1 个合并属性集（20 属性）
|
||
│ ├── Public/GameplayEffects/ 伤害 ExecutionCalculation
|
||
│ ├── Public/Target/ TargetType 策略 + Trace TargetActor
|
||
│ ├── Public/Interfaces/ IRPGInteractable
|
||
│ ├── Public/Actors/ ARPGActorBase/ARPGPickup/ARPGProjectile
|
||
│ ├── Public/Characters/ 6 个角色类（Base + 3 游戏类型）
|
||
│ └── Public/UI/ 4 个 UI 组件
|
||
├── CommonLoadingScreen/
|
||
├── CommonStartupLoadingScreen/
|
||
├── GameplayMessageRuntime/
|
||
└── GameplayMessageNodes/
|
||
```
|
||
|
||
### 1.3 类层次结构（当前）
|
||
|
||
```
|
||
[Ability 层]
|
||
UGameplayAbility
|
||
└── URPGGameplayAbility ← 核心基类（激活策略/EffectContainer/多Mesh动画）
|
||
└── URPGGA_CharacterJump ← 跳跃能力
|
||
|
||
[ASC 层]
|
||
UAbilitySystemComponent
|
||
└── URPGAbilitySystemComponent ← 多Mesh蒙太奇/RPC批处理/预测GE
|
||
|
||
[属性集层]
|
||
UAttributeSet
|
||
└── URPGAttributeSetBase ← 20 属性合并（反模式）
|
||
|
||
[计算层]
|
||
UGameplayEffectExecutionCalculation
|
||
└── URPGDamageExecutionCalc ← 护甲减伤 + 爆头 1.5x
|
||
|
||
[全局配置]
|
||
UAbilitySystemGlobals
|
||
└── URPGAbilitySystemGlobals ← 自定义 EffectContext
|
||
UGameplayCueManager
|
||
└── URPGGameplayCueManager ← 按需加载
|
||
UEngineSubsystem
|
||
└── URPGEngineSubsystem ← 启动时 InitGlobalData
|
||
|
||
[角色层]
|
||
ACharacter
|
||
└── ARPGCharacterBase ← GAS 角色基类
|
||
├── AActionRPGCharacter ← ARPG（交互/复活）
|
||
├── ARPGFighterCharacter ← 格斗（EnhancedInput）
|
||
└── ARPGShooterCharacter ← 射击
|
||
```
|
||
|
||
### 1.4 现有功能清单
|
||
|
||
| 功能域 | 功能点 | 状态 |
|
||
|--------|--------|------|
|
||
| **核心 GAS** | ASC/Globals/EffectContext/CueManager | ✅ 完成 |
|
||
| **Ability 基类** | EffectContainerMap / 被动 / 武器绑定 / RPC 批处理 | ✅ 完成 |
|
||
| **多 Mesh 蒙太奇** | 支持一个 Avatar 上多个 SkeletalMesh 同时播放并复制 | ✅ 完成 |
|
||
| **AttributeSet** | 20 个属性（生命/法力/耐力/护盾/护甲/移速/等级/XP/金币） | ✅ 完成但粗糙 |
|
||
| **伤害计算** | ExecutionCalculation（护甲减伤 + 爆头） | ✅ 完成 |
|
||
| **Target 系统** | TargetType 策略 + 线/球追踪 TargetActor + 散布系统 | ✅ 完成 |
|
||
| **AbilityTask** | 蒙太奇/目标等待/输入等待/交互扫描/延迟/移动 | ✅ 完成（10 个） |
|
||
| **UI 异步工具** | 属性变化监听 / Tag 变化监听 | ✅ 完成 |
|
||
| **交互系统** | IRPGInteractable（Pre/Post/Cancel + 同步策略） | ✅ 完成 |
|
||
| **角色系统** | Base + 三种游戏类型子类 + 死亡/倒地 | ✅ 完成 |
|
||
| **连击/输入缓冲** | 无 | ❌ 缺失 |
|
||
| **Buff/Debuff 管理** | 无统一管理层 | ❌ 缺失 |
|
||
| **Cooldown C++ 封装** | 完全依赖蓝图配置 | ❌ 缺失 |
|
||
| **WidgetController MVC** | 直接 BlueprintImplementableEvent | ❌ 缺失 |
|
||
| **技能升级系统** | 无 | ❌ 缺失 |
|
||
|
||
### 1.5 代码质量问题（按严重性）
|
||
|
||
#### P0：高优先级问题
|
||
|
||
**1. PURE_VIRTUAL 宏类名错误**
|
||
|
||
```cpp
|
||
// RPGGATA_Trace.h - 错误的代码
|
||
PURE_VIRTUAL(AGSGATA_Trace::DoTrace, ...); // ❌ 错误类名
|
||
PURE_VIRTUAL(AGSGATA_Trace::ShowDebugTrace, ...); // ❌ 错误类名
|
||
|
||
// 应该是：
|
||
PURE_VIRTUAL(ARPGGATA_Trace::DoTrace, ...); // ✅
|
||
```
|
||
|
||
**2. GASShooter 原始项目名残留**
|
||
|
||
- `EGSAbilityInputID`（GS 前缀来自 GASShooter）
|
||
- `FGSPlayMontageForMeshAndWaitForEventDelegate`
|
||
- 注释中大量 `AGSCharacterBase`、`GSAT_WaitTargetDataUsingActor` 引用
|
||
- 头文件注释 `#include "GASShooter/GASShooter.h"` 残留
|
||
|
||
#### P1：中优先级问题
|
||
|
||
**3. 上帝属性集反模式**
|
||
|
||
`URPGAttributeSetBase` 将 20 个属性塞入单个类：混合了射击游戏（Armor/弹药）、ARPG（XP/Gold）、格斗游戏（Stamina）的属性。职责不清，难以按游戏类型裁剪。
|
||
|
||
**4. 枚举与游戏类型强耦合**
|
||
|
||
```cpp
|
||
UENUM(BlueprintType)
|
||
enum class EGSAbilityInputID : uint8 {
|
||
None,
|
||
Confirm, Cancel,
|
||
PrimaryFire, SecondaryFire, Reload, // 射击游戏专用
|
||
NextWeapon, PrevWeapon, // 武器切换
|
||
Sprint, Jump, Interact, // 通用动作
|
||
Crouch // 但对格斗游戏无意义
|
||
};
|
||
```
|
||
|
||
对于 FighterGame，`PrimaryFire/Reload/NextWeapon` 等枚举完全不适用，浪费枚举空间且产生误导。
|
||
|
||
**5. 命名不一致**
|
||
|
||
| 错误 | 位置 |
|
||
|------|------|
|
||
| `EGSAbilityInputID`（GS 前缀） | RPGAbilityTypes.h |
|
||
| `FAbilityMeshMontage`（无前缀） | RPGAbilitySystemComponent.h |
|
||
| `FGSPlayMontageForMeshAndWaitForEvent*`（GS 前缀） | RPGAT_PlayMontageForMeshAndWaitForEvent.h |
|
||
|
||
#### P2：低优先级问题
|
||
|
||
**6. 硬编码值**
|
||
|
||
```cpp
|
||
// RPGDamageExecutionCalc.cpp
|
||
const float HeadShotMultiplier = 1.5f; // 不可配置
|
||
const FName BoneName = "b_head"; // 硬编码骨骼名
|
||
// 护甲减伤公式 100/(100+Armor) 硬编码
|
||
```
|
||
|
||
**7. 死代码**
|
||
|
||
```cpp
|
||
// RPGAbilityTypes.h 中 include 但未使用
|
||
#include "Abilities/Tasks/AbilityTask_WaitGameplayEffectStackChange.h"
|
||
#include "Abilities/Tasks/AbilityTask_WaitGameplayEffectRemoved.h"
|
||
```
|
||
|
||
---
|
||
|
||
## 二、参考项目核心架构分析
|
||
|
||
### 2.1 Lyra Starter Game — 企业级 GAS 架构
|
||
|
||
Lyra 是 Epic Games 官方现代 GAS 最佳实践项目，代表了 UE5 时代的设计标准。
|
||
|
||
#### 2.1.1 Activation Policy + Activation Group 双维控制
|
||
|
||
```cpp
|
||
// LyraGameplayAbility.h
|
||
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly)
|
||
ELyraAbilityActivationPolicy ActivationPolicy;
|
||
// OnInputTriggered - 输入按下时激活一次
|
||
// WhileInputActive - 按住期间持续尝试激活（自动武器/冲刺）
|
||
// OnSpawn - Avatar 生成时自动激活（被动技能）
|
||
|
||
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly)
|
||
ELyraAbilityActivationGroup ActivationGroup;
|
||
// Independent - 互不干扰
|
||
// Exclusive_Replaceable - 激活时取消其他 Exclusive，可被替换
|
||
// Exclusive_Blocking - 激活时取消所有 Replaceable，且不可被替换
|
||
```
|
||
|
||
这两个维度分别控制"何时激活"与"激活后如何处理其他技能"，相比分散的布尔值更加清晰。
|
||
|
||
#### 2.1.2 帧级输入缓冲机制
|
||
|
||
```cpp
|
||
// LyraAbilitySystemComponent.h
|
||
TArray<FGameplayAbilitySpecHandle> InputPressedSpecHandles;
|
||
TArray<FGameplayAbilitySpecHandle> InputReleasedSpecHandles;
|
||
TArray<FGameplayAbilitySpecHandle> InputHeldSpecHandles;
|
||
|
||
// ProcessAbilityInput() 每帧统一处理：
|
||
// 1. 检查 InputBlocked Tag
|
||
// 2. 收集所有待激活 Ability（Held/Pressed）
|
||
// 3. 统一 TryActivateAbility（避免顺序竞争）
|
||
// 4. 转发 InputReleased 事件
|
||
// 5. 清空缓存
|
||
```
|
||
|
||
避免了逐 Ability 处理时的时间顺序竞争问题。
|
||
|
||
#### 2.1.3 InputTag 三层解耦架构
|
||
|
||
```
|
||
UInputAction（EnhancedInput）
|
||
→ ULyraInputConfig（DataAsset）
|
||
→ InputTag（GameplayTag）
|
||
→ DynamicSpecSourceTags（注入 AbilitySpec）
|
||
→ ProcessAbilityInput（HasTagExact 匹配激活）
|
||
```
|
||
|
||
策划可在数据层完全重组输入映射，无需修改代码。
|
||
|
||
#### 2.1.4 AbilitySet — 声明式模块化授权
|
||
|
||
```cpp
|
||
// 不可变 Data Asset，包含三种授予项
|
||
UPROPERTY() TArray<FLyraAbilitySet_GameplayAbility> GrantedGameplayAbilities;
|
||
UPROPERTY() TArray<FLyraAbilitySet_GameplayEffect> GrantedGameplayEffects;
|
||
UPROPERTY() TArray<FLyraAbilitySet_AttributeSet> GrantedAttributes;
|
||
|
||
// GiveToAbilitySystem 时将 InputTag 注入 DynamicSpecSourceTags
|
||
AbilitySpec.GetDynamicSpecSourceTags().AddTag(AbilityToGrant.InputTag);
|
||
```
|
||
|
||
配合 `GameFeatureAction_AddAbilities` 实现 DLC/Mod 级别的能力热插拔。
|
||
|
||
#### 2.1.5 Tag Relationship Mapping 数据驱动
|
||
|
||
将 Ability Tag 之间的 Block/Cancel/Required 关系外部化为 Data Asset。策划修改技能互斥关系无需编译代码。
|
||
|
||
```cpp
|
||
// 激活 Ability 时动态扩展 Block/Cancel Tags
|
||
void ApplyAbilityBlockAndCancelTags(...) override {
|
||
if (TagRelationshipMapping) {
|
||
TagRelationshipMapping->GetAbilityTagsToBlockAndCancel(
|
||
AbilityTags, &ModifiedBlockTags, &ModifiedCancelTags);
|
||
}
|
||
Super::ApplyAbilityBlockAndCancelTags(...);
|
||
}
|
||
```
|
||
|
||
#### 2.1.6 Meta Attribute 管线 + HideFromModifiers
|
||
|
||
```cpp
|
||
// LyraHealthSet.h
|
||
UPROPERTY(meta=(HideFromModifiers)) FGameplayAttributeData Health; // 只有 ExecCalc 能改
|
||
UPROPERTY() FGameplayAttributeData MaxHealth;
|
||
UPROPERTY(meta=(HideFromModifiers)) FGameplayAttributeData Damage; // 临时元属性
|
||
UPROPERTY() FGameplayAttributeData Healing; // 临时元属性
|
||
|
||
// PostGameplayEffectExecute 中：
|
||
// Damage 元属性 -> 免疫检查 -> 转换为 Health 减少 -> 清零 Damage
|
||
```
|
||
|
||
`HideFromModifiers` 防止普通 GE Modifier 直接操纵 Health，所有伤害必须走 ExecutionCalculation 管线。
|
||
|
||
#### 2.1.7 GlobalAbilitySystem — 全局 Ability 分发
|
||
|
||
```cpp
|
||
// WorldSubsystem，管理全局 GE/Ability 分发
|
||
void RegisterASC(ULyraAbilitySystemComponent* ASC) {
|
||
// 自动将已有全局效果施加到新注册的 ASC
|
||
// 支持角色重生后自动重新应用
|
||
}
|
||
```
|
||
|
||
#### 2.1.8 AdditionalCosts 可扩展 Cost 系统
|
||
|
||
```cpp
|
||
UPROPERTY(EditDefaultsOnly, Instanced, Category=Costs)
|
||
TArray<TObjectPtr<ULyraAbilityCost>> AdditionalCosts;
|
||
|
||
// ShouldOnlyApplyCostOnHit - 远程武器未命中时不消耗弹药
|
||
```
|
||
|
||
#### 2.1.9 VerbMessage 广播模式
|
||
|
||
```cpp
|
||
// PostGameplayEffectExecute 中通过 GameplayMessageSubsystem 广播
|
||
UGameplayMessageSubsystem::BroadcastMessage(
|
||
TAG_Lyra_Damage_Message,
|
||
FLyraVerbMessage{Instigator, Target, Magnitude, Tags}
|
||
);
|
||
```
|
||
|
||
非耦合的伤害事件分发，UI/音频/统计系统各自监听。
|
||
|
||
### 2.2 GASShooter — 射击类 GAS 最佳实践
|
||
|
||
#### 2.2.1 EffectContainer 系统
|
||
|
||
```cpp
|
||
// GSAbilityTypes.h - 声明式 GE 映射
|
||
TMap<FGameplayTag, FGSGameplayEffectContainer> EffectContainerMap;
|
||
|
||
// 运行时应用流程：
|
||
// MakeEffectContainerSpec(Tag) -> TargetType::GetTargets() -> MakeEffectSpec
|
||
// ApplyEffectContainerSpec(Spec) -> K2_ApplyGameplayEffectSpecToTarget
|
||
```
|
||
|
||
将技能效果配置数据驱动化，蓝图设计师无需手动编写 GE 应用代码。
|
||
|
||
#### 2.2.2 武器作为能力授予者
|
||
|
||
```cpp
|
||
// AGSWeapon 实现 IAbilitySystemInterface
|
||
// bSourceObjectMustEqualCurrentWeaponToActivate 确保武器绑定
|
||
// 卸载武器时自动 ClearAbility
|
||
```
|
||
|
||
#### 2.2.3 弹药作为独立属性集
|
||
|
||
```cpp
|
||
// GSAmmoAttributeSet.h - 独立弹药属性集
|
||
UPROPERTY() FGameplayAttributeData RifleReserveAmmo;
|
||
UPROPERTY() FGameplayAttributeData MaxRifleReserveAmmo;
|
||
// GetReserveAmmoAttributeFromTag() - Tag 到属性的动态映射
|
||
```
|
||
|
||
#### 2.2.4 PreReplication 网络优化
|
||
|
||
```cpp
|
||
// 开火时禁用弹夹复制，减少带宽消耗
|
||
DOREPLIFETIME_ACTIVE_OVERRIDE(AGSWeapon, PrimaryClipAmmo, !bIsFiring);
|
||
```
|
||
|
||
### 2.3 UE5 GAS Aura — RPG 属性与 UI 设计
|
||
|
||
#### 2.3.1 三层属性体系
|
||
|
||
```
|
||
Primary（基础属性）
|
||
├── Strength → Physical Damage 加成
|
||
├── Intelligence → Magical Damage / Max Mana 加成
|
||
├── Resilience → Armor / ArmorPenetration 加成
|
||
└── Vigor → Max Health 加成
|
||
↓ (通过 MMC 公式派生)
|
||
Secondary（战斗属性）
|
||
├── Armor ← 防御
|
||
├── ArmorPenetration← 穿透
|
||
├── BlockChance ← 格挡
|
||
├── CriticalHitChance ← 暴击率
|
||
├── CriticalHitDamage ← 暴击伤害
|
||
├── CriticalHitResistance
|
||
└── MaxHealth / MaxMana (from Vital)
|
||
↓ (最终状态)
|
||
Vital（状态属性）
|
||
├── Health (当前生命，不可直接修改)
|
||
└── Mana (当前法力，不可直接修改)
|
||
```
|
||
|
||
#### 2.3.2 MMC 公式化属性派生
|
||
|
||
```cpp
|
||
// MMC_MaxHealth.cpp
|
||
float UAuraMMC_MaxHealth::CalculateBaseMagnitude_Implementation(...) const {
|
||
// Capture Vigor from Target
|
||
float Vigor = ...; float PlayerLevel = CombatInterface->GetPlayerLevel();
|
||
return 80.0f + 2.5f * Vigor + 10.0f * PlayerLevel;
|
||
}
|
||
```
|
||
|
||
通过 `ICombatInterface::GetPlayerLevel()` 统一等级接口，公式参数可进一步配置为 CurveTable。
|
||
|
||
#### 2.3.3 WidgetController MVC 架构
|
||
|
||
```
|
||
AuraHUD
|
||
└── 管理 WidgetController 生命周期
|
||
├── UOverlayWidgetController ← 战斗界面（血条/法力/消息）
|
||
└── UAttributeMenuWidgetController ← 属性菜单
|
||
|
||
UAuraWidgetController（基类）
|
||
├── FWidgetControllerParams（持有 ASC/AS/PC/PS）
|
||
├── BroadcastInitialValues() ← 初始化时推送数据
|
||
└── BindCallbacksToDependencies() ← 绑定属性变化回调
|
||
|
||
// BlueprintAssignable 委托驱动 Widget 更新
|
||
UPROPERTY(BlueprintAssignable) FOnAttributeChangedSignature OnHealthChanged;
|
||
UPROPERTY(BlueprintAssignable) FOnAttributeChangedSignature OnMaxHealthChanged;
|
||
```
|
||
|
||
#### 2.3.4 声明式 EffectActor
|
||
|
||
```cpp
|
||
// AuraEffectActor.h - 策略枚举控制 GE 应用
|
||
UPROPERTY(EditAnywhere) EEffectApplicationPolicy InstantEffectApplicationPolicy;
|
||
// ApplyOnOverlap / ApplyOnEndOverlap / DoNotApply
|
||
|
||
UPROPERTY(EditAnywhere) EEffectRemovalPolicy InfiniteEffectRemovalPolicy;
|
||
// RemoveOnEndOverlap / DoNotRemove
|
||
```
|
||
|
||
无需蓝图代码即可配置药水/Buff 区域/光环。
|
||
|
||
#### 2.3.5 集中式 Tag 管理
|
||
|
||
```cpp
|
||
// AuraGameplayTags.h - 单例原生 Tag 注册
|
||
struct FAuraGameplayTags {
|
||
static const FAuraGameplayTags& Get() { return GameplayTags; }
|
||
static void InitializeNativeGameplayTags();
|
||
FGameplayTag Attributes_Primary_Strength;
|
||
FGameplayTag InputTag_LMB, InputTag_RMB;
|
||
// ...所有 Tag 单点定义
|
||
};
|
||
```
|
||
|
||
避免跨项目 Tag 名称不一致和拼写错误。
|
||
|
||
#### 2.3.6 Tag-to-Attribute 运行时映射
|
||
|
||
```cpp
|
||
// AuraAttributeSet.h
|
||
TMap<FGameplayTag, TStaticFuncPtr<FGameplayAttribute()>> m_TagsToAttributes;
|
||
|
||
// 使用：根据 Tag 动态获取属性指针，O(1) 查找
|
||
// 用于 UI 属性菜单遍历所有属性
|
||
```
|
||
|
||
---
|
||
|
||
## 三、技术方案对比与借鉴决策
|
||
|
||
### 3.1 属性系统设计决策
|
||
|
||
| 方案 | 来源 | 优势 | 劣势 |
|
||
|------|------|------|------|
|
||
| 单一属性集 20 属性 | 当前 | 简单 | 上帝对象、游戏类型耦合 |
|
||
| 独立多属性集 | GASShooter | 职责清晰 | 需要 `GetAttributeSubobject` |
|
||
| **三层属性体系** | **Aura（推荐）** | **RPG 语义清晰、公式派生** | **初期设计工作量大** |
|
||
|
||
**决策**：采用 Aura 的三层体系思路，将现有 20 属性重组为：
|
||
- `URPGPrimaryAttributeSet`（基础属性：Strength/Intelligence/Vigor/Resilience）
|
||
- `URPGCombatAttributeSet`（战斗属性：Armor/Crit/Block + Damage/Healing 元属性）
|
||
- `URPGResourceAttributeSet`（资源：Health/Mana/Stamina/Shield + Max/Regen）
|
||
- `URPGProgressionAttributeSet`（进度：Level/XP/Gold，可选）
|
||
|
||
### 3.2 输入绑定设计决策
|
||
|
||
| 方案 | 来源 | 优势 | 劣势 |
|
||
|------|------|------|------|
|
||
| `EGSAbilityInputID` 枚举 | 当前 | 简单直接 | 游戏类型耦合、扩展困难 |
|
||
| **InputTag + DataAsset** | **Lyra（推荐）** | **完全解耦、数据驱动** | 需要 ProcessAbilityInput |
|
||
|
||
**决策**：
|
||
1. 移除 `EGSAbilityInputID` 枚举
|
||
2. 引入 `URPGInputConfig` DataAsset（`UInputAction` → `FGameplayTag` 映射）
|
||
3. ASC 实现 `AbilityInputTagPressed/Released/Held`
|
||
4. 实现帧级 `ProcessAbilityInput` 缓冲机制
|
||
|
||
### 3.3 UI 架构设计决策
|
||
|
||
| 方案 | 来源 | 特点 |
|
||
|------|------|------|
|
||
| BlueprintImplementableEvent | 当前 | 简单但耦合 |
|
||
| AsyncTaskAttributeChanged | 当前（工具层） | 轻量，适合简单 UI |
|
||
| **WidgetController MVC** | **Aura（推荐）** | **层次清晰，可测试** |
|
||
|
||
**决策**：引入 `URPGWidgetController` 基类体系，保留 `AsyncTaskAttributeChanged` 作为蓝图快速工具。
|
||
|
||
### 3.4 Cost 系统设计决策
|
||
|
||
**决策**：参考 Lyra 的 `ULyraAbilityCost` 模式，引入 `URPGAbilityCost` 抽象基类：
|
||
- `URPGAbilityCost_GameplayEffect`（标准 GE 费用）
|
||
- `URPGAbilityCost_Attribute`（直接扣属性）
|
||
- `URPGAbilityCost_TagStack`（Tag 栈计数，用于弹药/特殊资源）
|
||
|
||
---
|
||
|
||
## 四、重构方案设计
|
||
|
||
### 4.1 重构目标与原则
|
||
|
||
**设计原则**：
|
||
1. **向下兼容**：现有蓝图不应大规模失效，提供迁移路径
|
||
2. **游戏类型无关**：插件对 Shooter/ARPG/Fighter 均适用
|
||
3. **数据驱动**：策划可通过 DataAsset 配置，无需改代码
|
||
4. **可扩展**：新增能力类型/属性/Cost 无需修改基类
|
||
|
||
### 4.2 重构后架构总览
|
||
|
||
```
|
||
RPGGameplayAbility 插件（重构后）
|
||
│
|
||
├── Core/ [核心 GAS 基础设施]
|
||
│ ├── RPGAbilitySystemComponent 扩展 ASC（帧级输入缓冲、ActivationGroup）
|
||
│ ├── RPGAbilitySystemGlobals 全局配置（保留现有）
|
||
│ ├── RPGGameplayCueManager 按需加载（保留现有）
|
||
│ ├── RPGEngineSubsystem 启动初始化（保留现有）
|
||
│ └── RPGGameplayEffectContext 扩展 EffectContext（保留现有）
|
||
│
|
||
├── Abilities/ [能力层]
|
||
│ ├── RPGGameplayAbility 基类（ActivationPolicy/Group/AdditionalCosts）
|
||
│ ├── RPGAbilitySet 声明式授权 DataAsset
|
||
│ ├── RPGAbilityTagRelationshipMap Tag 互斥关系 DataAsset
|
||
│ └── RPGGlobalAbilitySystem 全局 Ability/GE 分发 WorldSubsystem
|
||
│
|
||
├── Attributes/ [属性层 - 三层体系]
|
||
│ ├── RPGAttributeSet 属性集基类（统一 Accessor 宏）
|
||
│ ├── RPGPrimaryAttributeSet 基础属性（4个，驱动派生）
|
||
│ ├── RPGCombatAttributeSet 战斗属性（含 Damage/Healing 元属性）
|
||
│ └── RPGResourceAttributeSet 资源属性（Health/Mana/Stamina）
|
||
│
|
||
├── Calculations/ [计算层]
|
||
│ ├── RPGDamageExecutionCalc 扩展（支持 CritHit/Block/Penetration）
|
||
│ └── RPGMMCBase MMC 基类（统一等级接口）
|
||
│
|
||
├── Costs/ [费用层 - 新增]
|
||
│ ├── RPGAbilityCost 抽象基类
|
||
│ ├── RPGAbilityCost_GameplayEffect GE 费用
|
||
│ └── RPGAbilityCost_TagStack Tag 栈费用（弹药）
|
||
│
|
||
├── Input/ [输入层 - 重构]
|
||
│ ├── RPGInputConfig DataAsset（InputAction ↔ InputTag）
|
||
│ └── RPGInputComponent EnhancedInputComponent 扩展
|
||
│
|
||
├── Tags/ [Tag 管理 - 新增]
|
||
│ └── RPGGameplayTags 集中式原生 Tag 单例
|
||
│
|
||
├── Target/ [目标层 - 保留]
|
||
│ ├── RPGTargetType 蓝图化目标策略
|
||
│ └── RPGGATA_Trace 追踪 TargetActor 系列
|
||
│
|
||
├── Tasks/ [任务层 - 保留 + 扩展]
|
||
│ └── (现有10个 Task + 新增连击Task)
|
||
│
|
||
├── UI/ [UI 层 - 扩展]
|
||
│ ├── RPGWidgetController WidgetController 基类（新增）
|
||
│ └── (现有 UI 组件保留)
|
||
│
|
||
└── Characters/ [角色层 - 整理]
|
||
├── RPGCharacterBase 基类（保留）
|
||
└── (游戏类型子类调整)
|
||
```
|
||
|
||
### 4.3 AttributeSet 拆分方案
|
||
|
||
#### 4.3.1 URPGAttributeSet（新基类）
|
||
|
||
```cpp
|
||
// 参考 Lyra：统一 Accessor 宏 + 统一委托
|
||
#define RPG_ATTRIBUTE_ACCESSORS(ClassName, PropertyName) \
|
||
GAMEPLAYATTRIBUTE_PROPERTY_GETTER(ClassName, PropertyName) \
|
||
GAMEPLAYATTRIBUTE_VALUE_GETTER(PropertyName) \
|
||
GAMEPLAYATTRIBUTE_VALUE_SETTER(PropertyName) \
|
||
GAMEPLAYATTRIBUTE_VALUE_INITTER(PropertyName)
|
||
|
||
DECLARE_MULTICAST_DELEGATE_SixParams(FRPGAttributeEvent,
|
||
AActor* EffectInstigator, AActor* EffectCauser,
|
||
const FGameplayEffectSpec* EffectSpec,
|
||
float EffectMagnitude, float OldValue, float NewValue);
|
||
```
|
||
|
||
#### 4.3.2 URPGPrimaryAttributeSet
|
||
|
||
```cpp
|
||
// 4 个基础属性，驱动 Secondary 属性的 MMC 计算
|
||
FGameplayAttributeData Strength; // 力量 → 物理伤害加成
|
||
FGameplayAttributeData Intelligence; // 智力 → 法术伤害 / MaxMana
|
||
FGameplayAttributeData Resilience; // 韧性 → 防御力 / 护甲穿透
|
||
FGameplayAttributeData Vigor; // 活力 → 最大生命值
|
||
```
|
||
|
||
#### 4.3.3 URPGCombatAttributeSet
|
||
|
||
```cpp
|
||
// 战斗属性（由 Primary 派生 + 元属性）
|
||
FGameplayAttributeData Armor; // 防御
|
||
FGameplayAttributeData ArmorPenetration; // 穿透
|
||
FGameplayAttributeData BlockChance; // 格挡率
|
||
FGameplayAttributeData CriticalHitChance; // 暴击率
|
||
FGameplayAttributeData CriticalHitDamage; // 暴击伤害倍率
|
||
FGameplayAttributeData CriticalHitResistance; // 暴击抵抗
|
||
|
||
// Meta 属性（不复制，仅服务器临时使用）
|
||
FGameplayAttributeData Damage; // 临时伤害值
|
||
FGameplayAttributeData Healing; // 临时治疗值
|
||
```
|
||
|
||
#### 4.3.4 URPGResourceAttributeSet
|
||
|
||
```cpp
|
||
// 资源属性（当前值 + 上限 + 恢复速率）
|
||
FGameplayAttributeData Health, MaxHealth, HealthRegenRate;
|
||
FGameplayAttributeData Mana, MaxMana, ManaRegenRate;
|
||
FGameplayAttributeData Stamina, MaxStamina, StaminaRegenRate;
|
||
FGameplayAttributeData Shield, MaxShield, ShieldRegenRate;
|
||
// Damage 元属性移至 CombatAttributeSet
|
||
// MoveSpeed 保留在此或独立
|
||
FGameplayAttributeData MoveSpeed;
|
||
```
|
||
|
||
#### 4.3.5 迁移路径
|
||
|
||
现有代码中大量使用 `URPGAttributeSetBase::GetHealth()` 等接口。重构后：
|
||
1. 保留 `URPGAttributeSetBase` 作为 `deprecated` 别名（临时）
|
||
2. 在 `ARPGCharacterBase` 中同时注册旧属性集和新属性集
|
||
3. 逐步将蓝图和 GE 引用迁移到新属性集
|
||
|
||
### 4.4 输入系统重构（Tag 驱动）
|
||
|
||
#### 4.4.1 移除 EGSAbilityInputID
|
||
|
||
```cpp
|
||
// 删除：EGSAbilityInputID 枚举
|
||
// 保留 Deprecated 版本一个版本周期用于迁移
|
||
|
||
// 新增：URPGInputConfig DataAsset
|
||
UCLASS()
|
||
class URPGInputConfig : public UDataAsset {
|
||
// InputAction -> InputTag 映射
|
||
TArray<FRPGInputAction> AbilityInputActions;
|
||
// 根据 InputAction 查找 InputTag
|
||
FGameplayTag FindAbilityInputTagForAction(const UInputAction* InputAction) const;
|
||
};
|
||
```
|
||
|
||
#### 4.4.2 ASC 输入接口扩展
|
||
|
||
```cpp
|
||
// URPGAbilitySystemComponent 新增
|
||
void AbilityInputTagPressed(const FGameplayTag& InputTag);
|
||
void AbilityInputTagReleased(const FGameplayTag& InputTag);
|
||
void AbilityInputTagHeld(const FGameplayTag& InputTag);
|
||
void ProcessAbilityInput(float DeltaTime, bool bGamePaused);
|
||
void ClearAbilityInput();
|
||
```
|
||
|
||
#### 4.4.3 帧级输入缓冲
|
||
|
||
```cpp
|
||
// 三个缓冲数组，每帧统一处理
|
||
TArray<FGameplayAbilitySpecHandle> InputPressedSpecHandles;
|
||
TArray<FGameplayAbilitySpecHandle> InputReleasedSpecHandles;
|
||
TArray<FGameplayAbilitySpecHandle> InputHeldSpecHandles;
|
||
```
|
||
|
||
### 4.5 Activation Policy + Activation Group 系统
|
||
|
||
```cpp
|
||
// RPGGameplayAbility.h 替换现有布尔值
|
||
UENUM(BlueprintType)
|
||
enum class ERPGAbilityActivationPolicy : uint8 {
|
||
OnInputTriggered, // 替代 bActivateOnInput
|
||
WhileInputActive, // 新增（自动武器/冲刺）
|
||
OnSpawn, // 替代 bActivateAbilityOnGranted（被动技能）
|
||
};
|
||
|
||
UENUM(BlueprintType)
|
||
enum class ERPGAbilityActivationGroup : uint8 {
|
||
Independent,
|
||
Exclusive_Replaceable, // 激活时取消同组，可被替换
|
||
Exclusive_Blocking, // 激活时取消同组，不可被替换
|
||
};
|
||
|
||
// 在 URPGGameplayAbility 中
|
||
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Ability")
|
||
ERPGAbilityActivationPolicy ActivationPolicy = ERPGAbilityActivationPolicy::OnInputTriggered;
|
||
|
||
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Ability")
|
||
ERPGAbilityActivationGroup ActivationGroup = ERPGAbilityActivationGroup::Independent;
|
||
```
|
||
|
||
**兼容性**：现有的 `bActivateAbilityOnGranted`、`bActivateOnInput` 保留为 `deprecated`，迁移完成后删除。
|
||
|
||
### 4.6 Tag Relationship Mapping 系统
|
||
|
||
```cpp
|
||
// URPGAbilityTagRelationshipMapping - DataAsset
|
||
USTRUCT()
|
||
struct FRPGAbilityTagRelationship {
|
||
FGameplayTag AbilityTag; // 被测试的 Ability Tag
|
||
FGameplayTagContainer AbilityTagsToBlock; // 阻断这些 Tag 的能力
|
||
FGameplayTagContainer AbilityTagsToCancel; // 取消这些 Tag 的能力
|
||
FGameplayTagContainer ActivationRequiredTags; // 需要这些 Tag 才能激活
|
||
FGameplayTagContainer ActivationBlockedTags; // 有这些 Tag 时无法激活
|
||
};
|
||
|
||
// ASC 中使用
|
||
UPROPERTY() TObjectPtr<URPGAbilityTagRelationshipMapping> TagRelationshipMapping;
|
||
```
|
||
|
||
**实际应用示例**：
|
||
- `Ability.Attack.Heavy` → `BlockTags: [Ability.Dodge]`（重击时无法翻滚）
|
||
- `Ability.Interact` → `BlockTags: [Ability.Attack.*]`（交互时禁止攻击）
|
||
- `Ability.Ultimate` → `RequiredTags: [Status.FullEnergy]`（蓄满才能放大招）
|
||
|
||
### 4.7 ExecCalc 扩展方案
|
||
|
||
```cpp
|
||
// RPGDamageExecutionCalc 扩展
|
||
// 输入：Source.BaseDamage + CriticalHitChance/Damage
|
||
// 输入：Target.Armor + ArmorPenetration + BlockChance + CritHitResistance
|
||
// 计算流程：
|
||
// 1. SetByCaller Damage 获取基础伤害
|
||
// 2. 计算暴击：Rand < (CritHitChance - CritHitResistance) -> CritDamage 倍率
|
||
// 3. 计算格挡：Rand < BlockChance -> 伤害减半
|
||
// 4. 计算护甲减免：EffectiveArmor = Armor * (1 - ArmorPenetration)
|
||
// MitigatedDamage = BaseDamage * (100 / (100 + EffectiveArmor))
|
||
// 5. 通过 DynamicAssetTag 标记 Crit/Block 用于 UI/音效
|
||
// 6. 写入 Target.Damage 元属性
|
||
```
|
||
|
||
**可配置化**：将 `1.5f`（爆头倍率）、`"b_head"`（骨骼名）、护甲公式系数移至 `UGameplayTagsProjectSettings` 或 `URPGCombatSettings` DataAsset。
|
||
|
||
### 4.8 WidgetController MVC 架构
|
||
|
||
```cpp
|
||
// URPGWidgetController - 新基类
|
||
UCLASS(BlueprintType, Blueprintable)
|
||
class URPGWidgetController : public UObject {
|
||
protected:
|
||
UPROPERTY() TObjectPtr<APlayerController> PlayerController;
|
||
UPROPERTY() TObjectPtr<APlayerState> PlayerState;
|
||
UPROPERTY() TObjectPtr<UAbilitySystemComponent> AbilitySystemComponent;
|
||
UPROPERTY() TObjectPtr<UAttributeSet> AttributeSet;
|
||
|
||
public:
|
||
virtual void BroadcastInitialValues() {}
|
||
virtual void BindCallbacksToDependencies() {}
|
||
void SetWidgetControllerParams(const FRPGWidgetControllerParams& Params);
|
||
};
|
||
|
||
// 具体子类（蓝图中配置委托绑定）
|
||
UCLASS() class URPGHUDWidgetController : public URPGWidgetController {
|
||
// OnHealthChanged / OnMaxHealthChanged / OnManaChanged / ...
|
||
// VerbMessage 监听（伤害数字、击杀通知）
|
||
};
|
||
|
||
UCLASS() class URPGAttributeMenuWidgetController : public URPGWidgetController {
|
||
// AttributeInfo DataAsset 驱动的属性菜单
|
||
// BroadcastAttributeInfo() 推送所有属性数据
|
||
};
|
||
```
|
||
|
||
### 4.9 集中式 Tag 管理
|
||
|
||
```cpp
|
||
// RPGGameplayTags.h
|
||
namespace RPGGameplayTags {
|
||
// Ability 激活失败原因
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Ability_ActivateFail_IsDead);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Ability_ActivateFail_Cooldown);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Ability_ActivateFail_Cost);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Ability_ActivateFail_TagsBlocked);
|
||
|
||
// 状态标签
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Status_Death);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Status_Death_Dying);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Status_Death_Dead);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Status_KnockedDown);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(Status_Interacting);
|
||
|
||
// 输入标签（通用）
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(InputTag_Jump);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(InputTag_Sprint);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(InputTag_Interact);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(InputTag_PrimaryAction);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(InputTag_SecondaryAction);
|
||
|
||
// SetByCaller
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(SetByCaller_Damage);
|
||
RPGGAMEPLAYABILITY_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(SetByCaller_Heal);
|
||
}
|
||
```
|
||
|
||
替换现有的 DataTable Tag 注册机制（或作为补充）。现有5个 DataTable（AbilityTags/DataTags/EffectTags/ObjectTags/StateTags）可保留用于蓝图 Tag 注册，C++ 关键 Tag 改用原生定义。
|
||
|
||
### 4.10 GlobalAbilitySystem 引入
|
||
|
||
```cpp
|
||
// URPGGlobalAbilitySystem : UWorldSubsystem
|
||
// 用途：全局 Buff/环境效果对所有角色生效
|
||
// 重生后自动重新应用全局效果
|
||
// 游戏模式可通过此系统广播全局技能/效果
|
||
```
|
||
|
||
---
|
||
|
||
## 五、新增功能建议
|
||
|
||
### 5.1 连击/输入缓冲系统（FighterGame 核心需求）
|
||
|
||
```cpp
|
||
// URPGComboManagerComponent - 新增组件
|
||
// 管理连击状态机：
|
||
// - 当前连击节点
|
||
// - 输入缓冲窗口（帧数）
|
||
// - 连击链定义（DataAsset）
|
||
// 与 RPGAT_PlayMontageAndWaitForEvent 配合：
|
||
// - 蒙太奇播放到"连击窗口"事件 → 检查输入缓冲 → 激活下一段
|
||
```
|
||
|
||
**设计参考**：UE5 的 `FInputBuffer` 或自定义 `TQueue<FGameplayTag>` 缓冲，配合 Activation Policy `Exclusive_Replaceable` 实现连击打断。
|
||
|
||
### 5.2 被动技能系统
|
||
|
||
已有 `bActivateAbilityOnGranted` 支持，重构后改为 `ActivationPolicy::OnSpawn`。扩展方向：
|
||
- **光环型被动**：持续 Infinite GE，通过 `URPGGlobalAbilitySystem` 可广播
|
||
- **触发型被动**：监听 GameplayEvent Tag 触发（如"受击时触发反伤"）
|
||
- **条件型被动**：基于 Tag 状态自动激活/失活
|
||
|
||
### 5.3 技能升级系统
|
||
|
||
```cpp
|
||
// URPGAbilityLevelComponent - 可选组件
|
||
// 管理每个 AbilitySpec 的等级
|
||
// AbilitySet 中声明 BaseLevel 和 MaxLevel
|
||
// 升级时：RemoveAbility -> GiveAbility(Level+1) 或直接修改 Spec.Level
|
||
|
||
// 或使用 Aura 模式：
|
||
// AbilitySpec.Level 直接与角色等级绑定（在 GiveAbility 时设置）
|
||
```
|
||
|
||
### 5.4 Buff/Debuff 可视化管理
|
||
|
||
```cpp
|
||
// 当前问题：ActiveGameplayEffects 存在 ASC 但无统一管理层
|
||
// 建议：URPGActiveEffectsComponent
|
||
// 提供：
|
||
// - GetActiveBuffs() / GetActiveDebuffs()（按 Tag 分类）
|
||
// - 持续时间/层数的 UI 数据推送（通过 WidgetController）
|
||
// - 效果到期/添加的 BlueprintAssignable 委托
|
||
```
|
||
|
||
---
|
||
|
||
## 六、重构实施计划
|
||
|
||
### 6.1 P0 — 立即修复（1-2 天）
|
||
|
||
| 任务 | 文件 | 操作 |
|
||
|------|------|------|
|
||
| 修复 PURE_VIRTUAL 类名错误 | `RPGGATA_Trace.h` | `AGSGATA_Trace` → `ARPGGATA_Trace` |
|
||
| 清理 GS 前缀枚举 | `RPGAbilityTypes.h` | `EGSAbilityInputID` → `ERPGAbilityInputID`（或废弃） |
|
||
| 清理 GS 前缀委托 | `RPGAT_PlayMontageForMeshAndWaitForEvent.h` | `FGS*` → `FRPG*` |
|
||
| 清理注释中的 GASShooter 引用 | 多文件 | 全局搜索替换 |
|
||
| 移除无用 include | `RPGAbilityTypes.h` | 删除未使用的 Task include |
|
||
|
||
### 6.2 P1 — 核心重构（1-2 周）
|
||
|
||
| 阶段 | 任务 | 优先级 |
|
||
|------|------|--------|
|
||
| 1.1 | 集中式 Tag 管理（`RPGGameplayTags.h`） | 高（其他重构依赖此） |
|
||
| 1.2 | 属性集拆分（Primary/Combat/Resource） | 高 |
|
||
| 1.3 | MMC 实现（MaxHealth/MaxMana 公式） | 中 |
|
||
| 1.4 | ActivationPolicy/Group 枚举引入 | 高 |
|
||
| 1.5 | ExecCalc 扩展（暴击/格挡/穿透） | 中 |
|
||
|
||
### 6.3 P2 — 架构升级（2-3 周）
|
||
|
||
| 阶段 | 任务 | 优先级 |
|
||
|------|------|--------|
|
||
| 2.1 | InputConfig DataAsset + Tag 驱动输入 | 高 |
|
||
| 2.2 | ProcessAbilityInput 帧级缓冲 | 高 |
|
||
| 2.3 | AbilitySet DataAsset | 中 |
|
||
| 2.4 | Tag Relationship Mapping | 中 |
|
||
| 2.5 | WidgetController MVC 基类 | 中 |
|
||
| 2.6 | AdditionalCosts 可扩展 Cost 系统 | 低 |
|
||
|
||
### 6.4 P3 — 新功能（持续迭代）
|
||
|
||
| 功能 | 预估时间 |
|
||
|------|---------|
|
||
| GlobalAbilitySystem | 3 天 |
|
||
| 连击/输入缓冲系统 | 1 周 |
|
||
| 技能升级系统 | 1 周 |
|
||
| Buff/Debuff 可视化管理 | 3 天 |
|
||
|
||
### 6.5 兼容性策略
|
||
|
||
1. **保留旧接口**：`bActivateAbilityOnGranted`、`bActivateOnInput` 保留 `UE_DEPRECATED` 一个版本
|
||
2. **渐进迁移**：旧属性集 `URPGAttributeSetBase` 保留为 `DEPRECATED`，指向新属性集组合
|
||
3. **单元测试**：重构每个子系统后立即编写 `.spec.cpp` 测试（至少覆盖 AttributeSet 的 Pre/PostGameplayEffectExecute）
|
||
|
||
---
|
||
|
||
## 七、命名规范
|
||
|
||
### 7.1 类命名
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| Ability 类 | `URPGGA_` | `URPGGA_PrimaryAttack`, `URPGGA_CharacterJump` |
|
||
| AbilityTask | `URPGAT_` | `URPGAT_PlayMontageAndWaitForEvent` |
|
||
| AttributeSet | `URPG` + 职责 + `AttributeSet` | `URPGResourceAttributeSet` |
|
||
| ExecutionCalc | `URPG` + 功能 + `ExecCalc` | `URPGDamageExecCalc` |
|
||
| MMC | `URPGMMC_` | `URPGMMC_MaxHealth` |
|
||
| TargetActor | `URPGGATA_` | `URPGGATA_LineTrace` |
|
||
| WidgetController | `URPG` + 用途 + `WidgetController` | `URPGHUDWidgetController` |
|
||
| DataAsset | `URPG` + 内容 | `URPGAbilitySet`, `URPGInputConfig` |
|
||
|
||
### 7.2 GameplayTag 命名规范
|
||
|
||
```
|
||
[Category].[SubCategory].[SpecificName]
|
||
|
||
# Ability 激活失败原因
|
||
Ability.ActivateFail.IsDead
|
||
Ability.ActivateFail.Cooldown
|
||
|
||
# 技能行为标记
|
||
Ability.Behavior.SurvivesDeath
|
||
Ability.Behavior.Passive
|
||
|
||
# 输入标签
|
||
Input.Jump
|
||
Input.Sprint
|
||
Input.PrimaryAction
|
||
Input.SecondaryAction
|
||
|
||
# 状态标签
|
||
Status.Death.Dying
|
||
Status.Death.Dead
|
||
Status.KnockedDown
|
||
Status.Interacting
|
||
|
||
# 效果类标签
|
||
Effect.Damage.CanCrit
|
||
Effect.Damage.Crit
|
||
Effect.Damage.Blocked
|
||
|
||
# SetByCaller
|
||
SetByCaller.Damage
|
||
SetByCaller.Heal
|
||
|
||
# 属性标签（用于 Tag-to-Attribute 映射）
|
||
Attribute.Primary.Strength
|
||
Attribute.Combat.Armor
|
||
Attribute.Resource.Health
|
||
```
|
||
|
||
### 7.3 文件组织
|
||
|
||
```
|
||
Source/RPGGameplayAbility/
|
||
├── Public/Core/ ASC/Globals/CueManager/EffectContext
|
||
├── Public/Abilities/ Ability 基类 + AbilitySet + Policy
|
||
├── Public/Attributes/ 三层属性集
|
||
├── Public/Calculations/ ExecCalc + MMC
|
||
├── Public/Costs/ Cost 基类 + 实现
|
||
├── Public/Input/ InputConfig + InputComponent
|
||
├── Public/Tags/ 集中式 Tag 定义
|
||
├── Public/Target/ TargetType + TargetActor
|
||
├── Public/Tasks/ AbilityTask
|
||
├── Public/UI/ WidgetController
|
||
├── Public/Characters/ 角色基类
|
||
└── Public/Interfaces/ 接口（Interactable/Combat/AbilitySource）
|
||
```
|
||
|
||
---
|
||
|
||
## 八、参考资料
|
||
|
||
- [GASDocumentation by tranek](https://github.com/tranek/GASDocumentation) - GAS 最全面文档
|
||
- [Lyra Starter Game Source](D:\MatrixTA\LyraStarterGame\Source) - Epic 官方最佳实践
|
||
- [GASShooter](D:\MatrixTA\GASShooter) - 多武器/网络预测参考
|
||
- [UE5 GAS Aura](D:\MatrixTA\UE5_GAS_Aura-main) - RPG 属性体系参考
|
||
- [现有插件](D:\MatrixTA\MusicFighterGame\Project\Plugins\RPGGameplayAbility) - 重构对象
|