How handling.meta works

1. What is in the file

A handling.meta is XML. The root is CHandlingDataMgr, inside it a HandlingData list, and each Item of type CHandlingData is one vehicle's handling. The entry does not know its vehicle; it only has a handlingName. The vehicle finds it the other way round: vehicles.meta names a handlingId, and the game matches the two by hash.

<CHandlingDataMgr>
  <HandlingData>
    <Item type="CHandlingData">
      <handlingName>SULTAN</handlingName>
      <fMass value="1500.0" />
      <fInitialDriveForce value="0.26" />
      <fInitialDriveMaxFlatVel value="145.0" />
      <nInitialDriveGears value="5" />
      ...
      <strModelFlags>440010</strModelFlags>
      <strHandlingFlags>0</strHandlingFlags>
      <SubHandlingData>
        <Item type="CCarHandlingData"> ... </Item>
        <Item type="NULL" />
        <Item type="NULL" />
      </SubHandlingData>
    </Item>
  </HandlingData>
</CHandlingDataMgr>

The 55 fields on the CHandlingData level cover mass, engine, gears, grip, brakes, steering, suspension, damage and three hex flag fields. All of them are listed with a one-line meaning on the fields page.

SubHandlingData holds up to six typed blocks. Cars carry a CCarHandlingData with camber, toe, castor and the strAdvancedFlags for differentials and gearbox type. Bikes need a CBikeHandlingData or they crash at spawn. Boats, planes, helicopters, trailers and submarines have their own. The NULL items are placeholders and are fine to keep.

Rockstar's own files contain typos that the parser accepts and that you must keep: fCamberStiffnesss with three s, values written as 7.5f, and the odd empty item type. A file that round-trips the vanilla set has to swallow all of that.

2. How FiveM loads it

A resource declares the file with a data_file line, and FiveM sorts HANDLING_FILE in before every other data file. The game's own parser reads it and each entry gets a slot in the global handling array.

Per handling name there is a stack, newest entry on top. The last loaded file with the same handlingName wins. That is the whole override mechanism: to change the Sultan you ship an entry called SULTAN in a resource that starts after the one that streams the car. Stop the resource and the previous entry is back.

Two details bite people. Vehicles that already exist keep a private copy of their handling, so a change only reaches cars spawned afterwards. And the global SET_HANDLING natives look up the first matching entry in the array, not the top of the stack, so with duplicates they can hit the wrong one.

fxmanifest.lua

files { 'data/handling.meta' } data_file 'HANDLING_FILE' 'data/handling.meta'

Match

joaat(handlingName) == joaat(vehicles.meta handlingId)

Priority

last loaded file with that name wins

Reach

vehicles spawned after the load

3. File units versus memory units

The numbers in the file are not the numbers the physics runs on. At load the game converts them, and the FiveM natives convert them back, so a script sees file units. alt:V and RAGE MP hand out the raw memory values, which is why the same car reads differently across platforms.

The practical rule: write file units everywhere, in the file and in FiveM natives. Convert only when you read memory through another platform.

4. The speed model

Four fields decide a straight line: fInitialDriveMaxFlatVel for the gearing, nInitialDriveGears for how it is split, fInitialDriveForce for the push and fInitialDragCoeff for the resistance. Mass is not on the list; both force and drag are per kilogram.

Gear n redline

fInitialDriveMaxFlatVel × 1.2 ÷ ratio[n], top gear ratio 0.9

Wheel acceleration

fInitialDriveForce × 10.9 × ratio × torque(rpm)

Torque curve

1.0 to 80 % rpm, then down to 0.55 at redline

Drag

fInitialDragCoeff × 0.0001 × v² plus 0.003 × v

Launch cap

fTractionCurveMax × g × (1.0 AWD, 0.55 two-wheel drive)

Shift

0.9 s ÷ fClutchChangeRateScaleUpShift without drive

Top speed is where wheel force in the current gear equals drag, or the redline of the last gear if that comes first. On most vanilla cars drag wins: measured fully upgraded cars reach 1.24 to 1.29 times the flat velocity value, not the 1.33 that the redline would allow.

