Reference

handling.meta

Every field that decides how a vehicle drives — mass, drivetrain, grip, suspension, damage — and what changing it actually does on the road.

How handling works

A handling entry is one <Item type="CHandlingData"> inside <HandlingData>. The vehicle is linked to it by the handlingId field in vehicles.meta — the file name does not matter, the id does.

The engine reads these values once when the model is loaded. Editing the file while the server runs changes nothing until the resource is restarted and the client re-streams the vehicle.

Two rules save a lot of time. First, change one value at a time and drive after each change — most fields interact, and a car that feels wrong usually has two fields fighting each other. Second, stock Rockstar vehicles are the best reference you have: find one that weighs and drives close to what you want, and start from its numbers instead of from zero.

Minimal skeleton

<?xml version="1.0" encoding="UTF-8"?>
<CHandlingDataMgr>
  <HandlingData>
    <Item type="CHandlingData">
      <handlingName>MYCAR</handlingName>
      <fMass value="1400.000000" />
      <!-- … -->
      <SubHandlingData>
        <Item type="CCarHandlingData">
          <!-- … -->
        </Item>
      </SubHandlingData>
    </Item>
  </HandlingData>
</CHandlingDataMgr>

Mass, drag and balance

These four fields set the physical body the rest of the file acts on. Get them wrong and no amount of grip tuning will make the car feel right.

Name	Type	Description	Typical
fMass	kg	Weight of the vehicle. Drives inertia, collision behaviour and how the suspension is loaded. A heavy car resists direction changes and pushes other traffic instead of bouncing off it. This is the single most influential value in the file.	1200–1900 (car), 200–350 (bike), 4000+ (truck)
fInitialDragCoeff	float	Aerodynamic drag. Higher values cut top speed and make the car decelerate faster when you lift off. It is the usual way to cap a top speed without touching engine power.	5.0–12.0
fDownforceModifier	multiplier	Scales downforce with speed, pressing the car onto the road as it goes faster. Above 1.0 the car gains high-speed stability and cornering grip. Only meaningful once the car is actually moving fast.	1.0 (stock), 1.5–3.0 (track cars)
fPercentSubmerged	percent	How deep the vehicle sits before it floats. Lower values make it buoyant, higher values sink it. Leave it alone unless the vehicle is meant to go in water.	85
vecCentreOfMassOffset	x y z, metres	Moves the centre of mass relative to the model origin. Y forward/back changes understeer versus oversteer; Z is the big one — lowering it makes the car far less likely to roll over. Raising Z is the fastest way to make a vehicle tip on corners.	x 0.0, y 0.0 to 0.3, z -0.1 to 0.2
vecInertiaMultiplier	x y z	Scales resistance to rotation on each axis. X is pitch (nose dive under braking), Y is roll (body lean), Z is yaw (how eagerly the car rotates into a corner). Lower Z makes the car feel darty, higher Z makes it feel long and stable.	1.0 1.0 1.0

Engine and drivetrain

Acceleration in GTA V is the product of fInitialDriveForce, fDriveInertia and the gear count. Top speed is set by fInitialDriveMaxFlatVel and then pulled back down by drag.

Name	Type	Description	Typical
fDriveBiasFront	0.0–1.0	Power split. 0.0 is rear-wheel drive, 1.0 is front-wheel drive, anything between is all-wheel drive with that share going to the front. 0.5 is an even split.	0.0, 0.5, 1.0
nInitialDriveGears	integer	Number of forward gears. More gears means shorter, closer ratios and quicker acceleration for the same top speed. The engine spreads ratios automatically — you cannot set them individually.	5–8
fInitialDriveForce	float	Raw engine torque. The main acceleration control. Increasing it beyond what the tyres can handle just produces wheelspin, so it has to move together with `fTractionCurveMax`.	0.10–0.35
fDriveInertia	float	How quickly the engine revs. Higher values reach the redline faster, which shortens each gear and sharpens throttle response. Very high values make the car feel twitchy and hard to modulate.	0.8–1.2
fClutchChangeRateScaleUpShift	float	Upshift speed. Higher is a faster shift with less time off power — this is how you get a dual-clutch feel. Low values give a slow, lazy automatic.	1.0–3.0
fClutchChangeRateScaleDownShift	float	Same thing for downshifts, including the ones triggered by braking into a corner.	1.0–3.0
fInitialDriveMaxFlatVel	km/h	Engine speed at the redline in top gear. This is not the final top speed: drag and terrain pull the real figure down, usually to around 80–90% of this number.	150–260

Brakes and steering

