14 调试、优化与最佳实践

目标：掌握生产级技能系统的调试工具链（showdebug/GameplayDebugger/日志）、核心优化手段（Ability Batching、Cue Batching、复制模式、属性代理、ASC 懒加载）、常见问题排查、设计模式与 Dave Ratti 的经验总结，以及不同项目类型下的架构选择。

14.1 调试工具

14.1.1 showdebug abilitysystem（最重要）

在游戏控制台输入 showdebug abilitysystem 开启屏幕调试。三页信息：

页面	内容	切换命令
第一页	所有属性的 `CurrentValue`、当前 GameplayTags	`AbilitySystem.Debug.NextCategory`
第二页	所有 Duration/Infinite GE、堆叠数、标签、Modifier	同上
第三页	所有已授予的 GA、运行状态、阻塞状态、AbilityTask 状态	同上

切换调试目标：

PageUp / NextDebugTarget：下一个目标；
PageDown / PreviousDebugTarget：上一个目标。

配置要求（否则无法切换目标）：

; DefaultGame.ini
[/Script/GameplayAbilities.AbilitySystemGlobals]
bUseDebugTargetFromHud=true

常见陷阱：showdebug abilitysystem 需要 GameMode 中设置了实际的 HUD 类，否则返回 "Unknown Command"。

14.1.2 Gameplay Debugger

按 '（撇号键）打开 Gameplay Debugger，按数字键 3 启用 Abilities 分类。

与 showdebug 的区别：

showdebug 查看自己的属性、GE、GA；
Gameplay Debugger 查看其他角色的标签、GE、GA（不包括属性值）。

目标是屏幕中央的 Character，可按 ' 重新选择目标。

14.1.3 GAS 日志系统

GAS 源码包含大量 ABILITY_LOG() 语句，默认不显示详细信息。

log LogAbilitySystem VeryVerbose     # 开启详细日志
log LogAbilitySystem Display         # 重置默认
log list                             # 显示所有日志类别

GAS 相关日志类别：

日志类别	默认级别	说明
`LogAbilitySystem`	Display	GAS 核心日志
`LogAbilitySystemComponent`	Log	ASC 相关日志
`LogGameplayCueDetails`	Log	GameplayCue 详细日志
`LogGameplayCueTranslator`	Display	GC 翻译器日志
`LogGameplayEffectDetails`	Log	GE 详细日志
`LogGameplayEffects`	Display	GE 核心日志
`LogGameplayTags`	Log	标签日志
`LogGameplayTasks`	Log	AbilityTask 日志
`VLogAbilitySystem`	Display	可视化日志（VLog）

14.1.4 UE_DISABLE_OPTIMIZATION 调试宏

UE 会优化 C++ 代码，导致断点不命中、变量无法查看。临时禁用优化：

UE_DISABLE_OPTIMIZATION
void MyClass::MyHardToDebugFunction(int32 MyParameter)
{
    // 现在可以正常设置断点和查看变量了
}
UE_ENABLE_OPTIMIZATION

注意：调试完成后必须移除这些宏！不应用于生产代码。对插件代码无效（除非从源码重新编译插件）。

14.2 优化策略

14.2.1 Ability Batching（能力批处理）

问题：一个射击能力需要三个 RPC——激活、发送 TargetData、结束能力。

优化：将这些合并为一个 RPC。适用于一帧内完成的能力（射击、使用道具）。

// 在自定义 ASC 中启用并批处理
virtual bool ShouldDoServerAbilityRPCBatch() const override { return true; }

bool UMyASC::BatchRPCTryActivateAbility(FGameplayAbilitySpecHandle Handle, bool EndImmediately)
{
    bool Activated = false;
    if (Handle.IsValid())
    {
        FScopedServerAbilityRPCBatcher Batcher(this, Handle);   // 作用域内 RPC 合并
        Activated = TryActivateAbility(Handle, true);
        if (EndImmediately)
        {
            if (FGameplayAbilitySpec* Spec = FindAbilitySpecFromHandle(Handle))
                Cast<UMyGameplayAbility>(Spec->GetPrimaryInstance())->ExternalEndAbility();
        }
    }
    return Activated;
}

半自动武器：激活 + TargetData + 结束 → 1 个 RPC；
全自动武器：第一发合并（1 个），后续每发独立 TargetData RPC，停止时独立 EndAbility RPC；
调试日志：AbilitySystem.ServerRPCBatching.Log 1。

14.2.2 Gameplay Cue Batching（GC 批处理）

每个 GameplayCue 是一个不可靠的 NetMulticast RPC。高频触发时产生大量 RPC。

