Combat Roles

Multi-enemy coordination with role-based behavior, slot management, and fitness evaluation.

Coordinating multiple enemies so they don't all attack at once. Some flank, some wait, some support.

When to Use This

• Any game with multiple enemies that should not all attack simultaneously
• Soulslike encounters where enemies take turns
• Group tactics with specialized roles (tank, flanker, support)
• Dynamic difficulty by adjusting how many attackers are allowed

This system can be used independently from the other plugin systems.

Core Concepts

The Role System

Slot Management

// In Project Settings > Plugins > Soulslike Enemy Combat:
RoleLimits:
  SEC.Role.Attacker  →  2    // Only 2 enemies attack at a time
  SEC.Role.Flanker   →  1    // One flanker
  // Unlisted roles are unlimited

Fitness Evaluation

// Built-in evaluators:
UDistanceRoleEvaluator    // Scores based on distance to target
UCooldownRoleEvaluator    // Scores based on action cooldown state (fatigue system)

Role-Based ActionSets

// In EnemyAIConfig:
DefaultActionSet:  DA_ActionSet_Attacker   // Fallback for unlisted roles
RoleActionSets:
  SEC.Role.Waiter   → DA_ActionSet_Patient
  SEC.Role.Flanker  → DA_ActionSet_Flanking

Quick Setup

1. Create an EnemyAIConfig

2. Configure Role Registration

3. Set Up Fitness Evaluators

FitnessEvaluators:
  - DistanceEvaluator
      RoleWeights: { SEC.Role.Attacker: 1.0, SEC.Role.Flanker: 0.5 }
      IdealDistance: 0          // Closer is better
      EffectiveRange: 2000     // Score drops to 0 at 2000cm
      ScoreMode: HigherIsBetter
 
  - CooldownEvaluator
      RoleWeights: { SEC.Role.Attacker: 1.0 }
      CurrentRolePenaltyMultiplier: 0.5  // Penalize staying in Attacker when on cooldown

4. Map Roles to ActionSets

bManageActionSetsAutomatically: true
DefaultActionSet: DA_ActionSet_Default
 
RoleActionSets:
  SEC.Role.Attacker  → DA_ActionSet_Aggressive
  SEC.Role.Waiter    → DA_ActionSet_Patient
  SEC.Role.Flanker   → DA_ActionSet_Flanking

bManageMovementProfilesAutomatically: true
DefaultMovementProfile: DA_MovementProfile_Default
 
RoleMovementProfiles:
  SEC.Role.Attacker → DA_MovementProfile_Aggressive
  SEC.Role.Waiter   → DA_MovementProfile_Passive

5. Assign to Enemy

How Role Assignment Works

1. Enemy spawns, controller possesses pawn
2. SECCombatControllerComponent resolves AIConfig
3. If bAutoRegisterForCombatRoles is true, registers with AICombatRoleSubsystem
4. Subsystem evaluates all registered enemies for each target pool
5. Fitness scores calculated per-evaluator, weighted per-role, combined via average
6. Roles assigned based on:
   - Slot availability (RoleLimits)
   - Fitness scores
   - Priority (tiebreaker)
   - Preferred role
   - Hysteresis (MinTimeInRole prevents rapid swapping)
7. ActionSet and MovementProfile synced via SECCombatRoleSyncLibrary
8. Re-evaluation happens on a timer (RoleReassignmentInterval)

Custom Fitness Evaluators

UCLASS(BlueprintType, meta = (DisplayName = "Visibility Evaluator"))
class UVisibilityRoleEvaluator : public URoleEvaluator
{
    GENERATED_BODY()
 
public:
    virtual float EvaluateFitness_Implementation(
        const FRoleEvaluationContext& Context) const override
    {
        // Context provides: Controller, Role, CurrentRole, TimeInCurrentRole
        // Access pawn via Context.Controller->GetPawn()
        // Return 0.0 (unfit) to 1.0 (perfect fit)
 
        if (!PlayerCanSeeMe(Context.Controller->GetPawn()))
            return 1.0f;  // Great flanker candidate
        return 0.3f;
    }
};

• Controller - The AI controller being evaluated (access pawn, components, etc. through this)
• Role - The role being considered
• CurrentRole - Currently assigned role
• TimeInCurrentRole - Seconds spent in current role (useful for stability bonuses)

