Command Definition and Dispatch

This page focuses on configurable types and public entry points rather than the complete gameplay flow. Start with Command System to understand the path from player or AI intent to the execution layer. To integrate an AI Pawn, see Integrate a Minimal Commandable Unit.

UGAIS_CommandSystemComponent is a UPawnComponent, so its configuration and runtime state belong to a Pawn. Do not treat the payloads or queue APIs below as a general-purpose command framework for arbitrary Actors or Controllers.

`UGAIS_CommandSystemComponent`

The component owns the authoritative command entry point and replicated observable state. It does not retain a complete execution history or expose the internal state of execution backends. Project UI should use Current, Queue, Last, and the events to present command feedback.

State or event	Purpose	When to use it	Misconfiguration risk
`CommandState.CurrentCommand` / `GetCurrentCommandData`	Payload of the command currently being tracked.	HUDs, target indicators, and auxiliary StateTree reads.	A non-empty value does not guarantee visible behavior; also inspect the execution layer and latest result.
`CommandState.CommandQueue` / `GetCommandQueue`	Ordered projection of commands waiting behind the current command.	Displaying a Shift queue or debugging insertion order.	This is not permanent history; synchronous completion can make a newly accepted item leave the queue almost immediately.
`LastCommand`, `LastResultTag`, `LastReasonTag`	Most recently terminated command and its final result.	Failure messages and animation or UI feedback.	Only the latest result is retained, so this is not a complete audit trail.
`OnCommandChanged`	Fires after a CurrentCommand change is committed.	Refreshing the current target or button state.	Do not assume the previous execution layer has not yet received cancellation when the callback runs.
`OnCommandQueueChanged`	Fires when the waiting-queue projection changes.	Displaying queue order.	This is not an event for the task state of every execution backend.
`OnLastCommandResultChanged`	Fires when the latest terminal result changes.	Reporting success, failure, cancellation, and the reason.	When clients coalesce replicated updates, they observe only the latest result.

`FGAIS_CommandData`

This is the runtime payload that describes what a single request issues. Input, UI, scripts, network requests, and Tactical Assignment can construct it; CommandSystem then normalizes and validates it against the Definition's target contract.

Field	Purpose	When to set it	Misconfiguration risk
`Definition`	Command definition class.	Every request must provide a valid, non-abstract class.	A null class or unsupported asset is rejected.
`Index`	Array variant index for MultiVariant commands; normally ignored by Simple commands.	When selecting a specific MultiVariant configuration.	DebugName does not participate in selection; reordering the array changes the meaning of existing references.
`Target`	Actor target.	When the command's TargetType requires an Actor.	Supplying an Actor to a targetless or location command violates the target contract.
`bHasLocation` / `Location`	Explicit position or direction data.	For Location or Direction commands.	Filling in Location without setting `bHasLocation` does not create a valid location request.

Helpers such as MakeTargetless, MakeActorTarget, and MakeLocationTarget reduce manual payload errors, but their output must still match the Definition's TargetType.

`UGAIS_SimpleCommandDefinition`

Simple is the most common command asset base class: one saved default configuration describes one stable command. It suits Move, Interact, Heal, ordinary Attack, and similar capabilities that do not need several independent variants behind one entry point.

Configuration	Purpose	When to change it	Misconfiguration risk
`CommonData.CancellationPolicy`	Whether replacement requests may cancel the current command.	When designing interruption behavior.	Marking an uninterruptible charge as cancelable lets insertion or replacement break the intended gameplay.
`CommonData.TargetType`	Target shape that a request must provide.	When creating each command.	A mismatch with CommandData is rejected before execution.
`RequirementsData`	Source and Target tag requirements and success conditions.	When the command needs common state gates or faction/status restrictions.	Encoding complex spatial or project rules only as tags can produce rejections that are difficult to explain.
`DisplayData`	Name, description, icon, and fixed button slot.	When UI presents the command.	Correct display data does not mean the command has a valid Execution.
`ExecutionDefinition`	Stateless execution adapter selected by this command.	For every executable command.	An empty configuration prevents the request from starting; do not store per-execution state on this object.
`RequiredRange`	Expected distance between executor and target; 0 means no explicit requirement.	When StateTree or a project backend needs distance semantics.	It does not replace automatic movement or legality validation.
`AcquisitionRadius`	Distance scale used by default target scoring.	When automatic selection or tactical scoring needs a distance preference.	It does not gather candidates and is not the maximum attack range.
`bIsCreatingIndividualTargetLocations`	Whether group dispatch generates a separate destination for each unit.	Formation movement and spread-out deployment.	Unless enabled or overridden, every unit receives the same target point by default.

