Movement System

Tactical AI positioning with direction sampling, distance maintenance, strafing, and pawn avoidance.

Intelligent positioning that makes AI feel alive. Approaching, strafing, retreating, and avoiding obstacles without looking robotic.

When to Use This

• Any AI that needs tactical positioning around a target
• Melee enemies that maintain attack distance
• Ranged enemies that keep their distance
• Group AI where pawns need to avoid each other
• Boss fights with phase-based positioning changes

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

Core Concepts

Direction Sampling

• Distance to target: Does moving here get us closer to the ideal range?
• Angle to target: Are we facing the target?
• Avoidance: Is there a wall or another pawn in this direction?
• Positioning Rules: Custom modifiers you define (see below)

Distance Maintenance

Too Close      Comfort Zone      Too Far
   |-----------|=============|-----------|
   0        -tolerance    distance    +tolerance     inf
          (approach)     (strafe)     (retreat)

Strafing

• AutoStrafeSwap: Automatically changes direction when the opposite side scores significantly better
• Strafe Fatigue: After continuous strafing, the AI rests briefly (broadcasts OnStrafeResting)
• Threat-Triggered Swap: If configured, the AI swaps direction when the player stares at it. Set per MovementBehaviorProfile (requires Threat Detection)

Movement Layers

Quick Setup

Option 1: Use a Preset

// In your AI Controller's BeginPlay:
MovementEvaluator->ApplyBehaviorConfig(FMovementBehaviorConfig::MakeAttacker());

• MakeDefault(): Balanced defaults (400 cm, moderate rest)
• MakeAttacker(): Close-range aggressive (300 cm, minimal rest)
• MakeWaiter(): Far-range passive (600 cm, frequent rest)
• MakeFlanker(): Medium distance repositioning (400 cm, quick pauses)
• MakeSupporter(): Medium-far range (500 cm, moderate rest)
• MakeElite(): Aggressive, relentless pressure (350 cm, very short rest)

Option 2: Use a Data Asset

1. Create a MovementBehaviorProfile data asset (Right-click, Miscellaneous, Data Asset, MovementBehaviorProfile)
2. Configure desired distance, rest times, threat response, and positioning rules
3. Apply it:

MovementEvaluator->ApplyBehaviorProfile(MyProfile);

Option 3: Configure at Runtime

MovementEvaluator->SetDesiredDistance(350.f);
MovementEvaluator->SetStrafeSide(1);  // 1 = right, -1 = left

Option 4: Role-Based (Recommended)

1. Configure your EnemyAIConfig data asset.
2. Assign profiles to roles (e.g., Attacker gets Aggressive, Waiter gets Passive).
3. The SECCombatControllerComponent syncs automatically when the role changes.

// Called by SECCombatControllerComponent automatically when role changes:
MovementEvaluator->SyncForCombatRole(RoleTag, MyAIConfig);

Key Properties

Key Functions

// Main tick function - call from StateTree or Blueprint
EMovementEvaluatorResult EvaluateAndMove();
 
// Same as above, but with an explicit distance override
EMovementEvaluatorResult EvaluateAndMoveToDistance(float Distance);
 
// Apply a preset configuration
void ApplyBehaviorConfig(const FMovementBehaviorConfig& Config);
 
// Apply a data asset profile
void ApplyBehaviorProfile(const UMovementBehaviorProfile* Profile);
 
// Sync with AI Config (role-based switch)
bool SyncForCombatRole(const FGameplayTag& RoleTag, UEnemyAIConfig* AIConfig);
 
// Runtime adjustments
void SetDesiredDistance(float NewDistance);
void SetStrafeSide(int32 NewSide);  // 1 = right, -1 = left
void SwapStrafeSide();
void SetDistanceMultiplier(float Multiplier);  // E.g., from threat detection
 
// Movement suspension
void SuspendMovement(float Duration);
bool IsMovementSuspended();
 
 
// Queries
bool IsAtDesiredDistance();
bool IsStrafing();
float GetCurrentDistanceToTarget();
EMovementLayer GetCurrentMovementLayer();

Positioning Rules

UCLASS(Blueprintable)
class UMyFlankingRule : public UPositioningRule
{
    GENERATED_BODY()
 
    virtual float EvaluateDirection_Implementation(
        const FDirectionEvaluationContext& Context) const override
    {
        // Return -1.0 to +1.0
        //  +1.0 = strongly encourage this direction
        //   0.0 = no preference
        //  -1.0 = strongly discourage this direction
    }
};

• PreferredAngle = 0 - frontal assault
• PreferredAngle = 90 - flanking (side attacks)
• PreferredAngle = 180 - backstab positioning
• bAvoidInstead = true - invert the rule to avoid the angle instead

Events

Behavior Tree Tasks

Debug Tools

SEC.Debug.Movement.DrawScoring 1      // Visualize direction scores
SEC.Debug.Movement.DrawAvoidance 1    // Show avoidance radii
SEC.Debug.Movement.LogMovement 1      // Log basic movement state
SEC.Debug.Movement.LogStrafeSwap 1    // Log strafe swap decisions
SEC.Debug.Movement.LogStrafeState 1   // Log strafe state changes

MovementEvaluator->bDebugDrawScoring = true;
MovementEvaluator->bDebugDrawAvoidance = true;
MovementEvaluator->bDebugLogMovement = true;
MovementEvaluator->bDebugLogScoring = true;
MovementEvaluator->bDebugLogAvoidance = true;
MovementEvaluator->bDebugLogStrafeSwap = true;
MovementEvaluator->bDebugLogStrafeState = true;

Integration Points