优化方法：

使用本地 GameplayCue：投射物命中、近战碰撞等使用本地触发，完全避免 RPC（第 08 章 8.6）；
使用 FScopedGameplayCueSendContext：将多个 GC 合并为一个 RPC；
配置 AbilitySystem.AlwaysConvertGESpecToGCParams=1：将 GE Spec 转换为更轻量的参数。

14.2.3 ASC 复制模式优化

默认 Full 模式把所有 GE 复制到所有客户端，多人效率极低。

推荐配置：

玩家控制 Pawn ASC → Mixed：GE 只复制给拥有者客户端；标签和 GC 复制给所有人；
AI 控制 Pawn ASC → Minimal：GE 不复制给任何人；标签和 GC 复制给所有人。

// 玩家角色
AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Mixed);
// AI 角色
AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Minimal);

14.2.4 属性代理复制（Fortnite 大逃杀方案）

100 人大厅中，每个玩家的 ASC 在 PlayerState（always-relevant）上，直接复制大量属性带宽爆炸。

Fortnite 方案：

在模拟代理上禁用 ASC 的直接复制；
用代理结构体在 Pawn 上复制属性的子集；
客户端收到代理数据后推送到本地 ASC。

// 概念代码：模拟代理跳过 ASC 复制
void AFortnitePlayerState::ReplicateSubobjects(...)
{
    if (bIsSimulatedProxy) return;   // 不复制 ASC
    Super::ReplicateSubobjects(...);
}

// Pawn 上的代理结构体（位掩码压缩白名单标签）
USTRUCT()
struct FAttributeProxy
{
    GENERATED_BODY()
    UPROPERTY(Replicated) float Health;
    UPROPERTY(Replicated) float Shield;
    UPROPERTY(Replicated) float MaxHealth;
    UPROPERTY(Replicated) uint32 TagBitmask;
};

Dave Ratti 评价："不确定在 Replication Graph 等优化后是否仍必要，且不是最可维护的模式。"优先考虑 Replication Graph，而非手工代理复制。

14.2.5 ASC 懒加载（Fortnite 方案）

大逃杀有大量可破坏 Actor（树木、建筑），每个都挂 ASC 成本高。FNBR 优化为只在首次受伤时才创建 ASC：

void AMyDamageableActor::TakeDamage(float Damage, ...)
{
    if (!AbilitySystemComponent)   // 首次受伤才创建
    {
        AbilitySystemComponent = NewObject<UAbilitySystemComponent>(this);
        AbilitySystemComponent->RegisterComponent();
        // 初始化属性集等
    }
    // 应用伤害 GE
}

14.3 常见问题排查速查（详见第 15 章）

问题	根因	快速解决
"Can't activate LocalOnly or LocalPredicted ability when not local!"	客户端的 ASC 未正确初始化	`PossessedBy`（服务端）+ `OnRep_PlayerState`（客户端）都调 `InitAbilityActorInfo`
ScriptStructCache 错误断线	未调 `InitGlobalData()`（仅 4.24~5.2）	`UAssetManager::StartInitialLoading()` 中调用；5.3+ 自动
动画蒙太奇不复制	用了 `PlayMontage` 而非 Task	用 `PlayMontageAndWait`（经 ASC 复制蒙太奇）
复制蓝图 Actor 后 AttributeSet 为 nullptr	引擎 Bug（UE-81109）	`PostInitializeComponents()` 中用 `AddSet<T>()`，不在头文件声明指针
MarkPropertyDirty 链接错误 LNK2019	`WITH_PUSH_MODEL` 定义不一致	`Build.cs` 加 `NetCore` 模块
枚举名路径警告 C4996	`FGameplayAbilityInputBinds` 用 FString 枚举名	改用 `FTopLevelAssetPath`

14.4 最佳实践总结

14.4.1 冷却系统设计选择

方案	优点	缺点	适用场景
Cooldown GE	GAS 原生支持，简单	高延迟玩家射速劣势	冷却较长技能（>1s）
自定义计时器	无延迟问题	需要手动实现	射击武器、快速冷却
混合方案	灵活	复杂度高	大型项目

14.4.2 伤害系统设计模式（推荐流水线）

1. GA 激活 → 检查 Cost/Cooldown
2. 应用 Cost GE（预测性扣除资源）
3. 执行 TargetActor / 射线检测
4. 创建 Damage GE Spec
   - SetByCaller 设置基础伤害
   - EffectContext 携带命中信息
