Formation Editor and Slot Diagnostics

Formation Editor and Slot Diagnostics

Formation issues are usually not caused by a single broken point. Instead, one part of the chain between asset slots, the runtime FormationComponent, squad slot assignment, navigation adaptation, and the Movement Intent Driver has failed to converge. When troubleshooting, do not only check whether the unit eventually moves. Inspect the system layer by layer: whether the slot exists, whether it is available, whether it was selected, whether its world-space position is correct, and whether an Intent was generated. This page explains slot diagnostics and Movement Intent diagnostics separately.

Related documentation: for the formation model, see Formation System; for slot fields, see Formation, Slot, and Navigation Parameters; for squad slot scoring and Movement Intent, see Squad, Role, and Unit Parameters.

Asset Layer: Formation Editor

The Formation Editor and slot preview primarily answer three questions:

• Does the formation asset actually contain slots?
• Is each slot's SlotId stable and unique?
• Do Weight, SlotTags, Location, and Rotation express the intended design?

If the slots look correct in the editor but units still occupy the wrong positions at runtime, first confirm that you are debugging the currently active runtime formation rather than another asset with the same name or display name. Debugging and saved references should use FormationId, not only DisplayName.

Runtime Layer: FormationComponent

At runtime, inspect the FormationComponent first:

1. Confirm that AvailableFormations contains the target formation.
2. Confirm that CurrentFormation has been set, or that EnsureCurrentFormation can select the first available formation.
3. Confirm that IsFormationReady is true.
4. Confirm that the slot count matches the asset's SlotDefinitions.
5. Confirm that slot queries are reasonable. Use QuerySlots or FindSlotRuntimeView to inspect the stable SlotId, SlotTags, and final World Transform. Do not determine availability using the legacy slot-state model.

If squad initialization shows that it is waiting for the formation to become ready, the usual causes are a missing FormationComponent, an empty available-formation list, a failed formation-class load, or a runtime slot container that was not rebuilt for the current formation.

Slot Scoring Layer: Slot Assignment Diagnostics

In non-Shipping/Test builds, slot assignment can output debug-only explanations. Focus on the following signals:

Common diagnostic results include Assigned, NoSlotAvailable, NoLegalSlot, and NotChosen. NoSlotAvailable usually indicates a slot-count or query-range issue. NoLegalSlot usually indicates a tag-constraint issue. NotChosen generally requires inspecting the global scoring competition.

Navigation Adaptation Layer

Typical symptoms of navigation-adaptation issues include: a slot is assigned but its world-space position is in an unwalkable area; a unit fails while moving toward the slot; or slot preview points visibly float or shift near slopes, bridge edges, or stairs.

Check the following in order:

1. Confirm that NavigationAdaptationConfig.bEnabled is enabled.
2. Confirm that the current world has a usable NavMesh and the correct default NavData.
3. Confirm that NavigationQueryFilterClass permits the area containing the slot.
4. Confirm that ProjectionQueryExtent, especially its Z value, is large enough to cover terrain-height differences.
5. Confirm that ProjectionStartHeightOffset raises the projection start point far enough above the surface.
6. Confirm that pivot movement or rotation exceeds ReprojectionDistanceThreshold / ReprojectionYawThresholdDegrees; otherwise, reprojection may not have been triggered.
7. If projection fails, confirm that bUseFallbackProjection is enabled and that FallbackSearchRadius is large enough to contract the search toward the formation root.

If only some slots are incorrect, the issue is usually local NavMesh coverage or the slot positions themselves. If none of the slots are projected, inspect NavData, QueryFilter, and whether the component has authority first.

Movement Intent Layer

Successful slot assignment does not mean that the unit will move. Movement Intent is an advisory output. Actual movement must be performed by UGAIS_UnitMovementIntentDriver or consumed by the project's movement system.

During troubleshooting, confirm the following:

• The Unit's AssignedSlotId has been mirrored to the UnitComponent.
• The Unit's AssignedSlotId can locate the corresponding slot through FindSlotRuntimeView.
• RawDesiredLocation is close to the FormationComponent's slot world location.
• Check whether DesiredLocation includes feed-forward offset caused by average-velocity prediction.
• Confirm that bShouldMove is true. If it is false, inspect MoveStartDistance / MoveStopDistance.
• Confirm that DesiredSpeed is greater than 0. If it is 0, inspect the Response settings and distance error.
• Confirm that MovementIntentDriver is configured, or that the project's movement system reads the Intent from the UnitComponent.

If the Intent is correct but the unit does not move, the issue has usually left the formation system and entered the movement-system integration boundary. Continue with Integrating Movement Intent into the Movement System.