reznok/gmcabilitysystem/gmas-ability

Behavior below was verified against GMC 2.3.x and GMAS 1.4. Confirm signatures in this project's own headers (paths are relative to each plugin's root, e.g. Source/GMCCore/Public/Components/GMCReplicationComponent.h); GMC's source is not part of this plugin.

A UGMCAbility (Public/Ability/GMCAbility.h) is a UObject the UGMC_AbilitySystemComponent ("the ASC") instantiates per activation and ticks from inside the pawn's GMC move: on the owning client (predicted, replayed) and on the server (re-executed). It owns no replicated state; what it changes lives in bound attributes and tags (gmas:gmas-rules), through effects (gmas:gmas-effect). The first ability and the movement-component wiring are in gmas:gmas-setup; GMC's move cycle in gmas:gmc-prediction; task authoring in gmas:gmas-task. Six worked abilities: references/recipes.md; the cosmetics API: references/cosmetics.md. GMAS paths below are relative to Source/GMCAbilitySystem/.

Anatomy

Identity and cost:

Activation gates, evaluated on the class default object before an instance exists:

Blocking and cancelling (all hierarchical on the other ability's AbilityTag):

Chains and end hooks (1.4+, category Chain):

Ticking and network:

Lifecycle

1. Activation (TryActivateAbility, ASC): instance gate, tag gates, NewObject from the class, Execute(ASC, AbilityID, InputAction) sets the owner, AbilityInputAction, ClientStartTime = ActionTimer and calls PreBeginAbility(). The instance is added to ActiveAbilities even when it already ended; the server confirms the client only when it did not.
2. `PreBeginAbility()`: cooldown → cost (CanAffordAbilityCost(), 1.4.1+) → PreExecuteCheckEvent() → BlockedByOtherAbility → IsAbilityTagBlocked. Each refusal logs at Verbose (Ability Activation for Ability.Dash Stopped By Cooldown / Stopped By Cost / ...) and refuses the activation (the press is consumed). Then (1.4.1+) AbilityState = Initialized, the OnAbilityActivated broadcast (the listener sees IsActive() true; a listener that calls CancelAbility() on it refuses the activation there: no cooldown, no BeginAbilityEvent, the cancel hooks fire), then BeginAbility(). On 1.4.0 cost was not checked and OnAbilityActivated fired from BeginAbility before Initialized. Keep PreExecuteCheckEvent cheap and pure: it runs on both sides inside the move.
3. `BeginAbility()`: BlockOtherAbilitiesQuery, chain consume, cooldown commit (bApplyCooldownAtAbilityBegin), CancelConflictingAbilities(), then `BeginAbilityEvent()`: your code. Override the events, not PreBeginAbility / BeginAbility / EndAbility, so the bookkeeping stays. An override of BeginAbility whose work after Super creates tasks, declares effects or commits a cost must stop when the ability ended inside Super: Super::BeginAbility(); if (AbilityState == EAbilityState::Ended) { return; }.
4. `Tick(DeltaTime)` (prediction tick, after the ASC processed the move's operation and before effects tick and attributes recalculate): confirm timeout (client), pending cancel or end, TickTasks, then `TickEvent`. `AncillaryTick` (ancillary tick, after cooldown expiry and task-payload dispatch): AncillaryTickTasks, then `AncillaryTickEvent`. Predicted movement goes in TickEvent; once-only work in AncillaryTickEvent or behind the live-move guard below.
5. `EndAbility()` is the natural end: chain window applied, FinishEndAbility(), `EndAbilityEvent()`, OnAbilityEnded. `CancelAbility()` is the abnormal end: FinishEndAbility(), then (1.4.1+) `CancelAbilityEvent()` (BlueprintNativeEvent) and the ASC's OnAbilityCancelled; no end event, no OnAbilityEnded, no chain window. Cleanup that must run on both paths (stop a loop, hide a cosmetic) implements both events. First end wins (1.4.1+): the two share one latch, so a CancelAbility() during a natural end, or an EndAbility() during a cancel, is ignored and exactly one hook set fires.
6. `FinishEndAbility()` (both paths, once): [AbilityCut] warning if tasks are unfinished, every task ended (EndTaskGMAS), every declared effect removed (by id, or by cached EffectTag if a replay renumbered it, [EffectLeak]), ApplyEffectOnEnd / RemoveEffectOnEnd (only for an ability that began, 1.4.1+), AbilityState = Ended. The ASC purges ended instances at the end of its next prediction tick (CleanupStaleAbilities; the server also sends RPCClientEndAbility).
7. Ending from outside (1.4.1+): every abnormal or external end cancels. CancelAbilitiesByTag(Tag) and CancelAbilitiesByQuery(Query) (pending cancel, next tick), CancelAbilitiesWithTag, EndOtherAbilitiesQuery, BlockOtherAbilitiesQuery, an effect's CancelAbilityOnActivation / CancelAbilityOnEnd and EndAbilityOn*Query, the client confirm timeout, the server's RPCClientEndAbility ([AbilityCut] warning) and the task heartbeat watchdog (server, 3 s without a client heartbeat) all call CancelAbility(). EndAbilitiesByTag(Tag), EndAbilitiesByClass(Class) and EndAbilitiesByQuery(Query) (pending end) keep the natural end for callers that mean it (a death handler ending a held ability). The By* calls return how many live instances they reached (already-ended, unpurged ones are skipped). On 1.4.0 every one of these paths was a natural end; an ability that must not open its window on interruption detected it itself and called CancelAbility().

Cost and cooldown calls: