Tactical Assignment Reference

Tactical Assignment configuration lives at three levels. A Plan defines batches and reevaluation cadence; a StateTree Task supplies the top-level Sources for one run; project policy and settings define capacity and location canonicalization for physical targets. Candidate flow, Allocator context, and Session tracking state are produced at runtime and are not saved Plan fields.

`UGAIS_TacticalAssignmentPlan`

A Plan can be a Data Asset or an Inline Plan on a StateTree Task. It stores reusable planning rules; the Task Sources provide candidate Units and targets for a run.

Field	Purpose	Adjust when	Misconfiguration risk
`Batches`	Tactical requests evaluated in order. Actors assigned by an earlier Batch do not enter later Batches.	You need several tactical priorities.	Placing low-priority Batches first consumes candidates too early.
`ReevaluationInterval`	Automatic reevaluation interval; must be greater than zero.	Balancing changing situations against runtime cost.	A short interval repeatedly runs Sources, Filters, scoring, and allocation; a long one reacts slowly.

Plan validation requires at least one Batch, a valid IntentTag on every Batch, valid Filter instances, finite score adjustments, and a valid reevaluation interval.

Data Asset versus Inline Plan

Item	`Plan` Data Asset	`Inline Plan`
Type	Standalone `UGAIS_TacticalAssignmentPlan` asset.	An inline instance of the same type on the Task.
Configurable fields	`Batches`, `ReevaluationInterval`.	The same fields.
Runtime semantics	The Task resolves it and starts a Session.	The Task resolves it and starts a Session.
Reuse	Multiple Tasks can reference it.	Saved only with the current Task configuration.
Change impact	Asset changes affect every reference.	Affects only this StateTree call site.
Sources	Supplied independently by every referencing Task.	Supplied by the current Task.
Selection constraint	Mutually exclusive with Inline Plan.	Mutually exclusive with Plan.

Standalone asset validation covers the Plan itself. When a Session starts, the system also validates the complete runtime configuration together with Sources supplied by the calling Task. An Inline Plan has the same fields and runtime capability; its configuration ownership is local to the Task.

`FGAIS_TacticalAssignmentBatch`

A Batch states which semantic request this priority makes, which candidates may participate, how scores are adjusted, and who makes the final selection. The Task supplies Sources centrally.

Field	Purpose	Adjust when	Misconfiguration risk
`DebugName`	Identifies the Batch in the editor, logs, and diagnostics.	A Plan has multiple Batches.	Does not change behavior, but makes diagnosis harder.
`IntentTag`	The `GAIS.CommandIntent.*` semantic that candidate Units resolve.	Separating attack, support, guard, and similar behavior.	A mismatch with Resolver or `CommandIntentMappings` produces `NoResolvedCommand`.
`AssigneeFilters`	Filters candidate Actors before command validation; every Filter must pass.	Limiting roles, tags, states, or distance.	Overly strict filters can reduce the Actor pool to zero.
`TargetFilters`	Filters targets before command `IsValidTarget`.	Limiting affiliation, source, Actor/location form, and similar rules.	The Command still performs its own target validation afterward.
`ScoreAdjustment.Multiplier`	Multiplies the Command base score.	A Batch needs an overall preference increase or decrease.	Extreme values hide the Command base score.
`ScoreAdjustment.AdditiveBias`	Adds a bias after multiplication.	Raising or lowering one Batch uniformly.	Cannot make an otherwise illegal candidate legal.
`Allocator`	Optional final selector; null uses Greedy With Capacity.	The default capacity-aware greedy choice does not fit gameplay.	A custom Allocator must not rediscover Sources or rerun command validation.

StateTree Task runtime inputs

FGAIS_STT_RunTacticalAssignmentPlan owns Session lifetime and top-level inputs while its StateTree state is active.

Input/output	Purpose	Notes
`AIController`	The only owning Controller for this run; the Task derives the Context Pawn from its current Pawn.	An invalid Controller cannot establish runtime context.
`Plan` / `Inline Plan`	Reusable asset or inline rule set.	Exactly one must be set.
`AssigneeSources`	Top-level Sources that each contribute candidate Actors.	They are not Batch fields. Each Source writes independently and the final pool is their union.
`TargetSources`	Top-level Sources that each contribute `FGAIS_CommandTargetData`.	Targetless Commands need not consume them; other Batches may still require real targets.
`ReplanCount`, `LastUpdateResult`, `AssignmentCount`	StateTree-readable outputs for this run.	Synchronized by the Session for observation and branching.
`OnAssignmentsAvailable` / `OnAssignmentsUnavailable`	Edge events when assignment availability changes.	Repeated identical state does not broadcast again; `Deferred` does not broadcast.

Sources and `SourceTag`

UGAIS_TacticalAssignmentAssigneeSource and UGAIS_TacticalAssignmentTargetSource Gather entry points only fill output arrays. Fixed Actor/Target Data arrays, squad members, EQS Actors or locations, and project-specific input can all be implemented as Sources.

