add blueprints

docs/blueprints/03-interaction/22_BPC_PhysicsDragSystem.md

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