• RoleWeights - TMap of role tag to influence weight. Roles not listed use InfluenceOnUnlistedRoles.
• ScoreMode - HigherIsBetter (default) or LowerIsBetter to invert the score.

Runtime Control & API

Blueprint Functions

• SetReassignmentInterval: Change how often the system re-evaluates roles.
• SetMinTimeInRole: Stop enemies from switching roles too quickly (hysteresis).
• SetRoleLimitOverride: Change the max number of actors allowed in a role.
  • Example: Allow 3 Attackers instead of 1 for an "Enrage" phase.
• ClearRoleLimitOverride / ClearAllRoleLimitOverrides: Reset limits back to project settings.
• UpdateConfig: Swap the entire configuration struct at runtime (with optional bLimitAttritionEnabled for soft updates).

• ForceAssignRole: Lock an AI into a specific role. Pass bLockRole = true to prevent the evaluation system from reassigning it.
  • Useful for: Scripted events where an enemy must wait or taunt.
• UnlockRole: Return the AI to the automatic evaluation pool.
• ForceReassignment: Trigger an immediate re-evaluation of all AI.
• PauseReassignment / ResumeReassignment: Freeze role changes during cutscenes or special sequences.

// Example: Enrage phase - Allow more attackers
UAICombatRoleSubsystem* RoleSys = GetWorld()->GetSubsystem<UAICombatRoleSubsystem>();
RoleSys->SetRoleLimitOverride(FGameplayTag::RequestGameplayTag("SEC.Role.Attacker"), 3);
RoleSys->ForceReassignment();

Multi-Target API

Delegates

OnCombatantsOrphaned fires when a target unregisters. The orphaned combatants have their roles reset to SEC.Role.None. Bind to this delegate to reassign them to a new target.

Role Syncing

Automatic Syncing (Default)

Manual Syncing (Custom Controllers)

• SyncAllForCombatRole: Updates both ActionSets and MovementProfiles.
• SyncActionSetForRole: Updates only the action set on the pawn's SECActionSetComponent.
• SyncMovementProfileForRole: Updates only the movement profile on the controller's MovementEvaluatorComponent.

// Inside your Custom Controller: On Role Changed Event
USECCombatRoleSyncLibrary::SyncAllForCombatRole(
    this,               // Controller
    GetPawn(),          // Pawn
    NewRoleTag,         // The new role
    MyEnemyAIConfig     // The config asset
);

Bosses and Non-Coordinated AI

1. Set bAutoRegisterForCombatRoles to false on the enemy's EnemyAIConfig
2. The AI will not be registered with the subsystem and will not consume any role slots
3. It can still use ActionSets and MovementProfiles, just not through role-based switching
4. Use ForceAssignRole with bLockRole = true if you still want to assign a role to a boss that is registered (e.g., for ActionSet/MovementProfile resolution), without the subsystem ever reassigning it

For enemies with bIgnoreTargetRedistribution = true on their config, the subsystem will not re-run their TargetSelector during periodic re-evaluation. This is useful for bosses or scripted AI that should always fight the same target.

Client-Side Role Visibility (SECCombatRoleComponent)

Setup

// In your custom character constructor:
CombatRoleComponent = CreateDefaultSubobject<USECCombatRoleComponent>(TEXT("CombatRoleComponent"));

How It Works

1. The server-side AICombatRoleSubsystem assigns a new role to a combatant
2. The subsystem notifies the AI controller via the OnCombatRoleChanged delegate
3. The controller (or StateTree) writes the role to the pawn's SECCombatRoleComponent via SetCombatRole()
4. The role tag replicates to all clients
5. Clients receive the OnCombatRoleChanged delegate on the component

Reading on Clients

// Get the component from any pawn reference
USECCombatRoleComponent* RoleComp = Pawn->FindComponentByClass<USECCombatRoleComponent>();
 
// Read the current role
FGameplayTag CurrentRole = RoleComp->GetCombatRole();
 
// React to changes
RoleComp->OnCombatRoleChanged.AddDynamic(this, &UMyWidget::OnRoleChanged);
 
void UMyWidget::OnRoleChanged(FGameplayTag NewRole, FGameplayTag OldRole)
{
    // Update role indicator icon, change outline color, etc.
}

This component is purely informational on the client side. Setting the role on clients is a no-op. Only the server can assign roles through the subsystem.

Integration Points