Squads, Roles, and Units

Squad settings describe organization: a Definition specifies how a squad is composed, SquadComponent owns runtime members and roles, UnitComponent mirrors each Unit's squad identity, and slot assignment plus Movement Intent connect that organization to Formation and movement.

For the ownership model and Intent generation, see Squad System. For Formation space and navigation adaptation, see Formation System. Setup and extension are covered by Configure Squads, Formations, and Slots and Squad, Role, and AI Extension Points.

`UGAIS_SquadDefinition`

UGAIS_SquadDefinition is a static template for one kind of squad. It does not store runtime members; it defines the host, default Units and roles, available formations, behavior baseline, slot scoring, and Movement Intent defaults.

Field	Purpose	Adjust when	Misconfiguration risk
`SquadActorClass`	Runtime host Actor; must implement `IGAIS_SquadActorInterface`.	Squad types need different hosts, components, or presentation.	Missing interface/runtime component fails the initialization contract.
`DefaultTeamId`	Default team ID applied to the host at initialization.	Squad has a fixed affiliation or inherits one on creation.	Conflict with project team truth affects filtering, attitude, and Tactical Assignment.
`AvailableFormations`	Formations the squad may use; order affects trait-query first match.	Switching defensive, advance, or spread formations.	Empty or unloadable classes prevent Formation readiness.
`DefaultUnits`	Unit templates for creation or replenishment.	`CreateSquad` spawns a fixed group or replenishment follows default composition.	Missing UnitClass or nonexistent DesiredRole leaves vacancies or fails role fill.
`InitialFormation`	Explicit initial formation, also required in `AvailableFormations`.	Initial positions must not depend on available-list order.	A formation outside the list fails initialization or editor validation.
`AvailableRoles`	Available roles; `RoleTag` is the stable identity.	You need role capacity, class limits, priority, or role StateTrees.	Missing/duplicate roles break default Units, role assignment, and slot matching.
`DefaultSquadStateTree`	Baseline StateTree for the squad host.	Whole-squad patrol, advance, retreat, or formation changes.	Putting Unit execution details here blurs responsibility.
`DefaultUnitStateTree`	Default Squad-layer fallback for a joined Unit.	A role has no dedicated StateTree but joined Units need common behavior.	Without fallback, some Units have no Squad-layer behavior.
`SlotAssignmentSettings`	Scoring rules from Units to Formation Slots.	Positions do not meet tag, distance, or stability intent.	Unbalanced weights cause swapping, bad placement, or `NoLegalSlot`.
`DefaultMovementIntentResponseSettings`	Start/stop, speed response, and prediction defaults for every Intent draft.	Tuning formation follow distance, speed, or short prediction.	Bad thresholds cause jitter, stalls, or permanent catch-up.
`DefaultMovementIntentTags`	Default project-semantic tags on Intent drafts.	Driver, animation, or movement layer recognizes facing or arrival semantics.	Unclear tags make Driver decisions hard to explain.
`MovementIntentDriver`	Strategy that applies batched Intent refreshes to Unit movement.	GAIS should bridge Intent to CharacterMovement, GMS, Mover, or custom movement.	Competing with project movement truth causes overwrites.

`FGAIS_SquadUnitInfo`

Default Unit templates are used when a Definition creates or replenishes a squad. UnitClass is the Actor class to spawn or fill, DesiredRole is the initial role, and OverrideRoleAI supplies a Unit-level role StateTree override. Missing classes/components make members invalid; an unavailable role is reassigned, left vacant, or triggers the missing-role policy; too many overrides make role-default AI difficult to maintain.

`FGAIS_SquadRoleInfo`

Role settings define which Units can occupy a post and its priority during fill and slot contention. They affect role occupancy, StateTree assignment, slot semantic matching, and reorganization.

Field	Purpose	Risk
`RoleTag`	Stable post identity, normally under `GAIS.Role`.	Do not mix it with SlotTags or CommandIntent tags.
`AllowedClasses`	Restricts eligible Actor classes; empty means unrestricted.	A wrong class list prevents replacement.
`RequiredTags` / `BlockTags`	GameplayTag role qualification.	Inconsistent tag vocabulary makes `IsQualifiedOfRole` opaque.
`MaxNum`	Maximum concurrent occupants.	Conflict with DefaultUnits leaves excess Units unroled.
`Priority`	Higher values get role/slot opportunities first.	Excessive priority starves ordinary roles of suitable slots.
`bRequired`	The squad expects this role to be filled.	Marking too much required triggers frequent replenishment or degradation after ordinary losses.
`StateTree`	Default Squad-layer StateTree for this role.	Do not put an entire combat flow here and overlap Command/Queue responsibility.

