Combo, weapon, and targeting

This page covers how a combo table picks a move, how a weapon Actor carries traces and a table, and how targeting and team IDs replicate. Concepts are in Combos, weapons, and the combat entity and Targeting and teams. Steps are in Configure combo and weapon.

`FGCS_ComboDefinition`

A Data Table row. On the locally controlled machine, UGCS_ComboAbility walks the table from the combat entity’s GetComboDefinitionTable(), filters by current ComboStep, event tag, tag queries, and an optional activation test, then TryActivateAbility on the first matching row. The table comes from the combat entity, not from the combo ability itself.

Lifecycle: a weapon or pawn implements GetComboDefinitionTable → input becomes a Gameplay Event → StartCombo / AdvanceCombo → SelectComboDefinition → activate the child ability and UpdateComboStep. When the child ends with no next step, ResetCombo clears the step to zero.

Field	Purpose	When to change	Misconfiguration
`AbilityClass`	Soft-referenced ability activated when the row wins.	One ability class per step.	A null row is skipped. A class not granted on the ASC (with a matching SourceObject) is also skipped.
`bResetComboStep`	When selected, reset the step toward the opener. Takes effect only when `MinComboStep > 0` and this is not a step-0 start.	A finisher or loop move inside a string.	Ticking it on an opener (`MinComboStep == 0`) does nothing.
`MinComboStep`	Step gate. `0` is eligible only at step 0. Non-reset rows are skipped once the current step exceeds this value.	Write 1 and 2 for the second and third hits.	If every row is 0, nothing is eligible after the step advances.
`EventTag`	When set, the incoming event tag must match exactly.	Light / heavy use different rows.	A mismatched input event tag permanently skips the row.
`EventInstigatorTagQuery`	When set, the event’s `InstigatorTags` must match.	The same key branches on instigator state.	A bad query makes the row always fail.
`TagQuery`	When set, the owner ASC’s current tags must match.	Weapon drawn, stance, buff gates.	Missing ASC tags skip the row and the string looks “broken.”
`bRunActivationTest`	Run `CanActivateAbility` before selecting the row.	Do not spend the step when cost fails.	The test reads a granted spec. Ungranted classes are skipped earlier as “missing.”
`bAbortIfActivationTestFailed`	Abort the whole combo on a failed test instead of trying the next row. Shown only when `bRunActivationTest` is on.	This step is the only legal follow-up.	A single cost failure Resets and never tries a fallback row.
`NativeExtension` / `Extension`	C++ / Blueprint extension. `CanSelectedComboDefinition` can read it.	Extra filter by current weapon tags.	Filling Extension without overriding the hook does not change selection.

DevDescription is editor-only. Selection runs on the locally controlled machine. The step replicates through the combat component.

`AGCS_WeaponActor`

Default Actor implementation of IGCS_WeaponInterface. Abstract; subclass it. bWeaponActive replicates. On activate, the project should call RefreshTraceInstance, which adds traces from TraceDefinitions on the owning pawn’s UGCS_TraceSystemComponent and uses the weapon as SourceObject. Default GetPrimitiveComponent looks up a mesh on the owner by WeaponMeshTagName, not on the weapon Actor itself.

Field	Purpose	When to change	Misconfiguration
`WeaponTags`	Weapon tags. Also implements `IGameplayTagAssetInterface`.	Primary / secondary, sword / gun.	`QueryWeapon` cannot find the weapon if the query does not match.
`TraceDefinitions`	Traces created while the weapon is active.	Blade, guard.	Invalid definitions fail `IsDataValid`. A missing Trace component makes Refresh log a Warning only.
`WeaponMeshTagName`	Mesh lookup tag. Default `WeaponMesh`.	The owner has a Primitive tagged this way.	If the tag lives only on the weapon Actor, the default returns null and traces never register. Override `GetPrimitiveComponent` / `GetSourceComponentForTrace`.
`bGiveAbilitiesFromComboDefinitionTable`	Authoring intent: grant abilities listed in the table with this weapon. Default true.	Equip-and-grant combo children.	The native Actor does not grant in BeginPlay. Granting belongs on the combat entity, inventory, or a project subclass. Ticking the bool does not add specs to the ASC.
`ComboDefinitionTable`	Combo table associated with this weapon.	One table per weapon.	`UGCS_ComboAbility` reads `IGCS_CombatEntityInterface::GetComboDefinitionTable()`. The entity should return this table for the current weapon, or selection logs “No combo definition table.”
`bWeaponActive`	Active state. Authority writes it through `SetWeaponActive` and replicates it.	Draw / holster.	Default `OnWeaponActiveStateChanged` only broadcasts. It does not call `RefreshTraceInstance`. Refresh after activate, or the weapon is in hand with no hitbox.