Configuration	Purpose	Risk
Target Source `SourceTag`	Adds source semantics to produced targets that do not already have one. Filters, Resolvers, and diagnostics can use it. A TargetData item with its own Tag is not overwritten.	An inconsistent tag vocabulary makes SourceTag Filters exclude expected targets.
`ValidateSourceConfiguration`	Validates deterministic prerequisites such as QueryTemplate, RoleTag, or an explicit SquadActor.	It must not mean “there are no targets this run”; that is normal empty output.
Gather output	This Source's independent candidate contribution for the run.	Empty output, no query result, or invalid output contributes an empty set; other Sources continue normally.

Built-in Assignee Sources

Editor label / type	Input and behavior	Use for	Key limitation
Actor Array / `UGAIS_TacticalAssignmentAssigneeSource_ActorArray`	A fixed `Actors` array.	Minimal verification or binding a few explicit Units from script.	Invalid items are dropped; not suitable for dynamic discovery.
All Squad Units / `UGAIS_TacticalAssignmentAssigneeSource_AllSquadUnitActors`	Expands every resolved Unit from an explicit `SquadOverride` SquadComponent.	Treating a whole squad as one shared candidate pool.	Does not fall back to Context Pawn; without explicit configuration this run is empty.
Squad Units By Role / `UGAIS_TacticalAssignmentAssigneeSource_SquadUnitActorsByRole`	Collects an exact `RoleTag`; uses Context Pawn when `SquadOverride` is null.	A Source only needs one role.	`RoleTag` is required and exact-match only; use a Role Filter for more complex role sets.
EQS Actors / `UGAIS_TacticalAssignmentAssigneeSource_EQSActors`	Runs `QueryTemplate` and reads Actor items using `RunMode`; uses Context Pawn when `QuerierOverride` is null.	Spatial searches for distance, visibility, areas, and similar criteria.	Query must return Actors. Current implementation is synchronous and immediate; a failure contributes an empty set this run.

Built-in Target Sources

Every Target Source inherits SourceTag.

Editor label / type	Input and behavior	Use for	Key limitation
Target Data Array / `UGAIS_TacticalAssignmentTargetSource_TargetDataArray`	Direct `FGAIS_CommandTargetData` array.	Actor plus location, pure locations, or preset TargetTags/SourceTag.	Every item must resolve to a valid physical target.
Actor Targets / `UGAIS_TacticalAssignmentTargetSource_ActorArray`	Converts `Actors` into Actor TargetData.	Fixed enemies, allies, or interactables.	Does not create pure location targets.
All Squad Units / `UGAIS_TacticalAssignmentTargetSource_AllSquadUnitActors`	Expands all Units from an explicit `SquadActor` and gathers owned tags.	Healing, support, escort, and other Plans targeting squad members.	`SquadActor` is required.
EQS Actor Targets / `UGAIS_TacticalAssignmentTargetSource_EQSActors`	Converts EQS Actor items to targets and retains Actor-owned tags.	Dynamic enemies or interactable Actors.	`QueryTemplate` is required and its item type must be Actor.
EQS Location Targets / `UGAIS_TacticalAssignmentTargetSource_EQSLocations`	Converts EQS Vector items to pure location targets.	Cover, guard, or flanking locations.	`QueryTemplate` is required and its item type must be Vector/Location.

`SourceTag` writing, matching, and boundary

TargetData with a valid SourceTag keeps its value.
TargetData without a Tag receives the producing Target Source's SourceTag.
TargetFilter_SourceTag checks BlockedSourceTags first and rejects a match. If Allowed is empty, other sources pass; otherwise a source must match an Allowed Tag. Matching follows GameplayTag parent-child hierarchy.
Intent Resolver receives this Tag in its context and can choose a Command by source.
GameplayDebugger displays the Tag on Assigned and Unassigned rows.
Candidates and reservations treat different SourceTags for one Actor as distinct logical candidates, but reservations canonicalize by Actor; pure locations canonicalize by location grid.

Built-in Assignee Filters

Type / editor label	Tests	Common use
`UGAIS_TacticalAssignmentAssigneeFilter_ActorOwnedTags` / Actor Owned Tags	All `RequiredTags` exist, no `BlockedTags` exist, and optional `TagQuery` passes.	Allow only combat-ready, unstunned, or suitably equipped Units.
`UGAIS_TacticalAssignmentAssigneeFilter_HasRole` / Has Role	Candidate has a valid Squad Role.	Exclude members not yet assigned a role.
`UGAIS_TacticalAssignmentAssigneeFilter_NoRole` / No Role	Candidate has a Squad entry but no valid Role.	Give unassigned members a fallback task.
`UGAIS_TacticalAssignmentAssigneeFilter_RoleTagQuery` / Role Query	Tests Squad Role with `RoleTagQuery`; an empty query accepts any valid Role.	One Batch serves a group of roles.
`UGAIS_TacticalAssignmentAssigneeFilter_DistanceToDesiredLocation` / Distance To Desired Location	Candidate must have a valid formation slot and MovementIntent, and be within `MinimumDistance` to optional `MaximumDistance`.	Make only stragglers catch up, or admit members near their slots to the next task.

Distance To Desired Location can use predicted/smoothed DesiredLocation or raw RawDesiredLocation; DistanceMetric can be 2D or 3D; a maximum distance of 0 means no upper bound.

