UE5-Modular-Game-Framework/docs/blueprints/03-interaction/21_BPC_ContextualTraversalSystem.md

BPC_ContextualTraversalSystem — Contextual Traversal System

Parent Class: ActorComponent Category: Interaction Target UE Version: 5.5–5.7 Build Phase: 2 — Interaction

---

1. Overview

BPC_ContextualTraversalSystem handles player traversal of environmental obstacles — vaulting, climbing, squeezing through gaps, sliding under obstacles. Uses motion warping and root motion for smooth traversal animations triggered by context-aware detection.

---

2. Enums

E_TraversalType

Value	Description
Vault	Vault over low obstacles
Mantle	Climb up onto ledges
Slide	Slide under low barriers
Squeeze	Squeeze through narrow gaps
LedgeGrab	Grab and hang from ledges

E_TraversalHeight

Value	Description
Low	Below knee height (step up)
Medium	Waist height (vault)
High	Chest height (mantle)

---

3. Variables

Variable	Type	Description
DetectionRange	float	Max distance to detect traversable surfaces
DetectionHalfAngle	float	Cone angle for forward detection
VaultHeightThreshold	float	Max height for vault vs mantle decision
TraversalSpeed	float	Speed multiplier during traversal anim
bIsTraversing	bool	Currently playing traversal animation
CurrentTraversalType	E_TraversalType	Active traversal type
MotionWarpingTarget	FVector	Target location for motion warping
TraversalCooldown	float	Min time between traversals

---

4. Functions

Function	Description
DetectTraversableObstacle	Performs forward trace to detect vault/mantle points
AttemptTraversal	Initiates traversal to detected point. Returns bool
ExecuteTraversal	Plays traversal montage with motion warping
OnTraversalComplete	Callback when montage finishes
CancelTraversal	Interrupts traversal (damage/player input)
IsTraversing	Returns bIsTraversing

---

5. Event Dispatchers

Dispatcher	Payload	Description
OnTraversalStarted	E_TraversalType Type, FVector Target	Traversal animation begins
OnTraversalComplete	E_TraversalType Type	Player reaches target position
OnTraversalFailed	FText Reason	Traversal attempt blocked

---

6. Dependencies & Communication

System	Relationship
BPC_MovementStateSystem	Movement mode override during traversal
BPC_CameraStateLayer	Camera FOV adjustment during traversal
BPC_StressSystem	Stress modifier for close-call traversals

---

7. Reuse Notes

• Uses UE5 Motion Warping for accurate target placement
• Detection uses capsule trace at player height ranges

---

8. Manual Implementation Guide

8.1 Class Setup

1. Create Blueprint Class: Parent = ActorComponent, Name = BPC_ContextualTraversalSystem
2. Add to Player Character
3. Enable Motion Warping plugin in Project Settings

8.2 Variable Initialization (BeginPlay)

Event BeginPlay
  ├─ Set bIsTraversing = false
  ├─ Set DetectionRange = 200.0  (cm)
  ├─ Set DetectionHalfAngle = 45.0  (degrees)
  ├─ Set VaultHeightThreshold = 120.0  (waist height in cm)
  ├─ Set TraversalSpeed = 1.0
  ├─ Set TraversalCooldown = 0.5
  ├─ Get Owner → Get Component by Class (BPC_MovementStateSystem) → Cache reference
  ├─ Get Owner → Find Component by Class (BPC_CameraStateLayer) → Cache reference
  └─ Get Owner → Cast to Character → Get CharacterMovement → Cache CMC reference

8.3 Function Implementations

DetectTraversableObstacle() → Hit Result, TraversalType, Height

[Function: DetectTraversableObstacle] (Pure)
  Step 1: Get Owner → Get Actor Location and Forward Vector
  Step 2: Three capsule traces at different heights:
    Trace A (Low: half-height = 30cm):
      Start: OwnerLocation + UpVector * 30
      End: Start + ForwardVector * DetectionRange
      Trace Channel: WorldStatic
    Trace B (Medium: half-height = 60cm):
      Same but offset by 60cm vertically
    Trace C (High: half-height = 90cm):
      Same but offset by 90cm vertically

  Step 3: For each trace that hits:
    Get Hit Actor → Get Hit Location → Get Hit Normal
    Calculate obstacle top: trace down from above obstacle to find top edge
    ObstacleHeight = topHit.Location.Z - bottomHit.Location.Z

  Step 4: Classify by height:
    ObstacleHeight <= 40cm → E_TraversalHeight::Low (step up)
    ObstacleHeight <= VaultHeightThreshold → E_TraversalHeight::Medium (vault)
    ObstacleHeight > VaultHeightThreshold → E_TraversalHeight::High (mantle)

  Step 5: Check clearance above obstacle (trace upward from top)
    If ceiling too low → cannot mantle → return invalid

  Step 6: Determine traversal type:
    - Low + no obstacle: just step (automatic)
    - Medium + clearance: Vault
    - High + ledge: Mantle
    - Narrow gap (sides): Squeeze
    - Low barrier with gap: Slide

  Step 7: Calculate landing position:
    Forward trace from obstacle top to find landing spot
    Set MotionWarpingTarget = landingPosition

  Step 8: Return HitResult, TraversalType, TraversalHeight struct