TraceHandles is a VisibleInstanceOnly runtime array. GCS_GetTargetingStartTransform, GCS_ToggleTargeting, and ToggleTrail are interface hooks: the first two feed bullet requests as a weapon-side origin or aim toggle; ToggleTrail is presentation only, not a collision Trace.

`UGCS_TargetingSystemComponent`

Lock-on and candidate collection. The owner is the Targeting SourceActor; the component is the SourceObject. TargetedActor replicates COND_OwnerOnly. Authority also pushes ClientSetTargetedActor; AutonomousProxy requests with ServerSetTargetedActor. PotentialTargets is not replicated and refreshes locally on Authority and AutonomousProxy. Combat code usually reads the same lock through GetCombatTargetActor.

Field	Purpose	When to change	Misconfiguration
`TargetingPreset`	Preset that gathers and filters candidates.	Lock cone, range, affiliation.	An empty preset makes `RefreshPotentialTargets` return no candidates, so `SearchForActorToTarget` idles.
`bAutoUpdatePotentialTargets`	Refresh candidates while ticking. Default true.	Lock-on UI that must stay current.	When off, call `RefreshPotentialTargets` / `SearchForActorToTarget` yourself. A dead lock will not clear unless you refresh.
`bUseAsyncTargeting`	Start targeting requests asynchronously. Default true.	Turn off to debug synchronously.	Reading `PotentialTargets` before an async request finishes can show the previous frame.

CanBeTargeted can be overridden. StaticSwitchToNewTarget steps left or right through candidates. Bullet GetTargetActor and emitter TargetingSystem may read this lock. Do not treat a SimulatedProxy write to TargetedActor as an authoritative lock.

Team: `FGenericTeamId`

UGCS_CombatTeamAgentComponent implements IGCS_CombatTeamAgentInterface and replicates CombatTeamId. SetCombatTeamId is authority-only. bAssignTeamIdToController defaults to true: the authority also copies the ID onto the owning Controller when that controller implements a team interface. GCS:FilterTask (Affiliation) looks at the CombatTeam interface first, then GenericTeam. TeamId 255 means unassigned; the filter ignores unassigned targets by default. For debug cross-team hits, use UGCS_DeveloperSettings::bDisableAffiliationCheck. Do not rewrite team IDs in shipping config.

Built-in Targeting Tasks

Add these by display name in a TargetingPreset Selection / Filter list.

Display name	Class	Role	When to use	Misconfiguration
`GCS:SelectionTask (Line Trace)`	`UGCS_TargetingSelectionTask_LineTrace`	Sync or async line trace up to the first blocking hit. Optionally writes a default HitResult at the end.	A line down the reticle.	Collision Profile does not work for async traces.
`GCS:SelectionTask (Trace)`	`UGCS_TargetingSelectionTask_TraceExt`	Extends engine Trace Selection. Reads `IGCS_TargetingSourceInterface` from SourceObject (level, direction, ignore list).	An ability supplies aim direction or level-scales length.	Without that interface on SourceObject, extra data stays at defaults.
`GCS:SelectionTask (Trace Bind Shape)`	`UGCS_TargetingSelectionTask_TraceExt_BindShape`	Reads radius / half-height / box from a bound ShapeComponent, then None/Add/Multiply with the task defaults.	The lock volume should follow a collision shape on the pawn.	Missing shape falls back, so the lock range does not match the visible volume.
`GCS:FilterTask (TagsRequirements)`	`UGCS_TargetingFilterTask_TagsRequirements`	Keep targets that match a TagQuery (`bInvert` flips it). Can fall back to `IGameplayTagAssetInterface`.	Only “lockable” or “elite.”	An empty query filters nothing.
`GCS:FilterTask (IsDead)`	`UGCS_TargetingFilterTask_IsDead`	Drops targets whose combat entity `IsDead()` is true. No interface means no filter.	Corpses should not stay locked.	Without `IsDead`, dead actors remain on the list.
`GCS:FilterTask (Affiliation)`	`UGCS_TargetingFilterTask_Affiliation`	Filters enemy / friend / neutral with `FAISenseAffiliationFilter`.	Lock enemies, not teammates.	Developer Settings affiliation-off lets this filter pass everyone.

Custom shapes or tasks are in Interfaces and custom instances. Combo advance hooks are in Processors and combat hooks.

Table of contents