Interfaces and custom instances

Decide whether you need to change “how the pawn answers combat questions,” “how a weapon or bullet instance moves and presents,” or “how targeting selects and filters.” Interfaces are the pawn-facing seam. Instance classes are the pool and collision seam. Targeting Tasks are the reusable seam inside a preset.

Related pages: weapon and targeting fields in Combo, weapon, and targeting, bullets and shapes in Trace and bullet definitions.

Decide whether to extend

Need	Is the default enough?	Extension entry
A normal sword, gun, or sphere bullet	Yes	`AGCS_WeaponActor` subclass + `AGCS_SphereBulletInstance` subclass
Odd-volume weapons, project death, custom aim	No built-in gameplay for those	Interfaces plus a custom shape or Targeting Task
Current target, current weapon, combo table	Project must implement	`IGCS_CombatEntityInterface`
Affiliation filtering	The component already replicates TeamId	`UGCS_CombatTeamAgentComponent`

A good custom case: an opening umbrella shield uses a custom FGCS_CollisionShape that follows the canopy socket; a death processor calls StartDeath / FinishDeath to disable collision, drop weapons, and ragdoll; aim uses a Filter Task that drops “not lockable” targets.

A case the default already covers: a sword uses the default weapon Actor (Trace definitions + combo table), and shots use a Blueprint subclass of AGCS_SphereBulletInstance that only swaps Niagara and FGCS_BulletDefinition. Do not reimplement IGCS_BulletInterface just to fly a sphere.

`IGCS_CombatEntityInterface`

The contract for a combat participant. The function library finds implementers with GetCombatEntity. Combo Ability, the IsDead filter, and bullet requests that read a lock all go through here.

Entry	What it can change	When the default is enough
`GetCombatTargetActor` / `GetCombatTargetObject`	The current lock and the locked component. Usually forwarded to the targeting component.	The pawn has a targeting component and returns `GetTargetedActor`.
`GetComboDefinitionTable`	The combo table. Return null when the actor has no data-driven combo.	A single weapon with a table on the pawn. Multiple weapons should return the table on `GetCurrentWeapon`.
`QueryAbilityActionsByContext`	Pick `FGCS_AbilityAction` rows from a context (often the weapon) and tags.	The pawn holds one `UGCS_AbilityActionSetSettings` DataAsset.
`QueryWeapon` / `GetCurrentWeapon` / `SetCurrentWeapon`	Find a weapon by query; mark which weapon the next move uses. `SetCurrentWeapon` is not a swap flow — it only marks primary / secondary.	Only one weapon is active.
`Set/GetRotationMode`, `MovementSet`, `MovementState`	Face-target, ADS, walk/jog.	Movement already listens to input and combat does not change stance yet.
`StartDeath` / `FinishDeath` / `IsDead`	Death lifetime. IsDead feeds the FilterTask.	Still return false when you have no death rules, so the filter does not lie.
`GetMovementIntent`	Movement input direction.	Combos do not need “launch along input.”
`GetRelativeTransformToSocket`	Align a weapon mesh or bullet spawn pose to a socket.	Attach sockets are already correct on the skeleton.

A Blueprint pawn or component can implement this. A missing GetComboDefinitionTable Errors inside Combo Ability. A missing IsDead means the death filter never filters.

`IGCS_WeaponInterface`

Contract for an object that acts as a weapon. The combat entity resolves it through Query / GetCurrentWeapon. The default implementation is Abstract AGCS_WeaponActor.

Entry	What it can change	When the default is enough
`GetWeaponOwner` / `GetWeaponTags` / `GetPrimitiveComponent`	Owner, tags, and the mesh used for traces.	The owner has a `WeaponMesh` tag. Override the lookup when the mesh lives on the weapon Actor.
`SetWeaponActive` / `IsWeaponActive`	Draw / holster, replicated.	The replicated bool is enough. Still call `RefreshTraceInstance` after activate.
`GCS_GetTargetingStartTransform`	Weapon-side origin for ranged requests.	`WeaponForward` / `WeaponTowardsFocus` can use the default muzzle.
`GCS_ToggleTargeting` / `ToggleTrail`	Aim toggle; visual trail. Trail is not collision.	No ADS optic or blade-trail mesh.

A good custom case: an odd-volume weapon overrides GetSourceComponentForTrace so different TraceTags bind to canopy and shield shapes. A default sword only fills TraceDefinitions.

`IGCS_BulletInterface` and instances

Pooled Actors managed by UGCS_BulletSystemComponent must implement this interface. The system owns BulletId, EntryId, pooling, and authoritative hits. The instance provides presentation and movement. ValidateAttackRequest is a component hook for fire-rate or resource checks, not an interface method.