`UGAIS_MultiVariantCommandDefinition` and `Variants`

MultiVariant groups several stable choices under one command class. A variant's position in the Variants array is its runtime identity for FGAIS_CommandData.Index and command references; DebugName is only for editor and debug display.

Variant field	Purpose	When variants should differ	Misconfiguration risk
`DebugName`	Readable editor name.	Naming melee, ranged, skill, and other variants.	It cannot replace Index for runtime selection.
`Common`	Cancellation policy and target type for this variant.	When melee needs an Actor but dodge needs a Location, for example.	If variants behind one entry point have different target shapes, UI must construct the payload for the actual Index.
`Requirements`	Dispatch and success conditions for this variant.	When class, weapon, state, or target restrictions differ.	Omitting faction or resource rules can make a variant appear available but then be rejected.
`Display`	UI presentation for this variant.	When choices behind one entry need different descriptions or icons.	Display does not choose the execution backend.
`ExecutionDefinition`	Execution adapter for this variant.	When melee and ranged enter different StateTrees, or one variant uses an Ability.	Variants need not share an execution layer; an incorrect shared adapter can conflict with behavior and target rules.
`RequiredRange` / `AcquisitionRadius`	Distance semantics and scoring scale for this variant.	When melee, ranged, and support ranges differ.	Do not treat them as candidate collection or navigation-completion thresholds.

`UGAIS_CommandExecutionDefinition`

An execution definition is an inline, stateless adapter configuration. It receives a Context with the precise execution identity: StartExecution establishes an asynchronous route or reports synchronously, while CancelExecution releases external state still owned by that execution. Temporary tasks, subscriptions, and callbacks for one command belong to the backend runtime, not the Definition asset.

Entry or configuration	Purpose	When to use it	Misconfiguration risk
`StartExecution`	Starts the exact accepted execution.	Custom StateTree, Ability, Behavior Tree, or project backends.	Returning false or failing to establish completion reporting ends the command as a startup failure.
`CancelExecution`	Stops external state still owned by this execution.	Command replacement, cancellation, and EndPlay.	It must not cancel the replacement execution; clean up by Context identity.
`UGAIS_CommandExecutionDefinition_StateTree.StateTree`	Complete StateTree reference, including parameter and property overrides.	Most AI Pawn commands.	An invalid StateTree, a player-controlled Pawn, or a missing AIController or Stack causes the default backend to fail.

Request, queue, and cancellation entry points

These Blueprint entry points all have authoritative-server semantics. The client that owns a Pawn should call the corresponding Server... RPC; non-owning clients need a project network entry point to forward the request.

Entry	Purpose	Suitable use	Misconfiguration risk
`IssueCommand`	Starts or replaces immediately; if the current command cannot be canceled, retains one waiting replacement.	The latest player instruction or a forced scripted switch.	Clears existing waiting entries, so it is not appropriate for a Shift queue.
`EnqueueCommand`	Starts when idle; otherwise appends FIFO.	Waypoints and sequential interactions.	`Queued` means accepted, not that the item is guaranteed to remain in the queue after the call returns.
`InsertCommandAfterCurrentCommand`	Places a command at the front of the waiting queue without interrupting current execution.	A high-priority next step after the current action.	Does not preempt the current execution.
`InsertCommandBeforeCurrentCommand`	Cancels a cancelable current command and runs the new command first.	Emergency dodge and reactive actions.	Rejected when the current command is `NonCancelable`.
`CancelCommand`	Cancels the current command if it is cancelable.	Player stop requests and state changes.	Does not bypass `NonCancelable` protection.
`ClearCommandQueue`	Clears waiting entries only.	Removing appended waypoints while preserving current movement.	Does not stop current execution.
`ClearCommands`	Cancels the current command and clears waiting entries.	Abandoning the current plan completely.	Does not forcibly break a non-cancelable current command.
`CompleteCommandExecution`	Lets an execution backend report a terminal result.	When a custom backend completes, fails, or cancels.	It can report only for the current execution with an exact identity match.

Cancellation policy and request results

Type	Values	Design meaning
`EGAIS_CommandCancellationPolicy`	`Cancelable` / `NonCancelable`	Whether replacement and insertion may cancel the current command.
`EGAIS_CommandRequestResult`	`Rejected` / `NoChange` / `Started` / `Queued`	Whether the request made no state change because it was rejected or identical, started immediately, or entered the waiting queue.

Whether the queue continues after cancellation depends on the terminal result and the command's success criteria. Do not assume that Canceled always means either “continue” or “stop.”

Table of contents