Name	Type	Description	Typical
fBrakeForce	float	Braking power. High values lock the wheels and trigger the ABS-like slide the engine simulates, so raising this past the grip available makes braking distances worse, not better.	0.6–1.2
fBrakeBiasFront	0.0–1.0	Front/rear brake split. Above 0.5 the front locks first and the car pushes straight on. Below 0.5 the rear locks first and the car rotates — useful for a playful feel, dangerous past about 0.4.	0.45–0.60
fHandBrakeForce	float	Rear handbrake power. Controls how easily the car breaks traction for a slide. Very high values make the rear snap round instantly.	0.5–5.0
fSteeringLock	degrees	Maximum steering angle at the wheels. Higher values turn tighter and feel more responsive but make the car nervous at speed. This also visibly changes how far the front wheels turn.	35–45 (car), 45+ (drift setups)

Traction and grip

The traction curve is the heart of how a car feels. fTractionCurveMax is the peak grip the tyre can produce; fTractionCurveMin is the grip left once it has slipped past that peak. The gap between the two decides whether a slide is progressive and catchable or sudden and terminal.

Name	Type	Description	Typical
fTractionCurveMax	float	Peak lateral grip — cornering speed. The higher it is, the more the car sticks. Raise it together with engine power, or the car will simply spin its wheels.	1.8–2.6
fTractionCurveMin	float	Grip once the tyre is sliding. Close to Max gives a forgiving car that recovers from a slide. Far below Max gives a snappy car that lets go abruptly. Never set it above Max.	1.6–2.4
fTractionCurveLateral	degrees	Slip angle at which peak grip happens. Higher values let the car run a wider slide angle before losing grip — the field drift setups live on.	17–25
fTractionSpringDeltaMax	metres	How far a wheel can leave the ground before it stops producing grip. Larger values keep grip over bumps and kerbs.	0.10–0.20
fLowSpeedTractionLossMult	float	Grip loss when pulling away from a standstill. 0.0 means the car launches cleanly with no wheelspin; higher values give a muscle-car struggle off the line.	0.0–1.5
fCamberStiffnesss	float	Effect of wheel camber on grip. Almost always left at 0. Note the triple "s" — that is the real spelling in the file, and a typo here silently drops the value.	0.0
fTractionBiasFront	0.0–1.0	Front/rear grip split. Above 0.5 the front has more grip and the car oversteers; below 0.5 the rear grips more and the car understeers. Stay near 0.5 — small changes matter a lot here.	0.47–0.52
fTractionLossMult	float	How much grip is lost on poor surfaces — wet roads, dirt, grass. Higher values make the vehicle far worse off-tarmac.	0.5–1.5

Suspension and roll

Name	Type	Description	Typical
fSuspensionForce	float	Spring stiffness. Higher values hold the body up harder and resist compression. Too high and the car skips over bumps instead of absorbing them.	1.0–3.0
fSuspensionCompDamp	float	Damping while the suspension compresses. Controls how much the body dives under braking and squats under acceleration.	1.0–2.5
fSuspensionReboundDamp	float	Damping while the suspension extends again. Too low and the car floats and bounces after a bump; too high and it feels locked down and skittish.	1.0–3.0
fSuspensionUpperLimit	metres	How far the wheel can travel upward into the arch. Visual and physical travel limit.	0.10–0.20
fSuspensionLowerLimit	metres	How far the wheel can drop below rest. Usually a negative value.	-0.10 to -0.20
fSuspensionRaise	metres	Shifts the whole body up or down relative to the wheels. This is the field for ride height — negative values slam the car. Push it too far and the wheels clip through the arches.	-0.05 to 0.05
fSuspensionBiasFront	0.0–1.0	Front/rear split of suspension force. Above 0.5 stiffens the front, below 0.5 stiffens the rear.	0.5
fAntiRollBarForce	float	Resistance to body roll in corners. Higher values keep the car flat, which helps grip but transmits bumps from one side to the other.	0.5–2.0
fAntiRollBarBiasFront	0.0–1.0	Front/rear split of anti-roll force. Shifts the balance between understeer and oversteer.	0.5
fRollCentreHeightFront	float	Height of the front roll axis. Higher values reduce visible body roll at the front but make weight transfer more abrupt.	0.0–0.5
fRollCentreHeightRear	float	Same for the rear axle.	0.0–0.5

Damage and durability

