add blueprints

docs/blueprints/03-interaction/21_BPC_ContextualTraversalSystem.md

@@ -0,0 +1,88 @@
+# 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