Formation and Movement Intent Extension Points

FormationDefinition changes what a formation asset can express; FormationComponent changes how slots are projected, refreshed, and broadcast at runtime; MovementIntentDriver changes how guidance reaches project movement. Do not force squad roles, command execution, or movement-component implementation into a formation asset.

For Formation space and navigation adaptation, see Formation System; for Squad-owned Intent, see Squad System. See Formations, Slots, and Navigation, Squads, Roles, and Units, Connect Movement Intent to Movement, and Temporarily Override Movement Intent with StateTree for adjacent work.

`UGAIS_FormationDefinition`

Extension point	Changes	Boundary
`CanExecute`	Whether the formation may currently be selected.	Availability only; do not switch squad behavior or issue commands.
`HasDirection`	Whether the formation uses overall direction or slot direction is more important.	Do not write concrete movement orientation here.
`CalculateOffsets`	Procedurally generates/rebuilds slot definitions.	Output stable `SlotId` and explainable SlotTags.
`SetSlotDefinitions`	Writes definitions from a tool, generator, or editor flow.	Do not reorder SlotId as a temporary runtime array index.

CalculateOffsets suits circles, fans, wedges, and random scatter, but must produce diagnosable data. Stable SlotId and SlotTags matter more than a visually plausible layout because squad assignment, Unit mirrors, diagnostics, and saved references depend on them.

`UGAIS_FormationComponent`

Extend FormationComponent for runtime spatial behavior, not squad organization.

Extension point	Changes	Boundary
`ProjectSlotsToNavigation`	Server-side projection of slots into project navigation.	Keep output as slot `LocationOffset`/world result; do not move Units directly or create client-side spatial truth.
`OnFormationChanged`	Project response after a formation switch.	Presentation, logs, and caches are valid; do not bypass readiness.
`AddAvailableFormation(s)`	Opens new formations at runtime.	Server-only; clients request through project/RPC path.
`SetCurrentFormationByTraitQuery`	Selects by FormationTraits.	First match depends on AvailableFormations order and Traits.
`ServerSetCurrentFormation` / `ServerSetCurrentFormationByTraitQuery`	Lets an owning client request a server switch.	Project still validates permission on the server.

For nonstandard NavMesh, layered navigation, flying Units, vessels, or large vehicles, override ProjectSlotsToNavigation or subclass FormationComponent. Keep output as final slot world results so Squad and Movement Intent remain independent of projection details.

`IGAIS_FormationSlotPreviewerInterface`

Slot Previewer displays runtime slot position and orientation. IGAIS_FormationSlotPreviewerInterface is currently a marker interface: FormationComponent creates preview Actors, attaches them to the formation host, and refreshes transforms; it does not supply occupancy, SlotTags, or scoring diagnostics through this interface.

Use project meshes, materials, or icons for slot location/orientation, and distinguish FormationComponent subclasses or preview Actor classes visually. To show SlotTags, occupancy, or navigation failure, query QuerySlots, FindSlotRuntimeView, or squad diagnostics in project code and add a separate binding; do not assume marker-interface input exists.

`UGAIS_UnitMovementIntentDriver`

UGAIS_MovementIntentModifier changes a draft before final Intent generation; UGAIS_UnitMovementIntentDriver changes how final Intent enters a movement backend. A Modifier does not move Units, and a Driver does not recalculate formation slots or roles.

`UGAIS_MovementIntentModifier`

Modifiers are ordered by UGAIS_MovementIntentModifierSet, usable as a shared DataAsset or an Inline Set in a StateTree Task. ModifyMovementIntent receives read-only context and a writable draft, and may change MovePolicy, DriverPolicy, SpeedMultiplier, DesiredSpeedOverride, PredictionVelocity, or MovementIntentTags. Keep it pure: do not mutate roster, formation, commands, abilities, movement components, or modifier bindings in the callback; runtime stability checks protect the resolve source.

`UGAIS_UnitMovementIntentDriver`

UGAIS_UnitMovementIntentDriver applies Squad-generated Intent to project movement. Built-in UGAIS_UnitMovementIntentDriver_CharacterMovement targets ACharacter + CharacterMovement, writing speed and optional orientation.

Driver phases are ActivateMovementIntent, ApplyMovementIntent, and ReleaseMovementIntent. A rejected activation never becomes active; Apply can occur on every refresh; invalid Intent, suspended DriverPolicy, Unit departure, or inactive Squad releases control. A custom Driver should preserve replicated movement truth on the server rather than applying divergent Intent on every client.

Direction	Driver should do	Driver must not do
CharacterMovement	Write MaxWalkSpeed, facing, or a movement request.	Decide whether a Unit remains in the squad.
GMS / custom movement	Convert DesiredLocation, DesiredSpeed, and `bShouldMove` to project movement input.	Recalculate formation slots.
Animation-driven movement	Convert ResponseRatio/SlotTags to animation-layer or movement-state input.	Directly mutate SquadComponent member truth.

The built-in CharacterMovement Driver records original MaxWalkSpeed and rotation-control state. On release it restores only values that still appear Driver-written, avoiding overwrite of later project control. Movement Intent is GAIS guidance, never a claim of ownership over the complete project movement system.

Table of contents