# **Ragdoll Physics Enhanced - Complete Guide**

## **📁 CONFIGURATION FILE (`RagdollPhysicsEnhanced.ini`)**

### **🔫 [WEAPON_FORCES] Section**
Controls how strong weapon impacts are on different body parts.

**Format:** `WEAPONTYPE_BODYPART = FORCE_VALUE`

**Weapon Types:**
- `PISTOL` - Handguns (Pistol, Combat Pistol, Heavy Pistol, etc.)
- `RIFLE` - Assault rifles, Carbines
- `SHOTGUN` - All shotgun types
- `SNIPER` - Sniper rifles
- `SMG`, `MG`, `EXPLOSIVE`, `MELEE`, `OTHER` - Other categories

**Body Parts:**
- `HEAD` - Head shots (most powerful)
- `TORSO` - Chest/stomach shots
- `PELVIS` - Hip/pelvis area
- `LEFT_ARM`/`RIGHT_ARM` - Arm shots
- `LEFT_LEG`/`RIGHT_LEG` - Leg shots

**Example Values:**
- `PISTOL_HEAD = 2.0` - Pistol headshot = 2.0 force units
- `SHOTGUN_HEAD = 5.0` - Shotgun headshot = 5.0 force units

**Force Scale:**
- `0.5-1.5` = Light push
- `1.5-3.0` = Noticeable ragdoll
- `3.0-6.0` = Strong ragdoll
- `6.0+` = Very strong (risk of physics issues)

---

### **🚗 [VEHICLE_FORCES] Section**
Controls vehicle impact forces based on speed.

**Format:** `SPEEDRANGE_BODYPART = FORCE_VALUE`

**Speed Ranges (mph):**
- `0_30` = 0-30 mph
- `31_60` = 31-60 mph
- `61_90` = 61-90 mph
- `91_120` = 91-120 mph
- `121_150` = 121-150 mph
- `151_180` = 151-180 mph
- `181_210` = 181-210 mph
- `211_240` = 211-240 mph
- `241_270` = 241-270 mph
- `271_300` = 271-300 mph
- `300_PLUS` = 300+ mph

**Example:**
- `0_30_HEAD = 1.0` - At 0-30 mph, head impact = 1.0 force
- `300_PLUS_HEAD = 30.0` - At 300+ mph, head impact = 30.0 force

---

### **🎯 [DIRECTION_MULTIPLIERS] Section**
Controls force direction for different impact types.

**Format:** `IMPACT_TYPE = X,Y,Z`

**XYZ Coordinates:**
- **X** = Left(-)/Right(+) direction
- **Y** = Backward(-)/Forward(+) direction  
- **Z** = Down(-)/Up(+) direction

**Weapon Multipliers:**
- `WEAPON_HEAD = 1.0,1.2,0.8`
  - Normal left/right (1.0)
  - **20% more backward** (1.2 = head snaps back)
  - **20% less upward** (0.8)
  
- `WEAPON_TORSO = 1.0,1.0,0.9`
  - Balanced force
  - Slightly less upward (0.9)

- `WEAPON_PELVIS = 1.0,0.9,1.1`
  - Slightly less backward (0.9)
  - **10% more upward** (1.1 = lifts hips)

- `WEAPON_LIMB = 0.9,0.9,0.8`
  - Reduced in all directions for arms/legs

**Vehicle Multipliers:**
- `VEHICLE_FRONT = 0.8,1.2,0.7`
  - Hit from front: less side, more back, less up

- `VEHICLE_SIDE = 1.2,0.8,0.6`
  - Hit from side: more side, less back, less up

- `VEHICLE_REAR = -0.8,0.5,0.5`
  - Hit from rear: pushes forward (-0.8X), some upward

---

### **⚙️ [PHYSICS_SETTINGS] Section**
Core physics and system settings.

**`RAGDOLL_DURATION_MS = 2000`**
- How long ragdoll lasts (milliseconds)
- 2000ms = 2 seconds
- Range: 500-5000ms (0.5-5 seconds)

**`FORCE_APPLICATION_DURATION_MS = 500`**
- How long continuous force is applied
- 500ms = 0.5 seconds of pushing
- Shorter = sharper impact, Longer = sustained push

**`ENABLE_LOGGING = true`**
- Logs events to `RagdollPhysicsEnhanced.log`
- `true` = Log enabled, `false` = No logging
- **Location:** Game folder (same as GTA5.exe)

**`DEBUG_MODE = true`**
- Enables debug features and visual markers
- `true` = Debug ON, `false` = Debug OFF
- Required for NumPad keys and visual feedback

**`MIN_VEHICLE_SPEED_MPH = 5`**
- Minimum vehicle speed to trigger ragdoll
- Below 5 mph = no ragdoll
- Prevents minor bumps from triggering effects

**`MAX_RAGDOLL_FORCE = 30.0`**
- **SAFETY LIMIT** - Maximum force allowed
- Forces above this are reduced automatically
- Prevents physics engine crashes