Nodes: Line Trace by Channel (x5+), Break Hit Result, Get Hit Location, Get Hit Normal, Vector Up/Down/Forward, Make Vector, Branch, Switch on E_TraversalHeight

AttemptTraversal(TraversalType, TargetLocation) → Boolean

[Function: AttemptTraversal]
  Step 1: Branch on bIsTraversing → If true, return false
  Step 2: Branch on CooldownActive → If cooldown timer active, return false
  Step 3: Query BPC_StateManager → IsActionPermitted("Action.Traverse")
    False → Fire OnTraversalFailed("Blocked by state"), return false

  Step 4: Set bIsTraversing = true
  Step 5: Set CurrentTraversalType = TraversalType
  Step 6: Notify BPC_MovementStateSystem → SetMovementMode(Vaulting, Forced)
  Step 7: Disable player input (optional — depends on traversal type)
  Step 8: Fire OnTraversalStarted(TraversalType, TargetLocation)

  Step 9: Call ExecuteTraversal(TraversalType, TargetLocation)
  Step 10: Return true

ExecuteTraversal(Type, Target) → void

[Function: ExecuteTraversal]
  Step 1: Switch on Type:
    Case Vault:
      - Play Montage: AM_Vault (from Animation Blueprint)
      - Add Motion Warping Target: "VaultTarget" → Target location
      - Root motion in montage moves character to Target
    Case Mantle:
      - Play Montage: AM_Mantle
      - Add Motion Warping Target: "MantleTop" → ledge top
      - Add Motion Warping Target: "MantleLand" → landing position
    Case Slide:
      - Play Montage: AM_Slide
      - Set capsule half-height to crouch height temporarily
      - Add Motion Warping Target: "SlideTarget"
    Case Squeeze:
      - Play Montage: AM_Squeeze
      - Add Motion Warping Target: "SqueezeTarget"
    Case LedgeGrab:
      - Play Montage: AM_LedgeGrab
      - Disable gravity temporarily
      - Attach to ledge point

  Step 2: On Montage Completed or Blending Out:
    Call OnTraversalComplete()

Nodes: Play Montage, Add or Update Motion Warping Target (name + location), Set Capsule Half Height, On Completed delegate

OnTraversalComplete() → void

[Function: OnTraversalComplete]
  Step 1: Set bIsTraversing = false
  Step 2: Restore capsule half-height (if modified)
  Step 3: Re-enable player input (if disabled)
  Step 4: Notify BPC_MovementStateSystem → restore previous movement mode
  Step 5: Start TraversalCooldown timer → set bCanTraverse = false
    On timer end → bCanTraverse = true
  Step 6: Fire OnTraversalComplete(CurrentTraversalType)

CancelTraversal() → void

[Function: CancelTraversal]
  Step 1: Branch on bIsTraversing → If false, return
  Step 2: Stop Montage (AM currently playing)
  Step 3: Set bIsTraversing = false
  Step 4: Restore movement mode, input, capsule height
  Step 5: Fire OnTraversalFailed("Cancelled")

8.4 Event Dispatcher Bindings

Bind to Dispatcher	Custom Event	Logic
IA_Jump (Pressed near obstacle)	OnTraversalInput	Call DetectTraversableObstacle → if valid: AttemptTraversal
BPC_MovementStateSystem.OnMovementModeChanged	CheckTraversalState	If in Vaulting mode and bIsTraversing false → force cancel

8.5 Blueprint Build Checklist

• Enable Motion Warping plugin
• Create BPC_ContextualTraversalSystem, add to Player Character
• Add all variables with defaults
• Create traversal montages: AM_Vault, AM_Mantle, AM_Slide, AM_Squeeze, AM_LedgeGrab
• Add Motion Warping notifies in montages at key frames
• Implement DetectTraversableObstacle with multi-height capsule traces
• Implement AttemptTraversal with state/cooldown checks
• Implement ExecuteTraversal with type-switch and motion warping targets
• Implement OnTraversalComplete cleanup
• Bind IA_Jump for traversal input
• Test: vault over low wall, mantle onto ledge, slide under barrier