接口与自定义实例

先判断要改的是“角色对外怎么被问到”“武器/子弹实例怎么运动和表现”，还是“瞄准怎么选、怎么滤”。接口是问角色的缝；实例类是对象池和碰撞的缝；Targeting Task 是预设里可复用的缝。

相关文档：武器与瞄准字段见连击、武器与目标，子弹与形状见 Trace 与子弹定义。

先判断要不要扩展

需求	默认是否足够	扩展入口
普通刀、枪、球形弹	足够	`AGCS_WeaponActor` 子类 + `AGCS_SphereBulletInstance` 子类
特殊体积武器、项目死亡、自定义瞄准	默认没有这些玩法	接口 + 自定义形状或 Targeting Task
当前目标、当前武器、连击表	必须项目实现	`IGCS_CombatEntityInterface`
阵营过滤	组件已复制 TeamId	`UGCS_CombatTeamAgentComponent`

适合自定义的案例：一把张开的伞盾用自定义 FGCS_CollisionShape 跟随伞面 Socket；死亡 Processor 调 StartDeath / FinishDeath 关碰撞、丢武器、进 ragdoll；瞄准用自写 Filter Task 丢掉“不可锁定”标签的目标。

默认已经够用的案例：刀用默认武器 Actor（Trace 定义 + 连击表），子弹用 AGCS_SphereBulletInstance 蓝图子类，只改 Niagara 和 FGCS_BulletDefinition。不必为“会飞的球”再实现一遍 IGCS_BulletInterface。

`IGCS_CombatEntityInterface`

战斗参与者的总契约。函数库用 GetCombatEntity 查找实现者。Combo Ability、IsDead 过滤、子弹请求取锁定目标，都走这里。

入口	能改变什么	默认已经够用的情况
`GetCombatTargetActor` / `GetCombatTargetObject`	当前锁和锁到的组件。通常转给 Targeting 组件。	角色上挂了 Targeting 组件并直接返回 `GetTargetedActor`。
`GetComboDefinitionTable`	连击表。没有连击就返回空。	单一武器、表固定在角色上。多武器时应返回 `GetCurrentWeapon` 上的表。
`QueryAbilityActionsByContext`	按上下文（常为武器）和标签选出 `FGCS_AbilityAction`。	角色只持一份 `UGCS_AbilityActionSetSettings` DataAsset。
`QueryWeapon` / `GetCurrentWeapon` / `SetCurrentWeapon`	按 Query 找武器；标记“下一招用哪把”。`SetCurrentWeapon` 不是切枪流程，只标记主/副手。	身上只有一把激活武器。
`Set/GetRotationMode`、`MovementSet`、`MovementState`	面向目标、ADS、走跑。	运动层自己听输入，战斗暂时不改姿态。
`StartDeath` / `FinishDeath` / `IsDead`	死亡生命周期。IsDead 给 FilterTask 用。	没有死亡规则时仍应返回 false，避免过滤器误伤。
`GetMovementIntent`	移动输入方向。	连击不需要“朝输入方向位移”。
`GetRelativeTransformToSocket`	把武器网格或子弹生成姿态对齐到 Socket。	挂点已经在骨骼上对好。

蓝图角色或组件都可以实现。缺 GetComboDefinitionTable 时 Combo Ability 会 Error。缺 IsDead 时死亡过滤器不过滤。

`IGCS_WeaponInterface`

武器对象契约。战斗实体用 Query / GetCurrentWeapon 解析。默认实现是 Abstract 的 AGCS_WeaponActor。

入口	能改变什么	默认已经够用的情况
`GetWeaponOwner` / `GetWeaponTags` / `GetPrimitiveComponent`	所属者、标签、Trace 用的网格。	所属者身上有 `WeaponMesh` Tag。网格在武器 Actor 本地时覆写查找。
`SetWeaponActive` / `IsWeaponActive`	抽出/收起，复制。	默认复制布尔值。激活后仍要 `RefreshTraceInstance`。
`GCS_GetTargetingStartTransform`	远程请求的武器侧原点。	`WeaponForward` / `WeaponTowardsFocus` 用默认枪口。
`GCS_ToggleTargeting` / `ToggleTrail`	瞄准开关；视觉拖尾。Trail 不是碰撞。	没有 ADS 镜或刀光网格。

适合自定义的案例：特殊体积武器覆写 GetSourceComponentForTrace，让不同 TraceTag 绑到伞面、盾面两个 Shape。默认刀只需填 TraceDefinitions。

`IGCS_BulletInterface` 与实例

UGCS_BulletSystemComponent 管理的对象池 Actor 必须实现此接口。系统拥有 BulletId、EntryId、对象池和权威命中；实例提供表现和运动。ValidateAttackRequest 是组件上拦截射速或资源的入口，不是接口方法。

