做一次近战攻击

本篇做出最小近战：一份攻击定义、一条 Trace，窗口打开时 Sweep 命中目标，再用 UGCS_CombatFunctionLibrary 把攻击定义写入 Effect Context 并应用 Gameplay Effect。目标身上的 Combat Flow 会收成 Attack Result。

相关文档：Flow 还没有 Result 时先看注册第一条攻击结果；请求模型见攻击定义与请求；窗口行为见 Trace 与命中窗口。

前置条件

已按挂上战斗组件挂好 UGCS_CombatSystemComponent 与 UGCS_TraceSystemComponent，并实现战斗实体接口。目标 Flow 已能按注册第一条攻击结果从属性回调注册 Result。
权威端已 InitializeAbilitySystem。
准备一个会改目标属性的瞬时 Gameplay Effect。需要本地预测反馈时，给该 Effect 加上 UGCS_GEComponent_PredictivelyExecute。
攻击者和目标的碰撞通道能互相扫到。

1. 写攻击定义

新建 Data Table，行结构选 GCS Attack Definition（FGCS_AttackDefinition）。填一行：

AttackTags：例如近战、轻击。这些标签会作为动态 AssetTags 进 Effect Spec。
TargetEffectClass：上一步的瞬时 GE。需要多条效果时再填 TargetEffectContainer，两者有效时各自应用。
击退、Cue、Extension 本篇可留空。

保存后记下这一行的 Data Table 句柄，后面 UGCS_AttackRequest_Melee 要指向它。

2. 写 Trace 定义

再建一张 Data Table，行结构选 FGCS_TraceDefinition：

TraceTag：窗口里用来开关这条 Trace 的标识。
CollisionShape：先用静态球或胶囊，半径覆盖武器挥砍范围即可。
SweepSetting：通道、对象类型或 Profile 必须和目标碰撞一致。默认同通道 Visibility 经常扫不到角色胶囊。

把该 TraceTag 写进近战请求的 TracesToControl。Task 调用 StartTraces 时只启动容器里列出的标签。

3. 填近战请求

创建或在 Notify 里嵌入 UGCS_AttackRequest_Melee：

字段	本篇填法
`AttackDefinitionHandle`	指向第 1 步的攻击定义行
`TracesToControl`	放入第 2 步的 `TraceTag`

请求只描述“这一窗打什么、开哪些 Trace”。它不是运行时执行器。

4. 用 Task 打开窗口

在战斗 Ability 里：

调用 HandleCollisionTraces 得到 UGCS_AbilityTask_CollisionTrace。
窗口开始时 AddMeleeRequest(Request, SourceObject)。SourceObject 可以是武器或角色，用来关联 Trace Handle。
绑定 OnTargetsFound。命中后用 UGCS_CombatFunctionLibrary 把 AttackDefinitionHandle 写入 Effect Context（Set Attack Definition Handle 或 AddAttackHandleToGameplayEffectSpec），再对目标应用 GE。
窗口结束时 RemoveMeleeRequest。Task 销毁时也会停掉仍挂着的 Trace。

动画窗口可以在 Montage 上放 GCS_ANS_AttackTrace，把同一份 Melee Request 填进 Notify。Notify 只存请求，Collision Trace Task 仍要读取并 AddMeleeRequest。只配 ANS、不启动 Task，Sweep 不会跑。

预期结果

窗口打开后，Debugger Trace 段出现对应 Handle 且为激活。扫到目标时 OnTargetsFound 触发；应用带攻击句柄的 GE 后，目标 Attack Result 段出现最近一条结果。

验证

PIE 打开 Gameplay Debugger Combat 分类：Shared 段已有 Combat 组件；打出一击后 Trace 段能看到句柄和激活状态。
Attack Result 段出现最近结果，并能看到是否预测、是否已复制。
对 Effect Context 调用 Get Attack Definition Handle，能读回本篇填的行。
LogGCS_Trace / LogGCS_Combat 提到 Verbose，能看到 Sweep 与结算。
多人 PIE 先看服务器是否产生 Result，再看 AutonomousProxy 的 LocalPredicted Processor 是否只跑一次。

常见失败

现象	先查
有动画没有命中	Trace 组件是否存在；ANS 是否只是数据容器而 Task 没启动；`AddMeleeRequest` 是否在窗口内调用
Task 警告 No any trace started	`TracesToControl` 是否和 Trace 表的 `TraceTag` 一致；`SourceObject` 是否有效
Sweep 打空	`SweepSetting` 通道/对象类型是否对上目标碰撞；形状半径是否太小
Effect 没有攻击上下文	是否用 CombatFunctionLibrary 写入句柄；Globals 是否为 GGA
窗口从未打开	`RemoveMeleeRequest` 过早，或 Ability 在 Notify 开始前就结束

下一步

近战闭环通了再接做一次远程攻击，或按配置连击与武器把这一击放进连击表。排错见调试与排错。

目录