Name	Type	Description	Typical
fCollisionDamageMult	multiplier	Mechanical damage taken from impacts. 0.0 makes the vehicle mechanically indestructible in crashes.	0.5–1.5
fWeaponDamageMult	multiplier	Damage taken from gunfire and explosions.	1.0
fDeformationDamageMult	multiplier	How much the bodywork visually crumples. Purely cosmetic — separate from mechanical damage. Set to 0.0 for a car that never dents.	0.5–1.5
fEngineDamageMult	multiplier	How quickly the engine degrades and eventually dies. High values mean a few hard hits will stop the car.	1.0–2.0
fPetrolTankVolume	litres	Fuel volume. Affects how long the vehicle leaks and burns after the tank is hit, and how big the resulting fire is.	40–90
fOilVolume	litres	Oil volume. Controls the oil leak trail after engine damage.	3–7
fSeatOffsetDistX	metres	Sideways shift of the driver and passengers relative to the seat bones.	0.0
fSeatOffsetDistY	metres	Forward/backward shift of the occupants.	0.0
fSeatOffsetDistZ	metres	Vertical shift of the occupants. Useful when hands do not reach the steering wheel.	0.0
nMonetaryValue	integer	In-game value of the vehicle. Used by insurance and some economy scripts; has no effect on driving.	20000–150000

Flag fields

Three fields take hexadecimal bitmasks. They are written as plain hex strings, and several flags can be combined by OR-ing their values together.

Name	Type	Description	Typical
strModelFlags	hex	Model behaviour — whether the vehicle can be a getaway car, has a hydraulic setup, spawns with a specific body state, and so on.	—
strHandlingFlags	hex	Driving behaviour switches such as forcing ABS, disabling the handbrake, or enabling the special drift-friendly behaviours.	—
strDamageFlags	hex	How the vehicle breaks apart — which panels detach, whether doors can be ripped off.	—
AIHandling	enum	Driving profile used by NPC drivers. Accepts AVERAGE, SPORTS_CAR, TRUCK or CRAP. Ignored when a player is driving.	AVERAGE

SubHandlingData

The <SubHandlingData> block holds one or more typed items that extend the base data. Cars use CCarHandlingData; other vehicle types have their own blocks. An empty or missing block is valid — the vehicle just uses defaults.

CCarHandlingData

Name	Type	Description
fBackEndPopUpCarImpulseMult	float	How much the rear lifts when the vehicle hits another car.
fBackEndPopUpBuildingImpulseMult	float	Same, for impacts against world geometry.
fBackEndPopUpMaxDeltaSpeed	float	Caps how violent that rear-lift reaction can get.
fToeFront	float	Front wheel toe angle. Positive toes the wheels in for straight-line stability, negative toes them out for sharper turn-in.
fToeRear	float	Rear wheel toe angle. Strongly affects stability under power.
fCamberFront	float	Front camber. Negative values lean the top of the wheel inward — visible on the model.
fCamberRear	float	Rear camber, same convention.
fCastor	float	Castor angle. Affects self-centring of the steering and straight-line stability.
fEngineResistance	float	Engine braking. Higher values slow the car more sharply when you lift off the throttle.
fMaxDriveBiasTransfer	float	On all-wheel-drive setups, how much power can shift between axles when a wheel loses grip.
fJumpForceScale	float	Strength of the vehicle jump ability, when the vehicle has one.
strAdvancedFlags	hex	Extra behaviour bitmask, used for things like hydraulics and special suspension modes.

Other SubHandlingData types

Name	Description
CBikeHandlingData	Lean angles, wheelie and stoppie behaviour, rider balance.
CBoatHandlingData	Hull rise, aquaplaning, prop force and water resistance.
CFlyingHandlingData	Lift, drag, yaw/pitch/roll rates. Used by planes and helicopters.
CSeaPlaneHandlingData	Water-landing behaviour on top of the flying block.
CSubmarineHandlingData	Dive rate, turn speed and depth limits.
CTrailerHandlingData	Attach point stiffness and swing damping for towed units.
CSpecialFlightHandlingData	Hover and transforming vehicle behaviour.

Practical recipes

Common goals and the fields that actually get you there, in the order worth trying.

Symptom to field

Name	Description
Car rolls over in corners	Lower the Z of vecCentreOfMassOffset first. Then raise fAntiRollBarForce.
Understeers, will not turn in	Raise fSteeringLock, then move fTractionBiasFront slightly above 0.5.
Snaps into a spin without warning	Raise fTractionCurveMin closer to fTractionCurveMax, and raise fTractionCurveLateral.
Too fast on top end	Lower fInitialDriveMaxFlatVel, or raise fInitialDragCoeff to keep the acceleration.
Slow off the line but fast later	Raise fInitialDriveForce and fDriveInertia; lower fLowSpeedTractionLossMult.
Floats and bounces after bumps	Raise fSuspensionReboundDamp, then fSuspensionForce.
Sits too high	Use a negative fSuspensionRaise. Check the wheels do not clip the arches.
Will not hold a drift	Raise fTractionCurveLateral, lower fTractionCurveMin, set fDriveBiasFront to 0.0 and raise fHandBrakeForce.