104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# 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 |