reznok/gmcabilitysystem/gmas-task

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 GMAS task is how an ability waits for something, or carries a value the owning client knows into the move so the server sees the same value in the same move. Tasks live in Public/Ability/Tasks/ (paths below are relative to Source/GMCAbilitySystem/). How an ability is built and where its own hooks run: gmas:gmas-ability; the rules on bound state and replay that every task inherits: gmas:gmas-rules, gmas:gmc-prediction.

What a task is

UGMCAbilityTaskBase (Public/Ability/Tasks/GMCAbilityTaskBase.h) is a UGameplayTask whose owner (IGameplayTaskOwnerInterface) is the UGMCAbility and whose tasks component is the ability's UGMC_AbilitySystemComponent (the ASC derives from UGameplayTasksComponent). Create it with the class's static factory (NewAbilityTask<T>(OwningAbility) inside), bind the delegate pins, then call ReadyForActivation(); Blueprint async nodes do the last step for you. OnGameplayTaskInitialized on the ability fills Ability and AbilitySystemComponent before Activate runs.

Client and server halves. Each side runs the ability's code and so creates its own instance of every task. Nothing about the task object is replicated; what crosses is the payload. QueueTaskData(const FInstancedStruct&) appends to QueuedTaskData; the ASC's PreLocalMoveExecution moves the oldest one (FIFO, 1.4+; LIFO before) into the bound TaskData slot (ClientAuth_Input, CombineIfUnchanged), so it rides the next move's input and reaches the server with it. On both machines SendTaskDataToActiveAbility hands the slot to UGMCAbility::HandleTaskData → ProgressTask on the task with that TaskID: in the prediction tick for abilities with bActivateOnMovementTick = true (replayed with the move), in the ancillary tick for the others; the slot is cleared at the end of the ancillary tick. One payload per move: N queued payloads take N moves. A payload for a TaskID this side never issued is dropped with a [TaskDiag] ... never issued on this side warning (1.4+): the sign that the two sides created different tasks. 1.4.1+: a payload whose struct is not an FGMCAbilityTaskData is dropped with one Error at dispatch, before any task sees it.

Heartbeat watchdog. From AncillaryTick, every live task on a client sends RPCTaskHeartbeat(AbilityID, TaskID) (Server, Reliable) once per HeartbeatInterval = 1 s of real time (FPlatformTime::Seconds(), 1.4+; 0.2 s of ActionTimer before). On a dedicated or listen server, for a remotely controlled pawn, the twin checks the age of its last stamp: more than HeartbeatMaxInterval = 3 s and it logs [TaskHeartbeat] Timeout: cancelling ability ... (Error, LogGMCAbilitySystem, 1.4.1+), broadcasts the ASC's OnTaskTimeout(AbilityTag), calls Ability->CancelAbility() (no end event, no chain window; CancelAbilityEvent runs) and ends itself; RPCClientEndAbility then cancels the client instance. On 1.4.0 it logged Server Task Heartbeat Timeout on LogGMCReplication plus the dump on LogTemp and called EndAbility(), the natural end. Activation seeds the stamp one interval ahead, so the first kill comes no sooner than about 6 s after the task started. Finished tasks neither send nor check (1.4+); locally controlled server pawns do neither. A task that exists on the server only is killed this way after 6 s; one that exists on the client only beats a TaskID the server never issued ([TaskDiag] Heartbeat for TaskID=... never issued, 1.4+). The watchdog covers only abilities with a live task: an ability whose tasks all ended but that never calls EndAbility runs unwatched, and the server logs [TaskDiag] Ability task-less for N s and still active at Verbose after 6 s (1.4+).

Ending. EndTask() (engine) moves the task to Finished and calls OnDestroy(false); TickTasks skips finished tasks (1.4+; before, every entry stayed registered and ticked). When the ability ends it calls EndTaskGMAS() on everything still in RunningTasks, after logging [AbilityCut] Ability ending with N unfinished task(s) (Warning, 1.4+) if any task had not completed: an ability that ends normally has no running tasks left.

Built-in tasks as models

Every factory takes UGMCAbility* OwningAbility first (omitted below); Blueprint shows the display names ("Wait For Input Key Press"), C++ uses the factory names in the second column.

Patterns the built-ins show:

• Local wait (WaitDelay, montage, yaw): read bound state and ActionTimer in Tick, complete on both sides independently. No payload, no network cost, replay-exact.
• Owner-known value (SetTargetData*, input tasks): only the owning machine has the fact; ClientProgressTask sends it, ProgressTask completes both twins in the same move. The input tasks are the model for a wait that ends on such a fact; SetTargetData* for a value computed at activation.
• Deterministic timeout (input tasks, 1.4+): MaxDuration is compared against ActionTimer - StartTime; the owner queues the payload when it crosses the limit, and OnTaskCompleted re-derives TimedOut from the payload move's ActionTimer so both sides pick the same pin even when the crossing and the payload land in one server frame.
• Replay-safe input poll: the input tasks read the live key state only where DrivesPawnLocally() and not while IsReplayingForGMASLogic(); the legitimate completion is already in the move history as a payload. 1.4.1+ for all three; on 1.4.0 only WaitForInputKeyRelease had the replay guard.

Writing a wait task

UMyTask_WaitUntilGrounded completes when the pawn's movement component reports ground contact, or times out. It completes locally: both sides see the same bound state in the same move.

// MyTask_WaitUntilGrounded.h
#pragma once
#include "Ability/Tasks/GMCAbilityTaskBase.h"
#include "MyTask_WaitUntilGrounded.generated.h"
 
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FMyWaitUntilGroundedPin, float, Duration);