This model, run over the vanilla files, lands within 3.3 % RMSE of 617 top speeds Broughy1322 measured and within 0.5 s of 155 community drag races over 1000 m. Eighty percent of cars are inside 3 %. The remaining error sits in the torque calibration and in things the file does not describe, such as the wheelie glitch on bikes.

5. Grip, brakes, steering

The tyre is a curve over slip angle. fTractionCurveMax is the peak, fTractionCurveMin the grip once sliding, fTractionCurveLateral the width of the curve with the peak at half its value. Vanilla cars run about twice the grip of a real tyre, on purpose.

Min vs max

keep min about 10 % under max; min above max breaks the curve

Steering that fits

fSteeringLock = fTractionCurveLateral × 1.25 + 10

Brake ceiling

deceleration = min(4 × fBrakeForce, fTractionCurveMax) in g

Bias fields

0 or 1 on fTractionBiasFront makes wheels vanish; stay inside 0.3 to 0.7

Low speed

fLowSpeedTractionLossMult 1.0 halves grip at walking pace

Two consequences are not obvious. Most vanilla cars already brake at the tyre limit, so raising fBrakeForce does nothing you can feel on 449 of the 608 cars. And fSteeringLock beyond the value that fits the tyre only adds understeer on a grip car; drift setups want it anyway for counter-steer.

Downforce comes from fDownforceModifier and grows with speed. Below 100 it uses the old ramp that caps at 90 % of the flat velocity; above 100 the newer, stronger ramp of the Krieger generation. A spoiler mod adds a further step on top.

6. Suspension

The suspension fields are relative, not in newtons. fSuspensionForce is the spring rate, the two damping fields are stored at a tenth of what you write, and the travel limits are metres.

Settled ride

compression + rebound damping about equal to fSuspensionForce

One-stroke bump

fSuspensionCompDamp about half of fSuspensionForce

Ride height

fSuspensionRaise, −0.02 is a visible drop

Body roll

fAntiRollBarForce up, or roll centres closer to the centre of mass

Rollover fix

vecCentreOfMassOffset z down, vecInertiaMultiplier z above 2

Model flags matter here too. The axle bits in strModelFlags pick torsion, solid or MacPherson geometry, and nearly every road car uses MacPherson at both ends.

7. Applying it on a server

For a permanent change, ship a resource with the entry under the vehicle's handlingName and start it after the car. That is exactly what the editor downloads.

fx_version 'cerulean'
game 'gta5'

files { 'data/handling.meta' }
data_file 'HANDLING_FILE' 'data/handling.meta'

ensure sultan_pack        -- the resource that streams the car
ensure sw_sultan_handling -- your override, after it

For testing, the natives change a spawned vehicle without a restart. SET_VEHICLE_HANDLING_FLOAT touches one vehicle, SET_HANDLING_FLOAT the global entry for cars spawned later. Both take file units.

local veh = GetVehiclePedIsIn(PlayerPedId(), false)
SetVehicleHandlingFloat(veh, 'CHandlingData', 'fInitialDriveForce', 0.32)
SetVehicleHandlingFloat(veh, 'CHandlingData', 'fInitialDragCoeff', 7.5)

Three things do not take live. Gear count and flat velocity build the ratios at spawn, mass builds the physics instance at spawn, and the flag fields are read at creation. For those, respawn the car, or use SetVehicleGearRatio and SetVehicleHighGear as a stand-in for the gearing.

8. When it does not work

Top speed moved less than expected

Drag is the limit, not the gears. The 1.33 rule is a ceiling; lower fInitialDragCoeff or raise fInitialDriveForce to move the crossing point.

Nothing changed at all

Check the handlingName matches the handlingId in vehicles.meta, that your resource starts after the car, and that you spawned a fresh vehicle.

Car flips in corners

Lower vecCentreOfMassOffset z, raise vecInertiaMultiplier z above 2, bring the roll centres up toward the centre of mass.

Bike crashes on spawn

The entry has no CBikeHandlingData block. Copy one from a vanilla bike.

Wheels disappear

fTractionBiasFront or a suspension bias is at 0 or 1. Stay inside the range.

8 gears refuse to apply

The FiveM handling native clamps at 7. Put the count in the file and respawn.

Values look wrong in alt:V

You are reading memory units. Convert with the table in section 3.