Formations, Slots, and Navigation

FormationId

Stable formation identity, not a localized display name.

When UI saves a selection or a save game, data table, or debug output references a formation.

Using the display name as identity breaks references after localization or renaming.

DisplayName / Description / Icon

Player- or editor-facing presentation.

For formation selection panels, tooltips, and debug summaries.

These fields only affect presentation and should not serve as gameplay identity.

FormationTraits

Formation-wide tactical semantics.

When StateTree, AI, or UI filters formations by ideas such as defense, advance, or spread.

Mixing these with SlotTags obscures the distinction between formation-wide and slot-local semantics.

bHasDirection

Whether the formation's overall direction supplies unit facing.

Usually enabled for shield walls, wedges, and marching columns; it can be disabled for rings, encirclement, or scattered layouts.

Incorrect direction semantics can turn every unit the wrong way or ignore each slot's own rotation.

SlotDefinitions

Authored slot list containing SlotId, Weight, SlotTags, Location, and Rotation.

Every formation asset must configure it.

Unstable SlotIds break replication, reassignment, Unit mirrors, and debug identification.

SlotDefinitionMap

SlotId lookup generated before saving.

Treat as read-only; it supports definition lookup by SlotId.

Manual maintenance can make the array and lookup map disagree.

SlotId

Stable slot identity, not an array index.

Every assignable, replicated, saved, or debugged slot needs a stable ID.

Changing IDs when reordering the array makes slot retention, debugging, and replication results difficult to explain.

Weight

Slot importance used by squad slot-assignment scoring.

When front-center, guard, or key fire-support positions need higher priority.

Excessive weight can overwhelm tags and distance, letting unsuitable units take key slots.

SlotTags

Slot-local semantics, usually under GAIS.Formation.Slot.

When front/back, inner/outer ring, or ranged positions should match a Unit or Role.

An unclear tag system can produce NoLegalSlot or put roles in the wrong positions.

Location

Local coordinates relative to the formation pivot.

When adjusting shape, unit spacing, and position depth.

Spacing that is too small causes crowding; too large makes Movement Intent chase indefinitely.

Rotation

Local rotation relative to the formation pivot.

When the formation has no overall direction or slots need independent facing.

A value that conflicts with bHasDirection expectations makes units face the wrong way.

AvailableFormations

Formations the current host can switch between.

When a squad or formation host needs several positioning modes.

An empty list prevents EnsureCurrentFormation from establishing a formation.

CurrentFormation

Current runtime formation.

Set directly by the server or selected through a Trait Query.

Direct client changes have no effect, and a class outside AvailableFormations is not selected.

ServerSetCurrentFormation / ServerSetCurrentFormationByTraitQuery

Requests a server-side formation switch by class or Traits.

When the requesting client owns the component Actor or its Owner chain.

Without network ownership, the RPC cannot replace project-level PlayerController forwarding and server authorization.

FormationSpread

Runtime scale applied to slot-local coordinates.

When one formation must suit different unit sizes, group sizes, or combat distances.

Too large makes units chase for too long; too small causes collision crowding.

Container

Replicated runtime slot container for the current formation.

Used internally to store SlotId, definition snapshots, navigation offsets, and preview transforms.

External writes that bypass query APIs break event and replication semantics.

QuerySlots / FGAIS_FormationSlotQuery

Queries immutable runtime views by role, tags, distance, and other conditions.

When Blueprint, EQS, squad slot assignment, or debugging needs slot candidates.

Treating query results as writable state violates the FormationComponent's single source of truth.

FindSlotRuntimeView

Reads one slot runtime view by stable SlotId.

When Movement Intent, debugging, or UI locates a member's slot.

If lookup fails, investigate formation readiness, SlotId, and layout version.

FindAvailableFormationByTraitQuery

Finds a formation by FormationTraits.

When StateTree or AI selects a formation from tactical intent.

An overly broad Traits query always selects an earlier-priority formation.

OnFormationReadyEvent

Broadcasts when the current formation's slot container is ready for consumers.

When squad initialization must wait for the spatial source of truth.

Ignoring the ready contract can make the squad assign an empty slot set.

SlotId

Current runtime slot identity.

Unit mirrors, debugging, and slot lookup.

Do not assume it equals the array index.

Definition

Slot definition copied from the formation asset.

Reading Weight, SlotTags, and local layout semantics.

Do not treat it as an asset-editing entry point at runtime.

WorldTransform

Final position and facing after pivot, spread, and navigation offset are applied.

When squads produce Movement Intent or when debugging and previews show positions.

Using Definition.Location directly bypasses navigation adaptation.

LocationOffset

Runtime local offset produced by navigation projection.

Investigating positions on slopes, steps, and NavMesh edges.

Writing it back to the asset pollutes the authored formation.

bEnabled

Enables runtime navigation projection.

Recommended when units must reach actual NavMesh positions.

Disabled slots may land in non-navigable areas.

UpdateIntervalSeconds

Dirty-check interval for navigation adaptation.

Controls query cost for large or frequently moving formations.

Too low increases NavMesh queries; too high makes slot positions lag.

ReprojectionDistanceThreshold

Reprojects after the pivot moves beyond this distance.

When a formation follows a moving host.

Too small causes frequent projection; too large can retain stale offsets across terrain changes.

ReprojectionYawThresholdDegrees

Reprojects after pivot Yaw changes beyond this angle.

When rotation significantly changes slot positions.

Too large can leave slots at old projected locations after turning.

NavigationQueryFilterClass

Navigation QueryFilter used for projection.

When units, squads, or terrain rules have different traversable areas.

A mismatched filter can project slots onto areas the unit cannot actually reach.

ProjectionStartHeightOffset

Raises the target point before projection.

When ground height varies or slots may sit slightly below the surface.

Too small can fail projection; too large can hit an unintended upper NavMesh layer.

ProjectionQueryExtent

Projection query bounds.

Increase Z or XY on slopes, steps, bridges, and complex terrain.

Too small misses the NavMesh; too large can project onto the wrong region.

ProjectedSlotZOffset

Extra Z offset after successful projection.

When preview points or movement targets should sit slightly above the ground.

Too high makes visualization or movement targets float.

bUseFallbackProjection

Tries fallback samples toward the formation root after projection failure.

Recommended near NavMesh edges, bridges, and obstacles.

When disabled, failed slots are more likely to retain unusable offsets.

FallbackSearchRadius

Maximum distance allowed for fallback samples.

Increase moderately for large formations or fragmented terrain.

Too large contracts slots excessively toward the center and distorts the formation.