`UGAIS_SquadComponent`

UGAIS_SquadComponent is runtime squad truth: it initializes the Definition, maintains member FastArray and role occupancy, tracks capacity, waits for Formation readiness, reallocates slots, refreshes Movement Intent, and emits member events.

Surface	Purpose and use	Boundary
`bInitializeOnBeginPlay`	Automatically initialize a placed host with its Definition.	Incomplete Definitions expose initialization failure at BeginPlay.
`GetMaxUnitCount` / `GetRemainingUnitCapacity` / `IsFull`	Query hard capacity from current Formation slots.	Capacity changes with current slot count; do not cache it or look only at role capacity.
`UnitsContainer`, `RoleContainer`	Runtime member and role truth for replication, events, and required-role state.	Use public operations; direct mutation breaks mirrors and events.
`HasUnit` / `HasUnits` / `HasAnyUnit`	Test one, all, or any Units before UI, authority, or batch changes.	`HasUnits` is false for empty/invalid input; that does not mean every Unit belongs.
`AddUnit` / `RemoveUnit` and batches	Server-authoritative recruitment, departure, death, and summons.	Client calls do not change truth; bypassing them desynchronizes Unit projection.
`ServerAdd/RemoveUnit(s)`	Owning client requests a member change.	RPC ownership is not general authorization.
`AssignRoleToUnit(s)` / `RevokeRole...`	Server role changes for player edits, AI reorganization, and replacement.	Follow-up refresh must occur or slots and StateTree retain old state.
`ServerAssignRole...` / `ServerRevokeRole...`	Owning client requests a role change.	Project still authorizes on server.
`GetInitializationState` / `IsSquadActive`	Observe unstarted, waiting-for-space, Active, or failure lifecycle.	Do not infer readiness from nonempty Formation or private convergence functions.
`OnInitializationStateChangedEvent` / `OnSquadActivatedEvent`	Event-driven readiness for UI, project logic, and tests.	Polling member count continues too early when Formation is not ready.
`IssueSquadCommand`	Issues through host CommandSystem.	It never bypasses CommandSystem execution.
`ServerDismiss` / `ServerChangeSquadTeamId` / `ServerIssueSquadCommand`	Requests host dismissal, team change, or Command.	Nonowners must use PlayerController/project RPC.
`SetUnitSquadStateTree` / `ClearUnitSquadStateTree`	Set or clear a Unit's Squad-layer behavior on join/leave or role change.	Failure to clear leaves departed Units under Squad behavior.

`UGAIS_SquadSubsystem`

The World-level squad registry and creation helper serves project logic, Blueprint, and higher systems.

Entry point	Purpose
`CreateSquad`	Creates a host from SquadDefinition and can spawn default Units.
`CreateSquadFromActors`	Creates a host and atomically recruits existing Actors.
`CreateSquadFromNearbyUnits`	Recruits a requested count of nearby unassigned Units.
`GetUnassignedUnits`	Returns registered Units with no squad.
`GetAutomaticallyRecruitableUnits`	Returns unassigned Units passing automatic-recruitment policy.
`TryReorganizeSquad`	Recruits nearby Units and tries to fill missing roles.
`MergeSquads`	Primary squad absorbs secondary squad while retaining its identity and high-level semantics.

`UGAIS_UnitComponent`

UGAIS_UnitComponent makes an Actor recognizable to squads and mirrors assignment results. It is also the default command-intent Resolver; final Commands execute through UGAIS_CommandSystemComponent on the candidate Pawn/Character.

Field	Purpose	Boundary
`CommandIntentMappings`	Default IntentTag-to-Command reference mapping.	Missing mapping causes `NoResolvedCommand`.
`OwningSquad`	Replicated current squad for UI, diagnostics, and Driver state.	Not an editor-time source of truth.
`CurrentRole`	Role mirrored from Squad entry.	Writing it does not change SquadComponent role truth.
`AssignedSlotId`	Formation Slot ID mirrored from Squad entry.	Writing it does not change slot assignment.
`MovementIntent`	Most recent mirrored movement guidance.	Treating it as movement truth conflicts with CharacterMovement/GMS and similar systems.
`ServerLeaveSquad`	Owner-chain client request to leave.	It cannot replace server authorization for an unowned Unit.

