# BPC_PhysicsDragSystem — Physics Drag System

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

---

## 1. Overview

`BPC_PhysicsDragSystem` allows the player to grab and physically drag rigid-body objects in the world. Supports grab-at-distance, hold-to-grab with physics constraints, object rotation, and throw mechanics. Integrates with the interaction detector for grab targeting.

---

## 2. Enums

### `E_DragMode`

| Value | Description |
|-------|-------------|
| `PhysicsConstraint` | Attaches object via physics constraint to player hand |
| `Kinematic` | Sets object to kinematic and parents to hand |
| `Magnetic` | Objects smoothly lerp toward grab point |

---

## 3. Variables

| Name | Type | Description |
|------|------|-------------|
| `DragMode` | `E_DragMode` | Current drag physics mode |
| `GrabbedObject` | `AActor*` | Currently held actor |
| `ConstraintComp` | `UPhysicsConstraintComponent*` | Physics constraint for held object |
| `GrabDistance` | `float` | Max distance to grab (cm) |
| `HoldDistance` | `float` | Distance object is held from camera |
| `ThrowForce` | `float` | Impulse applied on release |
| `RotationSpeed` | `float` | Degrees/sec for object rotation input |
| `bCanThrow` | `bool` | Object can be thrown on release |
| `bIsGrabbing` | `bool` | Currently holding an object |

---

## 4. Functions

| Function | Description |
|----------|-------------|
| `GrabObject` | Attempts to grab targeted physics object. Returns bool. |
| `ReleaseObject` | Releases held object, applies throw force if bCanThrow. |
| `RotateObject` | Rotates held object by input axis values |
| `SetHoldDistance` | Adjusts distance of held object from camera |
| `GetGrabbedObject` | Returns currently held actor (or null) |
| `IsGrabbing` | Returns `bIsGrabbing` |

---

## 5. Event Dispatchers

| Dispatcher | Payload | Description |
|------------|---------|-------------|
| `OnObjectGrabbed` | `AActor* GrabbedObject` | Object successfully grabbed |
| `OnObjectReleased` | `AActor* ReleasedObject`, `bool bWasThrown` | Object released |
| `OnGrabFailed` | `FText FailReason` | Grab attempt failed |

---

## 6. Blueprint Flow

```
GrabObject:
  → Get targeted object from InteractionDetector
  → Check if object has physics simulation enabled
  → If DragMode == PhysicsConstraint:
      → Create physics constraint between hand socket and object
      → Set constraint limits (linear + angular)
  → If DragMode == Kinematic:
      → Set object simulated physics to false
      → Attach to hand socket
  → Set bIsGrabbing = true
  → Broadcast OnObjectGrabbed

ReleaseObject:
  → If bCanThrow → Apply forward impulse * ThrowForce
  → Destroy constraint / detach
  → Re-enable physics on object
  → Set bIsGrabbing = false
  → Broadcast OnObjectReleased
```

---

## 7. Dependencies & Communication

| System | Relationship |
|--------|--------------|
| `BPC_InteractionDetector` | Provides grab target via focus |
| `BPC_CameraStateLayer` | Camera direction for throw vector |
| `BPC_MovementStateSystem` | Speed modifier while carrying objects |

---

## 8. Reuse Notes
- Physics drag uses UE5 physics constraint system for realistic object handling
- Objects must have `Simulate Physics = true` and `Mass` configured