5. 服务器端 ExecCalc 计算最终伤害
   - 读取 SetByCaller 基础伤害
   - 捕获 Source 的攻击属性
   - 捕获 Target 的防御属性
   - 计算暴击、穿透、元素克制
   - 输出到 Meta Attribute (Damage)
6. AttributeSet 的 PostGameplayEffectExecute
   - 从 Damage Meta Attribute 分配到 Health/Shield
   - 触发死亡逻辑
7. GameplayCue 播放表现效果

14.4.3 属性设计原则

使用 Meta Attribute 分离逻辑：伤害（Damage）作 Meta，生命值（Health）作实际属性；
合理规划属性数量：不需要的属性不创建，但预留逻辑"槽位"可以；
属性命名规范：层级命名 Vital.Health、Vital.Mana、Combat.AttackPower。

14.4.4 标签命名规范

State.           → 状态标签（State.Debuff.Stun、State.Buff.Shield）
Ability.         → 能力标签（Ability.Skill.Fireball）
Cooldown.        → 冷却标签（Cooldown.Skill.Fireball）
Data.            → 数据标签（Data.Damage、Data.Heal）
GameplayCue.     → 表现标签（GameplayCue.Hit.Fire）
Effect.          → 效果标签（Effect.Damage.Lifesteal）
Input.           → 输入标签（Enhanced Input 映射）
Event.           → 事件标签（Event.MeleeHit）

14.5 Dave Ratti Q&A 精华（GAS 核心开发者）

预测系统未来

移除 Prediction Key：改用 NetworkPrediction frames；
统一预测框架：与 CharacterMovement 整合；
GE 移除预测：长期目标，尚未解决所有边界情况；
冷却延迟问题：计划通过 GE reconciliation 解决（吃掉部分服务器端 GE 时间）。

Epic 内部的经验教训

做对了：标签驱动设计（GameplayTags）、表现层分离（GameplayCues）、属性捕获机制。

需改进：

GE 与数据表的紧耦合（应参数化）；
能力策略过多（应减少 ReplicationPolicy、InstancingPolicy 的数量）；
缺少"中间层"构建块（过滤 GE 容器、重叠卷支持）；
样板代码过多（应提供可选的开箱即用模块）。

Dave Ratti: "I would like to move GameplayCues to a separate module that is not coupled with the ability system."

14.6 不同项目类型的架构选择

场景一：大型多人游戏（100 人大逃杀）优化清单

□ ASC 复制模式：玩家 Mixed、AI Minimal
□ 属性代理复制 / Replication Graph（模拟代理跳过 ASC 直接复制）
□ ASC 懒加载（环境物体首次受伤才创建）
□ GameplayCue 优化：本地 GC、按需异步加载、FScopedGameplayCueSendContext 批处理
□ Ability Batching：射击能力合并为 1 个 RPC
□ 冷却系统：武器用自定义计时器（不用 GE）；技能用 Cooldown GE
□ 日志调试：Shipping 禁用详细日志、可视化日志 VLog

场景二：单人 RPG 最佳实践

□ ASC 位置：Character（无需跨重生持久化），角色和装备共享一个 ASC（AbilitySet 管理）
□ 复制模式：Full（简单）
□ 伤害系统：ExecCalc + Meta Attribute，元素克制/护甲穿透/暴击全在 ExecCalc
□ 属性系统：Derived Attribute（MMC/Infinite GE）+ CurveTable 等级缩放
□ 冷却系统：全部 Cooldown GE（单人无延迟问题）
□ 技能设计：GE Container 简化目标选择、Blueprint AsyncTask 显示冷却

场景三：射击游戏架构选择

□ 武器系统：射击冷却用自定义计时器、弹药 Plain Floats 或 AttributeSet
□ 伤害系统：ExecCalc，不预测伤害（Epic 建议）
□ 目标系统：射线 Instant TargetActor / 投射物 EffectContext / AOE GroundTrace
□ 表现层：命中特效本地 GameplayCue、射击动画预测播放、武器音效本地触发
□ 网络优化：射击 Ability Batching、霰弹枪 GC 批处理、ASC Mixed

14.7 本章验证

[ ] 配置 showdebug abilitysystem，验证三页信息与目标切换；
[ ] 将射击能力改用 Ability Batching，对比优化前后 RPC 数量；
[ ] 给 AI 角色设 Minimal 复制模式，验证 GE 不再复制到客户端；
[ ] 实现一个 Blueprint AsyncTask 监听冷却变化并在 UMG 显示；
[ ] 用 Unreal Insights 找一次高帧耗时的 GE/Cue 并优化；
[ ] 分析 Dave Ratti Q&A，总结三个对项目最有价值的建议。

下一章：15 常见问题与排错手册