**`ENABLE_WEAPON_RAGDOLL = true`**
- Toggle weapon ragdolls ON/OFF
- `true` = Enabled, `false` = Disabled

**`ENABLE_VEHICLE_RAGDOLL = true`**
- Toggle vehicle ragdolls ON/OFF
- `true` = Enabled, `false` = Disabled

---

---
## **📝 LOG FILE (`RagdollPhysicsEnhanced.log`)**

### **Location:** Game folder (where GTA5.exe is)

### **Log Entries Include:**
```
[TIME] === Ragdoll Physics Enhanced Log Started ===
[TIME] Log file: .\RagdollPhysicsEnhanced.log
[TIME] Game version: 98
[TIME] SHVDN version: 3.7.0.73
[TIME] Configuration loaded successfully
[TIME] Bone to body part map built
[TIME] RagdollPhysicsEnhanced initialized successfully
[TIME] Weapon Impact: PISTOL -> HEAD (Bone: 31086) Force: 2.00
[TIME] Applied ragdoll force: WEAPON - Force: 2.40
[TIME] Vehicle Impact: Speed=45.3mph -> TORSO Force=1.40
[TIME] EXCEPTION in MethodName: Error message
[TIME] Stack Trace: Full stack trace
```

### **Error Types Logged:**
- Initialization errors
- Config loading errors
- Weapon/vehicle impact events
- Ragdoll application events
- Native call failures
- Exception stack traces

---

## **🛠️ TROUBLESHOOTING GUIDE**

### **Game Crashes When Shooting:**
1. Reduce `MAX_RAGDOLL_FORCE` to 15.0
2. Reduce all weapon forces by 50%
4. Check log for last entry before crash

### **Poor Performance:**
1. Reduce `RAGDOLL_DURATION_MS` to 1500
2. Set `ENABLE_LOGGING = false`
3. Set `DEBUG_MODE = false`
4. System auto-limits to 20 active ragdolls

### **Config Changes Not Applying:**
1. Press **F5** or **NumPad 4** to reload
2. Check INI file is in `scripts\` folder
3. Verify file format (no extra spaces)
4. Restart game if changes don't apply

---

## **⚡ PERFORMANCE TIPS**

### **For Best Performance:**
```
RAGDOLL_DURATION_MS = 1500
ENABLE_LOGGING = false
MAX_RAGDOLL_FORCE = 15.0
```

### **For Maximum Realism:**
```
RAGDOLL_DURATION_MS = 2500
ENABLE_LOGGING = true  (for debugging)
MAX_RAGDOLL_FORCE = 25.0
```

---

## **🎯 RECOMMENDED SETTINGS**

### **Casual Gameplay:**
- Weapon forces: 1.0-3.0 range
- Vehicle forces: 1.0-10.0 range
- Ragdoll duration: 1500ms
- Max force: 15.0

### **Realistic Simulation:**
- Weapon forces: 2.0-6.0 range  
- Vehicle forces: 2.0-20.0 range
- Ragdoll duration: 2000ms
- Max force: 25.0

### **Arcade/Over-the-top:**
- Weapon forces: 3.0-8.0 range
- Vehicle forces: 5.0-30.0 range
- Ragdoll duration: 3000ms
- Max force: 30.0 (MAX SAFE)

---

## **📊 FORCE CALCULATION FORMULA**

```
Final Force = Base Force × Direction Multiplier × Random Variation

Base Force = Weapon/Vehicle force from config
Direction Multiplier = XYZ values from direction config
Random Variation = ±10% random adjustment
```

**Example - Pistol Headshot:**
```
Base: 2.0 (PISTOL_HEAD)
Direction: (1.0, 1.2, 0.8)
Random: +5%
Final: (2.1, 2.52, 1.68)
Magnitude: √(2.1² + 2.52² + 1.68²) ≈ 3.68 force units
```

## **⚠️ SAFETY WARNINGS**

1. **NEVER** set `MAX_RAGDOLL_FORCE` above 30.0
2. **AVOID** weapon forces above 8.0
5. **CHECK** log file after crashes

---

## **🔧 CUSTOMIZATION GUIDE**

### **Want Stronger Headshots?**
Increase: `PISTOL_HEAD = 3.0`, `RIFLE_HEAD = 4.0`

### **Want Longer Ragdolls?**
Increase: `RAGDOLL_DURATION_MS = 3000`

### **Want More Dramatic Vehicle Hits?**
Increase vehicle forces by 50% across all ranges

### **Want Less Upward Force?**
Change: `WEAPON_HEAD = 1.0,1.2,0.6` (Z from 0.8 to 0.6)

### **Want Side Impacts to Throw Further?**
Change: `VEHICLE_SIDE = 1.5,0.8,0.6` (X from 1.2 to 1.5)

---

**Created for Ragdoll Physics Enhanced mod v1.0**