顺序固定：OnBulletBeginPlay → OnBulletLaunch → 每次接受命中 OnBulletHit → 终止命中若有延迟则 OnBulletExplosionPending → 回收时 OnBulletEndPlay → OnBulletReset。Reset 之后不允许潜时操作，实例可能立刻复用。

AGCS_BulletInstance（Abstract、NotBlueprintable）已实现子弹接口、IGCS_EffectCauserInterface 和 IGCS_TraceCauserInterface，并自动创建定义里的 FX/SFX。AGCS_SphereBulletInstance（Abstract、Blueprintable）加上球形碰撞，作为默认弹种。蓝图请派生球形实例，不要从零实现接口。

OnSyncBulletState 把原生 FGCS_BulletState 同步进实例（已飞距离、重力系数、爆炸倒计时）。命中过滤走 CanHandleHitResult；要改登记规则时，在 UGCS_BulletSystemComponent 覆写 CreateBulletHitContext，并先调父实现以保留共享命中和冷却。

`IGCS_TargetingSourceInterface`

给 Targeting Selection Task 提供额外 Trace 数据。GCS:SelectionTask (Trace) / (Trace Bind Shape) 要求 SourceObject 实现它。

入口	用途
`GetTraceLevel`	`FScalableFloat::GetValueAtLevel` 算长度和形状。
`GetTraceDirection` / `GetSweptTraceRotation`	方向和胶囊/盒体旋转。
`GetTraceShape`	Bind Shape Task 绑定的 ShapeComponent。
`GetAdditionalActorsToIgnore`	额外忽略列表。

技能或武器作为 SourceObject 时实现它。只做准星直线、不需要等级缩放时，用 GCS:SelectionTask (Line Trace) 即可。UGCS_AttackRequest_Bullet 的 Custom 瞄准源要求覆写 GetTargetingTransform，那是请求上的缝，不是本接口。

`IGCS_TraceCauserInterface`

动态 Trace 来源（子弹、武器）的契约。

入口	用途
`GetTraceDefinitions`	运行时提供定义。子弹定义的 `TraceDefinitions` 会覆盖实例。
`GetTraceShapeComponent`	驱动形状与变换的组件。球形弹返回 Sphere。
`CanHandleHitResult`	登记命中前过滤。

默认球形弹已经实现。自定义体积弹在这里换 Shape，而不是在 Ability 里手写 Sweep。

`IGCS_EffectCauserInterface`

命中后把预先构建的 GE / EffectContainer 应用到 TargetData。子弹实例必须保留战斗 EffectContext，供 Combat Flow 产出权威结果。SetEffectSpec / SetEffectContainerSpec 由子弹组件在权威端 SetupGameplayEffects 时写入；命中时 ApplyEffectToTargetData。预测弹不得走这条 Apply。

陷阱、武器残留也可以实现它，但不要绕过攻击定义句柄。

`IGCS_CombatTeamAgentInterface`

队伍归属。默认组件 UGCS_CombatTeamAgentComponent 复制 FGenericTeamId，并可写到 Controller。SetCombatTeamId 仅权威。Affiliation Filter 先问本接口，再问 IGenericTeamAgentInterface。换阵营时走 SetCombatTeamId，让 OnTeamIdChangedEvent 通知 UI；不要只改一个未复制的本地变量。自写 Filter 仍应尊重 bDisableAffiliationCheck。

自定义形状与 Targeting Task

FGCS_CollisionShape 可再派生：实现 InitializeShape、GetTransform、GetDynamicCollisionShape。武器或子弹的 CollisionShape Instanced 字段选你的结构。适合伞面、不规则刃；拳头和刀刃用内置 Static / Socket Based 即可。InitializeShape 失败时句柄可能还在，Sweep 体积会退化。

自定义瞄准：派生 UTargetingTask（Selection 或 UTargetingFilterTask_BasicFilterTemplate），在 TargetingPreset 里替换或追加。内置 Line Trace / Trace / Bind Shape 以及 Tags / IsDead / Affiliation 已覆盖准星、体积和阵营。项目死亡规则放在实体的 IsDead，不要为“死人别锁”再写一个过滤器。

失败信号：子弹类未实现接口或仍是 Abstract，对象池取不出实例。武器默认网格查找在所属者上失败时，Refresh 打 Error，Trace 加不进去。SourceObject 没有 TargetingSource 接口时，扩展 Trace Task 静默使用默认长度和方向。

验证

默认刀：激活后 Debugger 的 Trace 段出现句柄；挥砍能进 Attack Result。
默认球形弹：权威命中出 Result，客户端只有弹道和 FX。
自定义死亡：Death Processor 调用后 IsDead 为真，Affiliation / IsDead 过滤器不再锁该目标。
自定义瞄准：Preset 换上项目 Filter 后，带“不可锁定”标签的演员从 PotentialTargets 消失。

目录