# 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