Integrating Team Identity and Affiliation

Integrating Team Identity and Affiliation

The goal of team-identity integration is to make commands, Tactical Assignment, squad recruitment, and debugging all read TeamId through the same rules. First decide where the project's source of truth lives, then let GAIS access it through TeamAgent or ProjectPolicy.

Related documentation: see Team Identity and Project Policy for the feature overview, Team Identity and Debugging Parameters for fields, and Team Identity and GAS Integration Extension Points for customization.

1. Choose the Team Source of Truth

Choose only one source of truth in the Pawn/Controller chain:

• Pawn source: suitable when units change Controllers, AIControllers temporarily take control, or team identity should follow the character entity.
• Controller source: suitable when a player seat owns affiliation or Pawns change frequently.
• Project-owned source: suitable when the project already has an affiliation component, team service, GAS attribute, or save-game team data.

If both Pawn and Controller have UGAIS_TeamAgentComponent, the default policy uses self-wins lookup semantics. It neither merges nor warns. Avoiding ambiguity between two sources of truth is the project's responsibility.

2. Use GAIS TeamAgent

If the project does not already have a mature team system, add UGAIS_TeamAgentComponent to the chosen source-of-truth side, call SetTeamId on the server, and keep bApplyTeamIdToMirrors enabled as needed. TeamId replicates, and OnTeamIdChangedEvent / OnTeamIdChanged can drive UI, presentation, or diagnostics.

Mirroring exists only for compatibility. It can synchronize TeamId to the Owner, Controller, or objects implementing IGenericTeamAgentInterface, but a mirrored object should not become a second authoritative state.

3. Integrate an Existing Project Affiliation System

If the project already has a team component, affiliation table, or Controller-side TeamAgent, do not create a duplicate source of truth. Create a stateless subclass of UGAIS_ProjectPolicy, override ResolveTeamAgent, HasGenericTeamId, GetGenericTeamId, SetGenericTeamId, and GetGenericTeamQuerySource, then assign it in UGAIS_DeveloperSettings.ProjectPolicyClass.

Policy is used as a CDO, so do not cache runtime Actors or Components in it. Team identity must still be written on authority. Client UI may request a project RPC; the server validates permission and then calls SetGenericTeamId or writes through the project's own source of truth.

Validation Scenarios

1. Template-created squad: DefaultTeamId is applied only when the host has no team, after which TeamAgent/Policy can read it.
2. Atomic grouping of existing Actors: candidate Units and the Squad have the expected recruitment attitude; invalid candidates cause creation to return null or recruitment to fail.
3. Runtime team change: after the server calls SetTeamId or SetGenericTeamId, clients receive the replicated change and GameplayDebugger TeamSource still points to the expected source of truth.
4. Tactical Assignment: Team Attitude in the Target Filter separates allies and enemies according to project rules.

Validation

• HasGenericTeamId returns the expected result for ContextActor and TargetActor participating in Tactical Assignment.
• GetGenericTeamQuerySource explains whether team information came from Self, Controller, Pawn, Interface, or None.
• Team Attitude results in Target Filters match the project's affiliation rules.