`FGAIS_FormationSlotAssignmentSettings`

Slot assignment scores Unit/Actor tags, current role tag, SlotTags, slot weight, distance, and previous slot.

Field	Purpose	Risk
`SlotTagMatchPolicy`	Add-only, require-any, require-all, or ignore SlotTags.	Strict RequireAll yields `NoLegalSlot`; Ignore removes tag semantics.
`bUseHierarchicalTagMatching`	Enables GameplayTag parent-child matching.	Disabling it reduces parent/child matches.
`SlotWeightScoreMultiplier`	Score multiplier for Slot weight.	Too high overwhelms tag and distance.
`MatchingTagScore`	Score per Unit/Slot tag match.	Too low makes configured tags appear ineffective.
`DistanceCostPer100Units`	Penalty per 100 UU.	Too high makes Units choose nearby but semantically wrong slots.
`StableSlotScore`	Bonus for keeping the previous slot.	Too high resists needed reorganization after formation or role change.

`FGAIS_MovementIntentResponseSettings`

These settings turn slot targets into movement guidance. They do not move Units; they provide Driver/project movement with desired location, speed, response strength, and arrival state. DefaultMovementIntentResponseSettings initializes each draft and Squad/Unit Modifiers can override it.

Field	Purpose	Risk
`MoveStartDistance`	A stopped Unit moves only beyond this distance.	Too small jitters; too large leaves obvious error unmoved.
`MoveStopDistance`	A moving Unit stops below this distance.	Larger than Start or too large stops loosely.
`ResponseDistance`	Distance error at response strength 1.	Too small reaches full speed instantly; too large catches up slowly.
`ResponseCurve`	Optional response-strength remapping.	Bad output causes speed jumps.
`NearDesiredSpeed` / `FarDesiredSpeed`	Desired speeds near/far from slot.	Unclear Far-below-Near intent makes the curve hard to tune.
`MinDesiredSpeedWhenMoving`	Minimum desired speed while moving.	Too high overshoots near the slot.
`DesiredLocationPredictionTime`	Predicts target from average squad velocity.	Too high leads Units to chase an overly distant point.

Movement Intent Modifiers and final Intent

Formation first supplies slot world position/orientation and creates FGAIS_MovementIntentResolveState, seeded with Definition response settings, default tags, and average-squad-velocity prediction. Squad Modifiers run before Unit Modifiers. Within one scope, higher PriorityWithinScope runs later and is appropriate for final overrides.

Surface	Purpose	Risk
`UGAIS_MovementIntentModifierSet`	Ordered immutable Modifier templates, usable as shared assets or Inline Sets.	Empty sets or invalid children are rejected.
`ModifyMovementIntent`	Purely transforms the draft.	Changing members, formation, Commands, or modifier bindings in the callback is rejected or guarded.
`PushSquadMovementIntentModifier`	Registers a Modifier for a squad and returns a handle.	Invalid owner/set, nonauthority, inactive squad returns an invalid handle.
`PushUnitMovementIntentModifier`	Registers a Modifier for one member.	Fails if the Unit is not in this squad.
`PopMovementIntentModifier` / `RemoveMovementIntentModifiersByOwner`	Clears bindings by handle or owner.	Forgotten cleanup leaves old state affecting Intent.
`MovePolicy`	Auto hysteresis, force move, or force stop.	Competing Driver/Command ownership causes tug-of-war.
`DriverPolicy`	Whether Driver applies final Intent.	`Suspended` makes Intent correct but leaves the Unit undriven.
`PredictionVelocity`	Advances target during prediction.	Excessive prediction chases a too-distant point.
`MovementIntentTags`	Semantics for Driver, animation, and project movement.	Inconsistent conventions make consumer behavior unstable.

Final FGAIS_SquadUnitMovementIntent records RawDesiredLocation, predicted DesiredLocation, DesiredOrientation, DesiredSpeed, DesiredVelocity, bShouldMove, bIsInDesiredLocation, MovementIntentTags, and DriverPolicy. It is written to the Squad entry and mirrored to UnitComponent.

Table of contents