Team Identity and Project Policy

The team identity system answers three questions: how GAIS determines which side an Actor belongs to, whether another Actor is friendly or hostile, and whether those rules should be owned by GAIS or by an existing project system. It allows command validation, Tactical Assignment, squad recruitment, and debugging to use the same team-query policy.

What Problem Does This System Solve?

Many projects already have their own faction, team, hostility, player-ownership, or GAS relationship rules. GAIS should not force those rules to be moved into the plugin. UGAIS_TeamAgentComponent provides a lightweight default source of truth, while UGAIS_ProjectPolicy provides a project-level policy entry point so GAIS can switch between its default model and a custom project team system.

If the project has no faction system, TeamAgent is enough to establish friendly and hostile relationships. If the project already has a mature source of truth, connect GAIS to it through ProjectPolicy instead of maintaining a second set of team state.

Runtime Model and Key Flow

UGAIS_TeamAgentComponent is GAIS's default source of truth for team identity. It stores a replicated TeamId and provides SetTeamId, GetTeamId, HasValidTeamId, and OnTeamIdChangedEvent. When mirroring is enabled, it synchronizes TeamId to the Owner or related Controller objects that implement IGenericTeamAgentInterface.

UGAIS_ProjectPolicy is a project-level policy CDO used to centralize team identity queries and writes. The default policy resolves TeamId through Actor, Controller, Pawn, TeamAgent, and IGenericTeamAgentInterface paths. Projects can override ResolveTeamAgent, HasGenericTeamId, GetGenericTeamId, SetGenericTeamId, and GetGenericTeamQuerySource.

UGAIS_AIBlueprintHelperLibrary is the unified Blueprint-facing entry point. GetGenericTeamId, SetGenericTeamId, and GetTeamAttributeTowards all use the active ProjectPolicy so different systems do not query team state independently.

Minimal Setup

If the project does not already have a team system, add UGAIS_TeamAgentComponent to the Pawn or Controller.
Call SetTeamId on the server. Keep bApplyTeamIdToMirrors enabled when Owner/Controller mirroring is needed.
If the project already has a team source of truth, create a UGAIS_ProjectPolicy subclass and override team query/write logic.
Assign that policy class to UGAIS_DeveloperSettings.ProjectPolicyClass.
Use UGAIS_AIBlueprintHelperLibrary::GetTeamAttributeTowards or GameplayDebugger to verify the relationship among ContextActor, CandidateActor, and TargetActor.

Common Entry Points

Entry Point	Typical Use
`UGAIS_TeamAgentComponent::SetTeamId`	Set an Actor's replicated team ID on the server.
`UGAIS_ProjectPolicy::SetGenericTeamId` / AI Blueprint Helper	Write the team ID to the source of truth resolved by project policy on the authoritative side.
`GetTeamId` / `HasValidTeamId`	Read the team state stored by TeamAgent itself.
`OnTeamIdChangedEvent`	Update UI, visual presentation, or debug state when team identity changes.
`UGAIS_ProjectPolicy::GetGenericTeamId`	Read any Actor's team ID through project policy.
`SetGenericTeamId`	Write the team ID back to the source of truth recognized by the project.
`GetGenericTeamQuerySource`	Debug whether the current TeamId was resolved from self, controller, pawn, or interface.
`UGAIS_AIBlueprintHelperLibrary::GetTeamAttributeTowards`	Query the relationship between two Actors from Blueprint.

Which Systems Does It Affect?

CommandDefinition can use team relationships to validate targets. Attack commands normally accept only hostile targets, while healing commands normally accept only friendly targets.

Tactical Assignment Sources and Filters can use team relationships to reduce candidates, such as allowing only friendly units to participate or selecting only hostile Actors as targets.

SquadSubsystem reads the relationship between a Squad and candidate Units during recruitment, regrouping, and team-based filtering.

GameplayDebugger displays team information to explain why a candidate was filtered out or why a command target was invalid.

Common Configuration Points

Entry Point	Purpose
`UGAIS_TeamAgentComponent`	GAIS default source of truth for team ID and the mirroring entry point.
`UGAIS_ProjectPolicy`	Project-level adapter for team queries, writes, and policy rules.
`UGAIS_DefaultProjectPolicy`	Default implementation used when no custom project policy is configured.
`UGAIS_DeveloperSettings.ProjectPolicyClass`	Selects the policy used by the current project.
`UGAIS_AIBlueprintHelperLibrary`	Blueprint helpers for TeamId, relationships, Blackboard, and navigation.

Usage Notes

Prefer one explicit team source of truth along the Pawn/Controller chain. If both Pawn and Controller have TeamAgent, the default rule is self-wins; the system does not merge values or emit an automatic warning. This prevents GAIS from rewriting project relationships, but it also means the project must avoid ambiguous dual sources.

TeamAgent and ProjectPolicy only solve identity lookup. They do not directly implement threat, perception, damage ownership, or faction UI. Those systems may read the same TeamId, but they should not silently write a second GAIS team source of truth.

Integrating an Existing Project Faction System

When the project already has a team source of truth, create a stateless UGAIS_ProjectPolicy subclass and select it in Settings. Override Resolve/Get/Set/Has TeamId so GAIS reads the project's existing Pawn, Controller, or interface state. Do not cache runtime Actors in the Policy CDO. The default lookup distinguishes Self, Controller, and Pawn TeamAgent/interface sources, and GetGenericTeamQuerySource can be used to debug which path actually matched.

When using GAIS TeamAgent, choose exactly one side of the Pawn/Controller chain as the real identity owner. Write it on the server through SetTeamId, then let replication and mirroring notify observers. If TeamAgent exists on both sides, self-wins and the values are not merged; the project architecture must prevent that ambiguity.

What to Read Next

For the integration workflow, see Integrate Team Identity and Affiliation. For field details, see Team Identity and Debugging Parameters. To connect a project faction system, override ProjectPolicy, listen for TeamId changes, or integrate GAS, read Team Identity and GAS Integration Extension Points. If team relationships cause Tactical Assignment filtering issues, read Troubleshooting Flows.

Table of contents