Built-in Target Filters

Type / editor label	Tests	Common use
`UGAIS_TacticalAssignmentTargetFilter_TargetActorOwnedTags` / Target Actor Tags	Target must have an Actor and pass Required/Blocked/TagQuery.	Attack only lockable enemies or heal only injured allies.
`UGAIS_TacticalAssignmentTargetFilter_TeamAttitude` / Team Attitude	Context Actor's attitude to the target Actor equals `RequiredAttitude`, Hostile by default.	Friend-or-foe filtering.
`UGAIS_TacticalAssignmentTargetFilter_SourceTag` / Target Source Tag	Filters using Allowed/Blocked source Tags.	Send one target pool to attack, guard, player-marked, or other Batches.
`UGAIS_TacticalAssignmentTargetFilter_TargetHasActor` / Has Actor Target	Keeps only valid Actor targets.	Actor-based Commands.
`UGAIS_TacticalAssignmentTargetFilter_TargetHasNoActor` / No Actor Target	Keeps only targets with no Actor.	Pure-location guard, movement, or flanking.

The boundary is simple: Sources decide where the global candidate pool comes from; each Batch's Filters decide who from that union can participate in its current tactical intent. Filtering occurs before pairing and Intent Resolver. CommandDefinition still runs CanObeyCommand and IsValidTarget afterward.

Target capacity and location canonicalization

The World Subsystem owns target capacity. It uses UGAIS_ProjectPolicy::ResolveTacticalAssignmentTargetCapacity to establish authoritative capacity for a canonical physical target. The default policy uses MaxAssigneesPerTacticalTarget: a positive value is a hard limit and 0 permits unlimited sharing. Batches and the Greedy Allocator do not have independent capacity-number fields.

UGAIS_DeveloperSettings.TacticalAssignmentLocationTargetGridSize controls the canonicalization grid for pure location targets. Actor targets use Actor identity; targetless Commands do not reserve physical targets. Do not look for removed Plan fields such as TargetLocationTolerance or MaxAssigneesPerTarget.

What a custom Allocator sees

FGAIS_TacticalAssignmentAllocatorContext is read-only Batch input: Context Actor, Batch Index, Batch copy, scored CandidateAssignments, and TargetCapacities. The capacity view already includes existing World claims; the core still validates candidate origin and capacity when it accepts results.

An Allocator selects. It must not call Sources again, redo Filters, resolve Intent again, or bypass Command validation. To change whether a Unit can execute or a target is legal, use a Command, Resolver, or Filter.

The default UGAIS_TacticalAssignmentAllocator_GreedyWithCapacity visits candidates in stable descending AdjustedScore order. One Actor produces at most one selection. A reservation-requiring candidate must also satisfy ExistingClaims + selections in this Batch <= MaxAssignees; equal scores retain original candidate order.

`FGAIS_TacticalAssignmentCandidate`

Every item an Allocator receives has passed Sources, Filters, Resolver, and Command validation.

Field	Meaning
`Actor`	Unit ready to receive the Command.
`IntentTag`	Tactical semantic requested by the current Batch.
`ResolvedCommand`	Command Definition and variant index resolved by the Unit.
`SourceTargetData`	Original Source target, preserving source semantics and reservation identity.
`TargetData`	Final command target resolved for the current Unit.
`ReservationKey`	Physical-target bucket for an Actor or location grid.
`CommandScore`	Base score returned by CommandDefinition.
`AdjustedScore`	Score after Batch multiplier and bias.

A custom Allocator writes selected original candidates to SelectedAssignments. The core looks them up in the canonical candidate set, so altered fields, fabricated candidates, or duplicate selection of an Actor are rejected.

Target capacity modes

FGAIS_TacticalAssignmentTargetCapacity has three modes.

`Mode`	Behavior	Typical use
`Limited`	Uses `MaxAssignees` as a hard limit of at least 1.	One-person cover, two-person coordinated attack, or limited interaction slots.
`Unlimited`	Any number of Sessions/assignments may share the target.	Rally areas or a public follow target.
`Blocked`	Rejects new reservations for this physical target.	A temporarily closed point or facility under repair.

FGAIS_TacticalAssignmentTargetCapacityView.ExistingClaims is the number held by other Sessions. The requesting Session's own existing claim is handled separately during replacement. Resolved capacity remains stable while a reservation bucket is non-empty so repeated reevaluations have stable results.

Customize capacity through UGAIS_ProjectPolicy::ResolveTacticalAssignmentTargetCapacity(World, CanonicalTargetData). The policy is called through its CDO and can immediately inspect the target Actor, type, tags, or project rules. The World Subsystem owns cross-frame usage, so the policy need not cache Actors or counts.

Results and diagnosis

Deferred means a World-update guard conflict or synchronous reentry and preserves tracked assignments and reservations. When a Source produces nothing this run, normal evaluation still completes, reconciling old assignments against the current candidate flow and marking them Stale when necessary.

For the end-to-end configuration workflow, see Configure a Tactical Assignment Plan; for extension ownership, see Tactical Assignment Extension Points; for failure signals, see Troubleshooting Flows.

Table of contents