Troubleshooting Flows

Troubleshooting Flows

GAIS issues are usually not isolated failures. More often, a request was not handed off from one layer to the next: input was not converted into a command, the command was not accepted by CommandSystem, the Command layer did not take control, a Queue task never completed, Tactical Assignment failed to resolve a command, or the squad/formation layer produced an intent that the project movement layer never consumed. Troubleshooting by narrowing the failure down stage by stage is more reliable than changing assets, Blueprints, and StateTrees at the same time.

Related documentation: start with GameplayDebugger to locate the runtime state, then use the Parameter Reference to verify field values. For formation and Movement Intent troubleshooting, see Formation Editor and Slot Diagnostics.

Command Does Not Enter Current

Symptom: after calling Issue Command, CommandSystem Current in GameplayDebugger remains None, and Last does not contain a useful result.

Check the following first:

1. Confirm that the commanded object is a Pawn/Character and that the Pawn has a UGAIS_CommandSystemComponent.
2. Confirm that FGAIS_CommandData.Definition is valid.
3. Confirm that the Index for a MultiVariant command is valid.
4. Confirm that the command TargetType matches Target, bHasLocation, and Location.
5. Confirm whether CanObeyCommand returns missing, blocking, or error tags.
6. Confirm that a command requiring server/authority handling was not issued directly from the client.

Do not modify the StateTree first. If the command never enters Current, the execution layer has not started yet.

Command Enters Current but the Unit Does Not Move

Symptom: CommandSystem Current contains a command, but the character does nothing, or the corresponding task does not appear in Stack/Queue.

Check the following first:

1. In the Stack panel, confirm that RequestedLayer selects Command and that AppliedLayer has completed the transition.
2. Confirm that the command's GetExecutionDefinition returns a valid execution configuration.
3. When using a StateTree execution configuration, confirm that the Command-layer StateTree Schema, Blackboard keys, and command context match.
4. In the Queue panel, check CurrentTask, PendingTask, and the latest failure reason.
5. Confirm that the project's movement, GAS, Ability, or custom execution logic is actually being called.

If Current contains a command but Stack's Applied layer is not Command, the problem is usually in the ExecutionDefinition or the route it establishes. If Stack/Queue are correct but the unit does not move, the problem is most likely in the project execution layer.

Command Never Finishes

Symptom: the unit performs the behavior, but Current never clears and subsequent queued commands do not advance.

Check the following first:

1. Confirm that the ExecutionDefinition reports the command result through the exact execution handle on success, failure, or cancellation.
2. Confirm that the StateTree, Ability, or project task reports completion, failure, or timeout.
3. Confirm that the GAS/Ability end event reaches the command callback.
4. Confirm that command requirement tags are not changing during execution in a way that causes project logic to restore the command after cancellation.
5. Check whether Queue CurrentTask elapsed time or timeout grows abnormally.

Do not use ClearCommands to hide this issue. Clearing commands may recover the current session, but the actual problem is a missing completion signal from the execution layer.

New Command Does Not Interrupt the Old Command

Symptom: after the player clicks a new target or AI issues a new task, the old command keeps running.

Check the following first:

1. Confirm that the old command's CancellationPolicy is Cancelable.
2. Confirm whether the new command uses IssueCommand, EnqueueCommand, or one of the Insert APIs.
3. Confirm that the old command's ExecutionDefinition CancelExecution releases only the project execution state owned by that execution.
4. Confirm that the new command was not merely appended to the Queue instead of being started immediately.
5. Check LastResult and ReasonTag for cancellation failure or policy rejection.

Use EnqueueCommand for Shift-style queuing. Use IssueCommand for immediate response, and confirm that the old command policy permits replacement.

Tactical Assignment Produces No Assignment

Symptom: the plan is running, but no Actor receives a command.

Inspect the Tactical Assignment values in GameplayDebugger layer by layer:

1. Actor pool is 0: the Assignee Source produced no candidates, or ContextActor is incorrect.
2. Target pool is 0: the Target Source produced no targets, or targets were not converted into FGAIS_CommandTargetData.
3. Actors before has values but after is 0: the Assignee Filter is too restrictive.
4. Targets before has values but after is 0: the Target Filter is too restrictive. Common causes include mismatched team attitude, SourceTag, or HasActor/NoActor rules.
5. Candidates is 0: Intent resolution, command executability, or target validity failed.
6. Selected is 0: the Allocator, target capacity, ExistingTargetUsage, or location tolerance prevented selection.
7. Assigned/Unassigned contains a failure reason: trace NoResolvedCommand, CannotObeyCommand, InvalidTarget, or MissingCommandSystem back to the corresponding layer.

Do not fix Source or Filter issues inside the Allocator. The Allocator only selects final pairings from candidates that have already been scored.

NoResolvedCommand

Symptom: Tactical Assignment has candidate Actors and targets, but a candidate cannot convert IntentTag into a concrete command.

Check the following first:

