> For the complete documentation index, see [llms.txt](https://usin.gitbook.io/usin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://usin.gitbook.io/usin/other/handling-helper.md).

# Handling helper 🚗

A page dedicated to help people understand the handling.meta file.

{% hint style="info" %}

* `handlingName` must match the handling ID referenced from `vehicles.meta`.
* Tune one system at a time. Small changes compound quickly.
* Most normal cars only need `CHandlingData`; bikes, aircraft, boats, trailers, and special vehicles may also need `SubHandlingData`.
* The “good range” values below are starting points, not hard engine limits.
* `strModelFlags`, `strHandlingFlags`, and `strDamageFlags` are bitfields. Treat them separately from normal numeric tuning.
* For a normal add-on vehicle, preserve the original XML field order and only change values you understand.
  {% endhint %}

## 1. Core `CHandlingData`

### Identity and physical properties

| Parameter                | Type    | What it does                                                                       | Practical tuning notes                                                                    |
| ------------------------ | ------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `handlingName`           | string  | Unique handling ID linked from `vehicles.meta`.                                    | Vanilla IDs are typically uppercase. Keep it short and unique.                            |
| `fMass`                  | float   | Vehicle mass, mainly relevant during collisions with dynamic objects and vehicles. | Road cars: roughly `1000–2500`; trucks: much higher.                                      |
| `fInitialDragCoeff`      | float   | Aerodynamic drag. Higher drag reduces achievable top speed.                        | Typical road vehicles often sit roughly around `10–120`.                                  |
| `fDownforceModifier`     | float   | Adds speed-dependent downforce/grip.                                               | Increase carefully; excessive values create unrealistic high-speed cornering.             |
| `fPercentSubmerged`      | float   | Water submersion threshold before the vehicle begins floating behavior.            | Road vehicles commonly use values around `85`.                                            |
| `vecCentreOfMassOffset`  | vector3 | Moves center of mass from the model origin.                                        | `x`: right/left, `y`: forward/back, `z`: up/down. Lower `z` improves rollover resistance. |
| `vecInertiaMultiplier`   | vector3 | Resistance to rotation around each axis.                                           | Higher values make the car feel less twitchy and resist roll/pitch/yaw rotation.          |
| `fPetrolTankVolume`      | float   | Fuel-tank capacity used by FiveM’s optional fuel-consumption system.               | Set `0` for effectively infinite fuel / no fuel use.                                      |
| `fPetrolConsumptionRate` | float   | Per-vehicle fuel-use multiplier for FiveM fuel consumption.                        | FiveM defaults to `0.5` when omitted.                                                     |
| `fOilVolume`             | float   | Engine oil capacity.                                                               | Usually leave near donor vehicle values.                                                  |
| `nMonetaryValue`         | int     | Rockstar’s internal vehicle-value field.                                           | Usually cosmetic/gameplay metadata; rarely affects FiveM RP systems.                      |

`fMass`, drag, center of mass, and inertia are foundational physics values. Higher drag lowers top speed; a lower center of mass generally makes a vehicle more stable.

## 2. Drivetrain and acceleration

| Parameter                         | Type  | What it does                                 | Practical tuning notes                                              |
| --------------------------------- | ----- | -------------------------------------------- | ------------------------------------------------------------------- |
| `fDriveBiasFront`                 | float | Torque distribution.                         | `0.0` = RWD, `1.0` = FWD, values between = AWD. `0.5` is equal AWD. |
| `nInitialDriveGears`              | int   | Number of forward gears.                     | Typical cars: `5–8`; bikes often `5–6`.                             |
| `fInitialDriveForce`              | float | Wheel drive force / acceleration multiplier. | Most normal cars are around `0.10–0.40`; raise gradually.           |
| `fDriveInertia`                   | float | Engine rev responsiveness.                   | Higher = engine reaches redline faster.                             |
| `fClutchChangeRateScaleUpShift`   | float | Upshift speed multiplier.                    | Higher = faster gear changes. Avoid extreme values.                 |
| `fClutchChangeRateScaleDownShift` | float | Downshift speed multiplier.                  | Higher = faster downshifts.                                         |
| `fInitialDriveMaxFlatVel`         | float | Gearbox/redline-limited top-speed target.    | It does not guarantee the car can actually reach that speed.        |

#### Quick drivetrain presets

```xml
<!-- RWD -->
<fDriveBiasFront value="0.000000" />

<!-- Balanced AWD -->
<fDriveBiasFront value="0.500000" />

<!-- Front-biased AWD -->
<fDriveBiasFront value="0.600000" />

<!-- FWD -->
<fDriveBiasFront value="1.000000" />
```

`fDriveBiasFront`, gear count, drive force, drive inertia, shift multipliers, and max flat velocity collectively determine straight-line behavior.

## 3. Braking and steering

| Parameter         | Type  | What it does                         | Practical tuning notes                                                                          |
| ----------------- | ----- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `fBrakeForce`     | float | Overall braking-force multiplier.    | Higher = shorter braking distances, until traction becomes the limit.                           |
| `fBrakeBiasFront` | float | Front/rear brake-force distribution. | Around `0.55–0.70` is common for road cars. Higher can make the rear more stable under braking. |
| `fHandBrakeForce` | float | Handbrake strength.                  | Higher helps drifting/parking brake turns, but can feel binary.                                 |
| `fSteeringLock`   | float | Maximum steering angle.              | Higher improves low-speed turning but can make high-speed handling nervous.                     |

## 4. Tire grip and traction

| Parameter                   | Type  | What it does                                    | Practical tuning notes                                                                   |
| --------------------------- | ----- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `fTractionCurveMax`         | float | Peak available tire grip.                       | Raise for more ultimate grip.                                                            |
| `fTractionCurveMin`         | float | Grip available once the tire exceeds peak slip. | Lower difference from max = more predictable, less snappy breakaway.                     |
| `fTractionCurveLateral`     | float | Slip-angle behavior / lateral traction curve.   | Strongly affects cornering feel and breakaway character.                                 |
| `fTractionSpringDeltaMax`   | float | Maximum suspension/traction spring effect.      | Usually leave close to donor values unless tuning deeply.                                |
| `fLowSpeedTractionLossMult` | float | Additional traction loss at low speed.          | Raise for easier burnouts/drift initiation; lower for stronger launch grip.              |
| `fCamberStiffnesss`         | float | Camber-related grip response.                   | Usually best left near a proven donor vehicle. Note the field uses three `s` characters. |
| `fTractionBiasFront`        | float | Front/rear traction distribution.               | Higher biases grip toward front; lower biases grip toward rear.                          |
| `fTractionLossMult`         | float | Overall traction-loss multiplier.               | Higher = easier wheelspin/sliding; lower = more planted.                                 |

#### Fast diagnosis

| Symptom                                 | Try first                                                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Spins too easily under throttle         | Lower `fInitialDriveForce`; lower `fTractionLossMult`; reduce rearward traction bias.                           |
| Understeers heavily                     | Reduce `fTractionBiasFront`; slightly increase rear grip; reduce front-heavy brake bias if braking is involved. |
| Snaps suddenly into oversteer           | Bring `fTractionCurveMin` closer to `fTractionCurveMax`; lower `fTractionLossMult`.                             |
| Too much grip at 200+ km/h              | Reduce `fDownforceModifier` and/or `fTractionCurveMax`.                                                         |
| Cannot do burnouts or controlled slides | Increase `fLowSpeedTractionLossMult` and/or `fTractionLossMult`.                                                |

## 5. Suspension, anti-roll, and chassis balance

| Parameter                | Type  | What it does                        | Practical tuning notes                                                                  |
| ------------------------ | ----- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| `fSuspensionForce`       | float | Suspension spring strength.         | Higher = stiffer spring behavior.                                                       |
| `fSuspensionCompDamp`    | float | Compression damping.                | Higher = resists suspension compression more.                                           |
| `fSuspensionReboundDamp` | float | Rebound damping.                    | Higher = resists extension after compression.                                           |
| `fSuspensionUpperLimit`  | float | Maximum upward wheel travel.        | Usually negative/positive values follow donor setup.                                    |
| `fSuspensionLowerLimit`  | float | Maximum downward wheel travel.      | More travel can help off-road vehicles.                                                 |
| `fSuspensionRaise`       | float | Ride-height offset.                 | Positive raises; negative lowers. Excessive lowering can cause clipping or instability. |
| `fSuspensionBiasFront`   | float | Front/rear suspension distribution. | Changes how front and rear react to bumps/load transfer.                                |
| `fAntiRollBarForce`      | float | Anti-roll stiffness.                | Higher reduces body roll, but too high can create harsh or lift-off behavior.           |
| `fAntiRollBarBiasFront`  | float | Front/rear anti-roll distribution.  | More front bar tends toward understeer; more rear bar tends toward oversteer.           |
| `fRollCentreHeightFront` | float | Front roll-center height.           | Advanced chassis-balance setting.                                                       |
| `fRollCentreHeightRear`  | float | Rear roll-center height.            | Advanced chassis-balance setting.                                                       |

#### Suspension tuning order

1. Set ride height with `fSuspensionRaise`.
2. Set spring stiffness using `fSuspensionForce`.
3. Control bounce with compression and rebound damping.
4. Reduce body roll with `fAntiRollBarForce`.
5. Balance understeer/oversteer using anti-roll bias and roll-center heights.

## 6. Damage, deformation, and durability

| Parameter                | Type  | What it does                     | Practical tuning notes                            |
| ------------------------ | ----- | -------------------------------- | ------------------------------------------------- |
| `fCollisionDamageMult`   | float | Damage received from collisions. | Higher = more crash damage.                       |
| `fWeaponDamageMult`      | float | Damage received from weapons.    | Useful for armored or emergency vehicles.         |
| `fDeformationDamageMult` | float | Body deformation sensitivity.    | Higher = panels deform more easily.               |
| `fEngineDamageMult`      | float | Engine damage multiplier.        | Higher = engine fails sooner from impacts/damage. |

## 7. Seating and camera offsets

| Parameter          | Type  | What it does                     | Practical tuning notes                             |
| ------------------ | ----- | -------------------------------- | -------------------------------------------------- |
| `fSeatOffsetDistX` | float | Seat/camera lateral offset.      | Usually leave from donor.                          |
| `fSeatOffsetDistY` | float | Seat/camera forward/back offset. | Helpful when first-person seat position is wrong.  |
| `fSeatOffsetDistZ` | float | Seat/camera vertical offset.     | Helpful for vehicles with incorrect driver height. |

## 8. Flags and AI

| Parameter          | Type           | What it does                               |
| ------------------ | -------------- | ------------------------------------------ |
| `strModelFlags`    | flags/bitfield | Vehicle model behavior flags.              |
| `strHandlingFlags` | flags/bitfield | Physics/handling behavior flags.           |
| `strDamageFlags`   | flags/bitfield | Damage-system behavior flags.              |
| `AIHandling`       | enum/string    | AI driving behavior preset.                |
| `SubHandlingData`  | collection     | Vehicle-type-specific handling extensions. |

Do not randomly copy flags between unrelated vehicle types. Many special behaviors require matching vehicle/model flags, layouts, and subhandling definitions.

## 9. `CCarHandlingData` subhandling

Usually used for cars with special physics behavior such as wheelie cars, certain special vehicles, or advanced chassis effects.

| Parameter                              | What it does                                      |
| -------------------------------------- | ------------------------------------------------- |
| `fBackEndPopUpCarImpulseMult`          | Strength of rear-end lift / wheelie impulse.      |
| `fBackEndPopUpCarImpulseBias`          | Bias/timing for rear lift impulse.                |
| `fBackEndPopUpCarImpulseMaxDeltaSpeed` | Speed-change cap affecting the rear lift impulse. |
| `fToeFront`                            | Front toe angle behavior.                         |
| `fToeRear`                             | Rear toe angle behavior.                          |
| `fCamberFront`                         | Front camber.                                     |
| `fCamberRear`                          | Rear camber.                                      |
| `fCastor`                              | Steering caster behavior.                         |
| `fEngineResistance`                    | Additional engine resistance / drag behavior.     |
| `fMaxDriveBiasTransfer`                | Maximum drivetrain bias transfer.                 |
| `fJumpForceScale`                      | Jump-force multiplier for jump-capable vehicles.  |
| `fIncreasedRammingForceScale`          | Additional ramming-force multiplier.              |
| `fWeaponDamageScaledToVehicleSize`     | Scales weapon damage based on vehicle size.       |

## 10. `CBikeHandlingData` subhandling

Used by motorcycles and bicycles.

| Parameter                          | What it does                                  |
| ---------------------------------- | --------------------------------------------- |
| `fLeanFwdCOMMult`                  | Center-of-mass effect while leaning forward.  |
| `fLeanFwdForceMult`                | Force effect while leaning forward.           |
| `fLeanBakCOMMult`                  | Center-of-mass effect while leaning backward. |
| `fLeanBakForceMult`                | Force effect while leaning backward.          |
| `fMaxBankAngle`                    | Maximum normal leaning angle.                 |
| `fFullAnimAngle`                   | Lean angle used for full rider animation.     |
| `fDesLeanReturnFrac`               | How quickly bike returns toward desired lean. |
| `fStickLeanMult`                   | Steering-input lean multiplier.               |
| `fBrakingStabilityMult`            | Stability under braking.                      |
| `fInAirSteerMult`                  | Steering influence while airborne.            |
| `fWheelieBalancePoint`             | Target balance point during wheelies.         |
| `fStoppieBalancePoint`             | Target balance point during stoppies.         |
| `fWheelieSteerMult`                | Steering influence during wheelies.           |
| `fRearBalanceMult`                 | Rear balance influence.                       |
| `fFrontBalanceMult`                | Front balance influence.                      |
| `fBikeGroundSideFrictionMult`      | Side friction for bike chassis on ground.     |
| `fBikeWheelGroundSideFrictionMult` | Side friction for bike wheels on ground.      |
| `fBikeOnStandLeanAngle`            | Lean angle when parked on stand.              |
| `fBikeOnStandSteerAngle`           | Steering angle when parked on stand.          |
| `fJumpForce`                       | Bike jump-force strength.                     |
| `fMinJumpHeightForJump`            | Minimum jump height threshold.                |
| `fMinJumpHeightForJumpBike`        | Bike-specific jump-height threshold.          |
| `fJumpLandForce`                   | Force applied on landing.                     |

For normal road motorcycles, begin with a close vanilla donor bike rather than building bike handling from scratch.

## 11. `CBoatHandlingData` subhandling

Used by boats, amphibious vehicles, and water-capable special vehicles.

| Parameter                  | What it does                              |
| -------------------------- | ----------------------------------------- |
| `fBoxFrontMult`            | Front buoyancy-box multiplier.            |
| `fBoxRearMult`             | Rear buoyancy-box multiplier.             |
| `fBoxSideMult`             | Side buoyancy-box multiplier.             |
| `fSampleTop`               | Upper water-sampling position/value.      |
| `fSampleBottom`            | Lower water-sampling position/value.      |
| `fAquaplaneForce`          | Hydroplaning force.                       |
| `fAquaplanePushWaterMult`  | Water-push force multiplier.              |
| `fAquaplanePushWaterCap`   | Cap for water-push effect.                |
| `fAquaplanePushWaterApply` | Application factor for water-push effect. |
| `fRudderForce`             | Rudder steering force.                    |
| `fRudderOffsetSubmerge`    | Rudder submersion offset.                 |
| `fRudderOffsetForce`       | Rudder force offset.                      |
| `fRudderOffsetForceZMult`  | Vertical rudder-force multiplier.         |
| `fWaveAudioMult`           | Wave-audio intensity multiplier.          |
| `vecMoveResistance`        | Resistance to linear movement.            |
| `vecTurnResistance`        | Resistance to turning movement.           |
| `fLook_L_R_CamHeight`      | Camera-height behavior.                   |
| `fDragCoefficient`         | Water drag.                               |
| `fKeelSphereSize`          | Keel collision/buoyancy sphere size.      |
| `fPropRadius`              | Propeller radius.                         |
| `fLowLodAngOffset`         | Low-LOD angle offset.                     |
| `fLowLodDraughtOffset`     | Low-LOD draft offset.                     |
| `fImpellerOffset`          | Impeller position/offset.                 |
| `fImpellerForceMult`       | Impeller-force multiplier.                |
| `fDinghySphereBuoyConst`   | Dinghy buoyancy constant.                 |
| `fProwRaiseMult`           | Bow lift multiplier.                      |
| `fTransmissionMultiplier`  | Boat transmission multiplier.             |
| `fTractionMultiplier`      | Boat traction multiplier.                 |

## 12. `CFlyingHandlingData` subhandling

Used by aircraft, helicopters, and some special flying vehicles.

| Parameter           | What it does                              |
| ------------------- | ----------------------------------------- |
| `fThrust`           | Base propulsion thrust.                   |
| `fThrustFallOff`    | How thrust declines with speed.           |
| `fThrustVectoring`  | Thrust-vectoring influence.               |
| `fYawMult`          | Yaw responsiveness.                       |
| `fYawStabilise`     | Yaw stabilization.                        |
| `fSideSlipMult`     | Side-slip response.                       |
| `fRollMult`         | Roll responsiveness.                      |
| `fRollStabilise`    | Roll stabilization.                       |
| `fPitchMult`        | Pitch responsiveness.                     |
| `fPitchStabilise`   | Pitch stabilization.                      |
| `fFormLiftMult`     | Body/form lift multiplier.                |
| `fAttackLiftMult`   | Lift from angle of attack.                |
| `fAttackDiveMult`   | Dive force from angle of attack.          |
| `fGearDownDragV`    | Drag with landing gear deployed.          |
| `fGearDownLiftMult` | Lift behavior with landing gear deployed. |
| `fWindMult`         | Wind-effect multiplier.                   |
| `fMoveRes`          | Linear movement resistance.               |
| `vecTurnRes`        | Rotational resistance.                    |
| `vecSpeedRes`       | Speed-resistance vector.                  |

Aircraft handling is highly interconnected. Use a known aircraft donor and change thrust, lift, and response multipliers in small increments.

## 13. `CTrailerHandlingData` subhandling

Used for trailers and trailer-like vehicles.

| Parameter            | What it does                          |
| -------------------- | ------------------------------------- |
| `fAttachLimit`       | Attachment/connection limit behavior. |
| `fAttachStrength`    | Strength of trailer attachment.       |
| `fAttachMaxDistance` | Maximum attachment distance.          |
| `fCameraDistance`    | Trailer camera distance.              |

## 14. `CSpecialFlightHandlingData` subhandling

Used by special aircraft/VTOL-style vehicles.

| Parameter            | What it does                      |
| -------------------- | --------------------------------- |
| `vecAngularDamping`  | Angular damping vector.           |
| `vecLinearDamping`   | Linear damping vector.            |
| `fLiftCoefficient`   | Lift coefficient.                 |
| `fMinLiftVelocity`   | Minimum velocity needed for lift. |
| `fDragCoefficient`   | Flight drag coefficient.          |
| `fMaxLiftVelocity`   | Velocity cap for lift behavior.   |
| `fThrustCoefficient` | Thrust coefficient.               |
| `fHorizontalDamping` | Horizontal damping.               |
| `fVerticalDamping`   | Vertical damping.                 |

## 15. Useful tuning recipes

### Make a car less likely to flip

```xml
<vecCentreOfMassOffset x="0.000000" y="0.000000" z="-0.150000" />
<fAntiRollBarForce value="0.850000" />
<fSuspensionForce value="2.200000" />
<fRollCentreHeightFront value="0.250000" />
<fRollCentreHeightRear value="0.250000" />
```

Also consider slightly increasing `vecInertiaMultiplier` on the roll/yaw-related axes.

### Add realistic acceleration without making the car uncontrollable

```xml
<fInitialDriveForce value="0.310000" />
<fDriveInertia value="0.950000" />
<fClutchChangeRateScaleUpShift value="2.500000" />
<fClutchChangeRateScaleDownShift value="2.300000" />
<fLowSpeedTractionLossMult value="0.900000" />
```

### Make a car more drift-friendly

```xml
<fDriveBiasFront value="0.000000" />
<fTractionCurveMax value="2.300000" />
<fTractionCurveMin value="1.900000" />
<fLowSpeedTractionLossMult value="1.250000" />
<fTractionLossMult value="1.100000" />
<fHandBrakeForce value="1.100000" />
<fAntiRollBarBiasFront value="0.450000" />
```

### Add high-speed stability

```xml
<fDownforceModifier value="1.500000" />
<fSteeringLock value="34.000000" />
<fTractionCurveMax value="2.700000" />
<fTractionCurveMin value="2.400000" />
<vecCentreOfMassOffset x="0.000000" y="0.000000" z="-0.080000" />
```

## 16. FiveM runtime handling notes

Common native field group names:

```lua
-- Core handling fields
GetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fInitialDriveForce')
GetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fPetrolTankVolume')

-- Per-vehicle override
SetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fInitialDriveForce', 0.32)

-- Global override for a handling name
SetHandlingFloat('ADDER', 'CHandlingData', 'fInitialDriveForce', 0.32)
```

Use runtime overrides sparingly. They can conflict with other resources, may be reset when a vehicle streams/rebuilds, and do not replace having correct baseline values in `handling.meta`.

## 17. Minimal normal-car template

```xml
<Item type="CHandlingData">
  <handlingName>USINEXAMPLE</handlingName>

  <fMass value="1500.000000" />
  <fInitialDragCoeff value="7.500000" />
  <fDownforceModifier value="1.000000" />
  <fPercentSubmerged value="85.000000" />

  <vecCentreOfMassOffset x="0.000000" y="0.000000" z="-0.080000" />
  <vecInertiaMultiplier x="1.000000" y="1.300000" z="1.500000" />

  <fDriveBiasFront value="0.000000" />
  <nInitialDriveGears value="6" />
  <fInitialDriveForce value="0.280000" />
  <fDriveInertia value="1.000000" />
  <fClutchChangeRateScaleUpShift value="2.500000" />
  <fClutchChangeRateScaleDownShift value="2.300000" />
  <fInitialDriveMaxFlatVel value="170.000000" />

  <fBrakeForce value="0.850000" />
  <fBrakeBiasFront value="0.620000" />
  <fHandBrakeForce value="0.700000" />
  <fSteeringLock value="35.000000" />

  <fTractionCurveMax value="2.450000" />
  <fTractionCurveMin value="2.180000" />
  <fTractionCurveLateral value="22.500000" />
  <fTractionSpringDeltaMax value="0.150000" />
  <fLowSpeedTractionLossMult value="0.900000" />
  <fCamberStiffnesss value="0.000000" />
  <fTractionBiasFront value="0.490000" />
  <fTractionLossMult value="1.000000" />

  <fSuspensionForce value="2.200000" />
  <fSuspensionCompDamp value="1.350000" />
  <fSuspensionReboundDamp value="2.100000" />
  <fSuspensionUpperLimit value="0.100000" />
  <fSuspensionLowerLimit value="-0.120000" />
  <fSuspensionRaise value="0.000000" />
  <fSuspensionBiasFront value="0.500000" />

  <fAntiRollBarForce value="0.800000" />
  <fAntiRollBarBiasFront value="0.500000" />
  <fRollCentreHeightFront value="0.250000" />
  <fRollCentreHeightRear value="0.250000" />

  <fCollisionDamageMult value="1.000000" />
  <fWeaponDamageMult value="1.000000" />
  <fDeformationDamageMult value="0.800000" />
  <fEngineDamageMult value="1.250000" />

  <fPetrolTankVolume value="65.000000" />
  <fOilVolume value="5.000000" />

  <fSeatOffsetDistX value="0.000000" />
  <fSeatOffsetDistY value="0.000000" />
  <fSeatOffsetDistZ value="0.000000" />

  <nMonetaryValue value="50000" />
  <strModelFlags>440010</strModelFlags>
  <strHandlingFlags>0</strHandlingFlags>
  <strDamageFlags>0</strDamageFlags>
  <AIHandling>SPORTS_CAR</AIHandling>

  <SubHandlingData>
    <Item type="NULL" />
  </SubHandlingData>
</Item>
```