Movement System

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

Tactical positioning that considers distance, angle, navmesh walkability, pawn avoidance, and custom rules on every tick.

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

Works independently of the other plugin systems.

Core Concepts

Direction Sampling

• Distance to target: how well the move serves the ideal range
• Angle to target: whether it faces the target
• Pawn avoidance: whether another AI sits in this direction
• Navmesh walkability: whether it leads off a ledge, into a wall, or onto a hazard (see Navmesh-Aware Sampling)
• 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: changes direction when the opposite side scores better
• Strafe Fatigue: the AI rests after continuous strafing (broadcasts OnStrafeResting)
• Threat-Triggered Swap: swaps direction when the player stares, if configured. Set per MovementBehaviorProfile (requires Threat Detection)

Movement Layers

Detour Escalation (Around Corners)

• Far detour (predictive): the route is much longer than the straight line. It engages when route / straight-line exceeds DetourEnterRatio (1.6) and route - straight-line exceeds DetourMinExcess (200 cm). The second gate lets the AI strafe past a thin pillar instead of pathfinding around it.
• Tight corner (reactive): the target is just past a corner, so the route is barely longer than straight and the ratio can't see it, yet local steering still can't round the corner and grinds the wall. When the AI wants to close on a target it can't see but isn't gaining ground (closing slower than DetourStallSpeed, 60 cm/s), it escalates. A pillar never trips this, because the AI keeps closing past it.

Tuning: if it paths around minor bumps, raise DetourEnterRatio or DetourMinExcess; if it still grinds a tight corner, raise DetourStallSpeed so a slower grind counts as stalled; if it pathfinds during a normal slow approach, lower DetourStallSpeed. SEC.Debug.Movement.LogMovement 1 logs Detour escalation ENGAGED / CLEARED, noting (stalled at cover) when the reactive path fired. Works under the StateTree, a Behavior Tree, or standalone, with no extra wiring.

Navmesh-Aware Sampling

Tuning tip: lower NavProbeDistance (try ~60) for tight arenas and corridors, where a long probe over-reports edges.

Hazard Areas

1. Create a Blueprint subclass of NavArea (e.g. NavArea_Lava) and give it a distinct draw color.
2. Drop a Nav Modifier Volume over the patch, set its Area Class to your hazard area, and rebuild navigation (press P to verify it tints).
3. On the movement component, add the area to Hazard Areas with an avoidance strength from 0 to 1: 0 ignores it, 1 treats it like a wall, ~0.75 routes around it but crosses when cornered.

A patch authored as NavArea_Null carves a hole in the navmesh, so the AI treats it as an impassable wall without a Hazard Areas entry. Use a walkable hazard area only when the AI should be able to cross it.

Evaluate-Only Mode (Root Motion)

// Read the chosen direction for a locomotion blendspace:
FVector   Dir   = MovementEvaluator->GetCurrentDirection();
float     Angle = MovementEvaluator->GetCurrentDirectionAngle();   // signed yaw: 0 ahead, +90 right, +/-180 behind
FVector2D Local = MovementEvaluator->GetCurrentDirectionLocal();   // (forward, right)

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();
 
// Root-motion direction output (Evaluate-Only mode)
FVector GetCurrentDirection();
float GetCurrentDirectionAngle(bool bRelativeToControlRotation = false);
FVector2D GetCurrentDirectionLocal();

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.DrawNav 1          // Show navmesh sample validity and the ledge guard
SEC.Debug.Movement.LogMovement 1      // Log discrete movement events (layer change, suspend/resume, pathfinding, stuck, detour)
SEC.Debug.Movement.LogTick 1          // Log the per-tick state dump (distance, error, speed)
SEC.Debug.Movement.LogScoring 1       // Log direction scoring details
SEC.Debug.Movement.LogAvoidance 1     // Log avoidance detection and scoring
SEC.Debug.Movement.LogStrafeSwap 1    // Log strafe swap decisions
SEC.Debug.Movement.LogStrafeState 1   // Log strafe state changes

Log LogMovementEvaluatorTick off

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

Integration Points