Combat Roles

Coordinate multiple enemies with role slots, fitness scoring, and per-role action/movement/reaction sets.

Slot limits cap how many enemies attack at once. Fitness scoring fills open slots. A role change swaps ActionSet, ReactionSet, and movement profile.

When to Use This

• You run several enemies against one player and want staggered pressure.
• You want Soulslike-style turn-taking without scripting each swap by hand.
• One controller class should drive different archetypes (Attacker up front, Waiter at range) via tags.
• You tune difficulty by raising or lowering Attacker caps per target pool.

Built-in Roles

Project Settings: Slots and Timing

Role limits

Reassignment timing

• RoleReassignmentInterval (default 8 s): interval for EvaluateRoleDistribution. Set 0 and drive reassignment with ForceReassignment.
• MinTimeInRole (default 8 s): hysteresis window. If the AI is still in its current role and TimeInCurrentRole is below this value, the evaluator adds +0.3 to that role's adjusted fitness.
• bReevaluateTargetsOnReassignment: with two or more registered combat targets, re-run each AI's TargetSelector at the start of each timer tick, before role evaluation. Ignored with a single target. Per-enemy opt-out: bIgnoreTargetRedistribution on EnemyAIConfig.

EnemyAIConfig Setup

Combat role fields

Map roles to behavior assets

Register a Combat Target

UAICombatRoleSubsystem* Roles = GetWorld()->GetSubsystem<UAICombatRoleSubsystem>();
Roles->RegisterCombatTarget(PlayerPawn, /*bAutoAssignUnassigned=*/true);

• RegisterCombatTarget: adds the actor to the target pool.
  • bAutoAssignUnassigned: assigns unassigned combatants to this target (skips team-friendly pairs), then calls ForceReassignment and EvaluateRoleDistribution.
  • bReevaluateExisting: calls ReevaluateAllTargets() so assigned combatants re-run TargetSelector (honors bIgnoreTargetRedistribution).
• SetCombatTarget: deprecated; calls RegisterCombatTarget(NewTarget, true) with no bReevaluateExisting.
• AddCombatTarget: registers the target only. Use RegisterCombatTarget unless you own assignment yourself.

Runtime Flow

1. On possess, SECCombatControllerComponent resolves EnemyAIConfig from the pawn's IEnemyAIConfigProvider, else DefaultAIConfig.
2. With auto-register enabled, it calls UAICombatRoleSubsystem::RegisterCombatant (AAIController required).
3. The combatant receives a target from InitialTarget (runtime-only), TargetSelector, or the first target registered via RegisterCombatTarget.
4. With a target set, AssignRoleToNewCombatant slots the newcomer without reshuffling the whole pool.
5. Each RoleReassignmentInterval tick, EvaluateRoleDistribution groups by target, scores (AI, role) pairs, sorts by adjusted fitness then Priority, and greedily fills slots.
6. NotifyRoleChange calls SECCombatControllerComponent::HandleCombatRoleAssigned when present, replicates to SECCombatRoleComponent, and runs SyncStateForCombatRole.

When the Role Changes

1. HandleCombatRoleAssigned writes the tag to SECCombatRoleComponent on the pawn (replicated).
2. SyncStateForCombatRole pushes the matching action set, reaction set, and movement profile.

Client Role Visibility

• EnemyCharacterBase adds it by default.
• The server sets it in HandleCombatRoleAssigned via SetCombatRole.
• Clients read GetCombatRole() or bind OnCombatRoleChanged.
• SetCombatRole on clients returns without doing work.

Bosses and Opt-Out AI

Integration

// Enrage: allow three Attackers, then re-evaluate immediately
UAICombatRoleSubsystem* RoleSys = GetWorld()->GetSubsystem<UAICombatRoleSubsystem>();
RoleSys->SetRoleLimitOverride(
    USoulslikeEnemyCombatSettings::GetRoleAttacker(), 3);
RoleSys->ForceReassignment();