Logo_UE_XS
Yuewu
GenericAISystem

Formation System

GenericAISystem formation assets, runtime slots, and navigation adaptation provide matchable, adjustable spatial positions for AI squads.

Table of contents

The Formation System provides a selectable spatial layout for a group. UGAIS_FormationDefinition describes slots, while UGAIS_FormationComponent maintains the active layout and final slot positions at runtime. Squads consume those results to place members; Formation does not own membership, roles, or movement execution.

What a formation solves

UGAIS_FormationDefinition authors a layout with stable SlotId values, tags, positions, and orientations. UGAIS_FormationComponent selects the active formation, owns the available-formation list and runtime slot container, and signals when the layout is ready.

Formation can also serve standalone spatial queries, previews, or scene placement. A squad decides which member occupies a slot; Formation answers where that slot is in the current world and what spatial meaning it carries.

Runtime path

  1. Configure available and initial formations on the FormationComponent, or select another formation on the server.
  2. The component builds runtime slots from the active definition and resolves them from the host location and orientation.
  3. Once ready, a squad can assign members using roles, tags, and scores; Blueprint, EQS, and tools can query the same result through QuerySlots.
  4. A formation switch, spread change, or navigation projection change notifies spatial consumers to reconcile.

Formation selection and runtime geometry are server-authoritative. An owning client can request a server change, but project policy still decides whether it is allowed.

Formation navigation adaptation

The Location authored in a formation asset is local data relative to the pivot, not a member's final world destination. Runtime slots first apply formation direction and FormationSpread, then the host world location and rotation. When navigation adaptation is enabled, ProjectSlotsToNavigation also projects or adjusts slots into usable project navigation space.

Squads, debuggers, and project queries should therefore use the final world transform or GetSlotWorldLocation, rather than consuming an authored offset directly. This keeps every consumer on the same spatial truth when terrain, obstacles, reprojection, or host rotation changes the usable position.

Selection, queries, and extension

Use SetCurrentFormation, trait-query selection, QuerySlots, and FindSlotRuntimeView for common Blueprint integration. A command, tactical state, or StateTree can decide which formation to select without duplicating slot geometry.

For flying units, vessels, layered navigation, or another spatial model, extend FormationComponent and override ProjectSlotsToNavigation. Keep the output as final slot positions so squads remain independent of projection details.

Relationship to squads and Movement Intent

After Formation is ready, a squad assigns member slots and generates a Movement Intent from each member's final slot. Intent is a squad-to-movement hand-off, not another Formation responsibility: Formation supplies spatial results, Squad produces member guidance, and a Driver or project movement layer performs movement.

For setup, see Configure Squads, Formations, and Slots. For Intent generation, see Squad System; for fields, extension, and diagnosis, see Formations, Slots, and Navigation, Formation and Movement Intent Extension Points, and Formation Editor and Slot Diagnostics.