1. Confirm that the Batch IntentTag exactly matches UGAIS_UnitComponent.CommandIntentMappings.
2. Confirm that the candidate Actor has a UGAIS_UnitComponent, or that the Actor/component implements IGAIS_CommandIntentResolver.
3. Confirm that the resolver returns a valid Command.Definition.
4. Confirm that Command.Index is valid for a MultiVariant command.
5. Confirm that direct player commands and AI semantic intents are not mixed into the same entry point in a way that leaves the Unit without a corresponding mapping.

CannotObeyCommand or InvalidTarget

Symptom: Tactical Assignment resolves a command but cannot submit it, or a manually issued command is rejected.

Distinguish between the two cases:

• CannotObeyCommand: the executor does not satisfy command requirements. Check SourceRequiredTags, SourceBlockedTags, class/role, resources, dead/stunned/busy state, and any project override of CanObeyCommand.
• InvalidTarget: the target does not satisfy command requirements. Check TargetType, Target Actor, Location, target tags, team attitude, distance, and any project override of IsValidTarget.

If a Filter already accepted the target but the command still reports InvalidTarget, the Filter only performed early pruning and the command-level target rules are stricter. Fix the command rule or target data rather than simply loosening the Filter.

Squad Initialization Fails

Symptom: the Squad panel has no valid Definition, FormationStatus is not ready, or members/roles/capacity do not match expectations.

Check the following first:

1. Confirm that SquadActorClass implements IGAIS_SquadActorInterface.
2. Confirm that the squad host satisfies the runtime contract for SquadComponent, CommandSystem, AIController/Stack, and related components.
3. Confirm that SquadDefinition can be loaded and that AvailableFormations is valid.
4. Confirm that DefaultUnits and AvailableRoles can satisfy roles marked bRequired.
5. Confirm that Capacity is not full and that role Max values are not preventing units from joining.
6. Confirm that team identity is consistent between the squad host and its units.

If the squad can be created but behaves incorrectly, continue with Formation, Slot, and Movement Intent diagnostics instead of recreating the squad.

Slot Assignment Is Incorrect

Symptom: a unit joins the squad but occupies the wrong slot, takes the wrong role, or leaves an important slot empty for an extended period.

Check the following first:

1. Confirm that each SlotId is stable and unique.
2. Confirm that SlotTags and Unit/Role tags belong to the same semantic system.
3. Confirm that SlotTagMatchPolicy matches the intended behavior: mandatory match versus score bonus.
4. Confirm that SlotWeightScoreMultiplier, MatchingTagScore, DistanceCostPer100Units, and StableSlotScore are not unbalanced. The corresponding diagnostic component for slot weight is SlotWeightScoreContribution.
5. In GameplayDebugger slot assignment diagnostics, identify whether tag rejection, distance cost, weight, or stability has the largest effect.

If slot assignment is correct but the unit does not move, continue with Movement Intent and the project movement system.

Movement Intent Has Values but the Unit Does Not Move

Symptom: the Squad panel shows DesiredLocation, DesiredSpeed, or bShouldMove, but the character does not move.

Check the following first:

1. Confirm that the unit has a UGAIS_UnitMovementIntentDriver, or that the project movement system consumes MovementIntent.
2. Confirm that bApplyDriverOnlyWhenIntentChanged is not preventing continuous input from being applied repeatedly.
3. Confirm that the Driver apply interval and Movement Intent update interval are not too large.
4. Confirm that DesiredLocation is reachable and that the Formation navigation projection succeeded.
5. Confirm that the project movement component, GMS, CharacterMovement, or AI MoveTo does not have its own blocking conditions.

Movement Intent is advisory; it does not own movement. GAIS provides the target and response strength, while actual movement is performed by the project movement layer.

Team Attitude Is Incorrect

Symptom: allies are treated as enemies, enemies are filtered out, or every candidate fails the Tactical Assignment Team Attitude Filter.

Check the following first:

1. Determine whether the TeamAgent source of truth is on the Pawn, Controller, PlayerState, or a project-specific object.
2. Confirm that UGAIS_ProjectPolicy points to the project's custom policy.
3. Confirm that GameplayDebugger Team and TeamSource match expectations.
4. Confirm that the source reported by GetGenericTeamQuerySource matches the project design.
5. Confirm that the Team Attitude Filter RequiredAttitude matches the intended gameplay behavior.

Do not patch team attitude independently in each Filter. Team identity should first be unified through ProjectPolicy and the TeamAgent source of truth.

RPC Ownership Mismatch

Symptom: after the client calls Server Issue Command, Server Add Unit, Server Assign Role, Server Set Current Formation, or a similar node, the server state does not change.

Check the following first:

1. Confirm that the call truly occurs on the client rather than in an incorrect non-owning network context.
2. Confirm that the Actor containing CommandSystem, SquadComponent, or FormationComponent is owned by the calling client, or that a usable Owner chain exists.
3. Confirm that the Unit Actor used by ServerLeaveSquad is owned by the calling client.
4. If the squad host is AI/server-owned, consider sending a project RPC through PlayerController, then locating the squad and invoking the authoritative entry point on the server.
5. Confirm whether the server must also validate team ownership, player permissions, resources, or game state.

The presence of an RPC node does not mean it can be called on any Actor. Fix network ownership and server authorization first, then inspect GAIS membership, roles, formations, or command logic.