Squad System

The Squad System manages a group of units as an organization that can be created, reinforced, reorganized, and commanded. It owns the runtime truth for members, roles, capacity, and slot occupancy. Once Formation provides final slot positions, Squad generates a Movement Intent for every member and hands it to the project movement layer.

Where organization truth lives

UGAIS_SquadSubsystem indexes squads and units in the current World, and handles discovery, creation, merging, recruitment, and reorganization. The host Actor's UGAIS_SquadComponent owns a squad's committed members, roles, slots, and lifecycle. UGAIS_UnitComponent mirrors the owning squad, current role, AssignedSlotId, and final Movement Intent to each member for UI, StateTree, drivers, and diagnostics.

UGAIS_SquadDefinition contains static setup: the host, default units and roles, available formations, slot scoring, default behavior, and default Movement Intent response, tags, and driver. It is not a mutable runtime member container.

Squad, Formation, and slot assignment

During initialization, a squad reads its Definition and configures FormationComponent. It can wait while Formation is not ready, so successful creation or initialization does not mean every member already has a usable slot. Once ready, SquadComponent commits slot assignments using roles, tags, capacity, and scores, then mirrors the result to UnitComponent.

Formation owns slot geometry and navigation projection; Squad owns which member occupies an available slot. Formation, membership, or role changes cause Squad to reconcile assignments. Do not write a UnitComponent mirror directly to bypass this path.

How a squad generates Movement Intent

After slot assignment commits, SquadComponent requests a Movement Intent refresh. Each Intent starts from that member's final assigned-slot world position, then incorporates SquadDefinition default response settings and tags plus squad or unit Modifiers. The final result is mirrored to UnitComponent.

plaintext

1Final Formation slot
2→ SquadComponent assigns member slots
3→ SquadComponent refreshes each member's Movement Intent
4→ UnitComponent mirrors the result
5→ Movement Intent Driver / project movement layer consumes it

Intent expresses suggested position, speed, orientation, and whether a unit should move. It does not replace navigation, avoidance, animation, network prediction, or project command priority. UGAIS_UnitMovementIntentDriver is the per-squad strategy that acquires, applies, and releases this control; it does not recalculate Formation or own membership and roles.

StateTree, commands, and authority

SquadComponent exposes squad-level command and Squad StateTree-layer entry points. They connect organization to behavior scheduling without replacing explicit Command requests or Tactical Assignment candidate selection.

Squad truth and slot assignment are server-authoritative; client RPCs are only requests from an owner. Create runtime squads through the Subsystem and initialize placed squads on the server. Observe lifecycle state and OnSquadActivatedEvent, rather than inferring readiness from member count alone.

Next steps

For setup, see Configure Squads, Formations, and Slots. For spatial results and navigation adaptation, see Formation System. For Intent fields, project movement integration, and temporary modifiers, see Squads, Roles, and Units, Connect Movement Intent to Movement, and Temporarily Override Movement Intent with StateTree.