Order is fixed: OnBulletBeginPlay → OnBulletLaunch → OnBulletHit on every accepted hit → OnBulletExplosionPending when a terminal hit waits → OnBulletEndPlay → OnBulletReset on recycle. No latent work after Reset; the instance may be reused immediately.

AGCS_BulletInstance (Abstract, NotBlueprintable) already implements the bullet interface, IGCS_EffectCauserInterface, and IGCS_TraceCauserInterface, and spawns FX/SFX from the definition. AGCS_SphereBulletInstance (Abstract, Blueprintable) adds a sphere collision and is the default ammo type. Subclass the sphere instance in Blueprint. Do not implement the interface from scratch.

OnSyncBulletState copies native FGCS_BulletState onto the instance (distance traveled, gravity scale, explosion deadline). Filter hits with CanHandleHitResult. To change registration rules, override CreateBulletHitContext on UGCS_BulletSystemComponent and call the parent first so shared-hit and cooldown stay intact.

`IGCS_TargetingSourceInterface`

Extra Trace data for Targeting Selection Tasks. GCS:SelectionTask (Trace) / (Trace Bind Shape) expect SourceObject to implement it.

Entry	Use
`GetTraceLevel`	`FScalableFloat::GetValueAtLevel` for length and shape.
`GetTraceDirection` / `GetSweptTraceRotation`	Aim direction and capsule / box rotation.
`GetTraceShape`	ShapeComponent bound by the Bind Shape task.
`GetAdditionalActorsToIgnore`	Extra ignore list.

Implement it when an ability or weapon is the SourceObject. A reticle line with no level scaling can stay on GCS:SelectionTask (Line Trace). Custom on UGCS_AttackRequest_Bullet requires overriding GetTargetingTransform on the request, which is a different seam.

`IGCS_TraceCauserInterface`

Contract for a dynamic Trace source (bullet or weapon).

Entry	Use
`GetTraceDefinitions`	Definitions supplied at runtime. A bullet row’s `TraceDefinitions` override the instance.
`GetTraceShapeComponent`	Component that drives shape and transform. The sphere bullet returns Sphere.
`CanHandleHitResult`	Filter before the causer registers a hit.

The default sphere bullet already implements this. Swap the Shape here for a custom-volume bullet instead of writing sweeps in an ability.

`IGCS_EffectCauserInterface`

Applies a prepared GE / EffectContainer to TargetData after a hit. Bullet instances must keep the combat EffectContext so Combat Flow can build an authoritative result. SetEffectSpec / SetEffectContainerSpec are written by the bullet component during authoritative SetupGameplayEffects; the hit calls ApplyEffectToTargetData. Predicted bullets must not take this Apply path.

Traps and lingering weapons can implement it too. Do not skip the attack-definition handle.

`IGCS_CombatTeamAgentInterface`

Team affiliation. Default UGCS_CombatTeamAgentComponent replicates FGenericTeamId and can copy it to the Controller. SetCombatTeamId is authority-only. The Affiliation filter asks this interface first, then IGenericTeamAgentInterface. Change teams through SetCombatTeamId so OnTeamIdChangedEvent can notify UI. Do not write a local, unreplicated faction field. Custom filters should still honor bDisableAffiliationCheck.

Custom shapes and Targeting Tasks

You can subclass FGCS_CollisionShape and implement InitializeShape, GetTransform, and GetDynamicCollisionShape. Pick that struct in a weapon or bullet CollisionShape instance. That fits a canopy or an irregular edge. Fists and blades can stay on built-in Static / Socket Based. If InitializeShape fails, a handle may still exist while the sweep volume degrades.

For custom aim, subclass UTargetingTask (Selection or UTargetingFilterTask_BasicFilterTemplate) and replace or append it in the TargetingPreset. Built-in Line Trace / Trace / Bind Shape plus Tags / IsDead / Affiliation already cover reticle, volume, and team. Put project death rules on the entity’s IsDead. Do not write another filter just to “not lock corpses.”

Failure signals: a bullet class that does not implement the interface, or is still Abstract, never leaves the pool. When default weapon mesh lookup fails on the owner, Refresh Errors and traces never register. A SourceObject without TargetingSource makes the extended Trace task silently use default length and direction.

Verify

Default sword: after activate, Debugger Trace shows handles; a swing produces an Attack Result.
Default sphere bullet: the authority hit produces a Result; the client has trajectory and FX only.
Custom death: after the Death processor runs, IsDead is true and Affiliation / IsDead filters no longer lock that actor.
Custom aim: after the preset uses the project filter, actors tagged “not lockable” disappear from PotentialTargets.

Table of contents