handling.meta explained: fields, units and flags

handling.meta is an XML list of CHandlingData items. Each item is one physics profile, identified by handlingName. On FiveM it is loaded with data_file 'HANDLING_FILE'. The entry below is the stock Sultan with the name changed; the values in the tables on this page refer to it.

<?xml version="1.0" encoding="UTF-8"?>
<CHandlingDataMgr>
  <HandlingData>
    <Item type="CHandlingData">
      <handlingName>MYCAR</handlingName>
      <fMass value="1400.000000" />
      <fInitialDragCoeff value="8.000000" />
      <fPercentSubmerged value="85.000000" />
      <vecCentreOfMassOffset x="0.000000" y="0.000000" z="0.000000" />
      <vecInertiaMultiplier x="1.000000" y="1.400000" z="1.600000" />
      <fDriveBiasFront value="0.400000" />
      <nInitialDriveGears value="5" />
      <fInitialDriveForce value="0.260000" />
      <fDriveInertia value="1.000000" />
      <fClutchChangeRateScaleUpShift value="1.800000" />
      <fClutchChangeRateScaleDownShift value="1.800000" />
      <fInitialDriveMaxFlatVel value="145.000000" />
      <fBrakeForce value="0.400000" />
      <fBrakeBiasFront value="0.650000" />
      <fHandBrakeForce value="0.700000" />
      <fSteeringLock value="35.000000" />
      <fTractionCurveMax value="2.350000" />
      <fTractionCurveMin value="1.950000" />
      <fTractionCurveLateral value="22.500000" />
      <fTractionSpringDeltaMax value="0.150000" />
      <fLowSpeedTractionLossMult value="1.400000" />
      <fCamberStiffnesss value="0.000000" />
      <fTractionBiasFront value="0.485000" />
      <fTractionLossMult value="1.000000" />
      <fSuspensionForce value="2.800000" />
      <fSuspensionCompDamp value="1.200000" />
      <fSuspensionReboundDamp value="2.100000" />
      <fSuspensionUpperLimit value="0.150000" />
      <fSuspensionLowerLimit value="-0.140000" />
      <fSuspensionRaise value="0.000000" />
      <fSuspensionBiasFront value="0.500000" />
      <fAntiRollBarForce value="0.300000" />
      <fAntiRollBarBiasFront value="0.530000" />
      <fRollCentreHeightFront value="0.240000" />
      <fRollCentreHeightRear value="0.250000" />
      <fCollisionDamageMult value="0.700000" />
      <fWeaponDamageMult value="1.000000" />
      <fDeformationDamageMult value="0.700000" />
      <fEngineDamageMult value="1.500000" />
      <fPetrolTankVolume value="65.000000" />
      <fOilVolume value="5.000000" />
      <fSeatOffsetDistX value="0.000000" />
      <fSeatOffsetDistY value="0.000000" />
      <fSeatOffsetDistZ value="0.050000" />
      <nMonetaryValue value="35000" />
      <strModelFlags>440010</strModelFlags>
      <strHandlingFlags>0</strHandlingFlags>
      <strDamageFlags>0</strDamageFlags>
      <AIHandling>AVERAGE</AIHandling>
      <SubHandlingData>
        <Item type="CCarHandlingData">
          <fBackEndPopUpCarImpulseMult value="0.100000" />
          <fBackEndPopUpBuildingImpulseMult value="0.030000" />
          <fBackEndPopUpMaxDeltaSpeed value="0.600000" />
        </Item>
        <Item type="NULL" />
        <Item type="NULL" />
      </SubHandlingData>
    </Item>
  </HandlingData>
</CHandlingDataMgr>

Every field has a minimum and maximum in the game's data schema. For most floats the range is 0 to 1000, fMass goes up to 100000, and the gear count is capped at 10. Values in the tables are what the game does with the number after loading, taken from the handling code.

Field	Unit	Sultan	What it does
fMass	kg	1400	Vehicle mass. Used in every force and collision calculation.
fInitialDragCoeff	multiplied by 0.0001 on load	8.0	Air drag. Higher values slow the vehicle more at speed.
fPercentSubmerged	%	85	How much of the vehicle sits under water when floating. The game derives its buoyancy constant as 100 divided by this value.
vecCentreOfMassOffset	metres	0, 0, 0	Moves the centre of mass. y is front to back, z is up and down. A higher centre makes the vehicle roll over more easily.
vecInertiaMultiplier	multiplier per axis	1.0, 1.4, 1.6	Rotational inertia. A lower value on an axis makes the vehicle rotate more easily around it.

Top speed comes from fInitialDriveMaxFlatVel and acceleration from fInitialDriveForce. The game converts the velocity from km/h to m/s on load and then adds 20% to get the speed used for gearing, which is why vehicles go a little faster than the number in the file.

Field	Unit	Sultan	What it does
fInitialDriveMaxFlatVel	km/h	145	Top speed reference on flat ground. Gearing uses this value times 1.2.
fInitialDriveForce	scale	0.26	Engine drive force. Raises acceleration.
nInitialDriveGears	count	5	Number of forward gears. Anything above 10 is cut to 10.
fDriveInertia	scale	1.0	How quickly the engine revs rise and fall.
fClutchChangeRateScaleUpShift, ...DownShift	scale	1.8	How fast the clutch re-engages after a shift. Higher is a quicker shift.
fDriveBiasFront	0 to 1	0.4	Share of drive on the front wheels. Below 0.1 the game treats it as pure rear-wheel drive, above 0.9 as pure front-wheel drive, anything between is all-wheel drive.

Field	Unit	Sultan	What it does
fBrakeForce	scale	0.4	Overall braking strength.
fBrakeBiasFront	0 to 1	0.65	Share of braking on the front axle. The rear gets the rest.
fHandBrakeForce	scale	0.7	Handbrake strength.
fSteeringLock	degrees	35	Maximum steering angle of the wheels. Converted to radians on load.

The traction curve is the tire grip model. Grip is highest at a small slip angle (fTractionCurveMax) and falls toward fTractionCurveMin as the tire slides. Max must be greater than Min and above zero, or the loader warns about an invalid curve.

Field	Unit	Sultan	What it does
fTractionCurveMax	grip coefficient	2.35	Peak grip, before the tire starts sliding.
fTractionCurveMin	grip coefficient	1.95	Grip once the tire is sliding.
fTractionCurveLateral	degrees	22.5	Slip angle range of the curve. A larger angle makes grip fall off more gradually, so slides are more forgiving.
fTractionSpringDeltaMax	limit	0.15	Limit used by the sideways spring of the tire model.
fLowSpeedTractionLossMult	multiplier	1.4	Extra grip loss when pulling away from a stop. 0 turns the effect off; higher values mean more wheelspin off the line.
fCamberStiffnesss	multiplier	0	Side force from leaning; only does something above 0 and is mainly used by bikes. The tag really has three s.
fTractionBiasFront	0 to 1	0.485	Share of grip on the front axle. Lower values make the front slide first (understeer).
fTractionLossMult	multiplier	1.0	How strongly the surface under the wheels (grass, sand, mud) costs grip, adds drag and cuts top speed. 0 ignores the surface.

The handling flag HF_HAS_RALLY_TYRES (0x8) reverses the curve: grip rises toward Max as the tire slides instead of dropping.

Field	Sultan	What it does
fSuspensionForce	2.8	Spring stiffness.
fSuspensionCompDamp, fSuspensionReboundDamp	1.2, 2.1	Damping while the spring compresses and while it extends. Both are multiplied by 0.1 on load. Low values bounce, high values feel planted.
fSuspensionUpperLimit, fSuspensionLowerLimit	0.15, -0.14	How far the wheel can travel up and down from rest, in metres.
fSuspensionRaise	0	Raises or lowers the body relative to the wheels, in metres.
fSuspensionBiasFront	0.5	Share of spring force on the front axle (0 to 1).
fAntiRollBarForce, fAntiRollBarBiasFront	0.3, 0.53	Anti-roll bar strength and its front share. More force means less body roll in corners.
fRollCentreHeightFront, fRollCentreHeightRear	0.24, 0.25	Roll centre heights in metres, used for weight transfer in corners.

A lowered car whose wheels pop through the arches usually has too much upper travel for the space in the wheel arch: reduce fSuspensionUpperLimit and raise the damping before touching the spring force.

• fCollisionDamageMult, fWeaponDamageMult, fEngineDamageMult: multipliers for damage from crashes, from weapons and to the engine.
• fDeformationDamageMult: how much the body visibly deforms.
• fPetrolTankVolume, fOilVolume: tank and oil volume.
• fSeatOffsetDistX/Y/Z: seat position offsets.
• nMonetaryValue: base value of the vehicle, up to 1000000.
• AIHandling: name of the AI driving profile, for example AVERAGE. It only affects computer-controlled drivers.
• fDownforceModifier (0 to 100), fRocketBoostCapacity and fBoostMaxSpeed: newer optional fields for downforce and rocket boost.

The three flag fields are hexadecimal bitmasks written without the 0x prefix. To build one, add up the hex values of the flags you want. The Sultan's 440010 is three flags:

MF_ABS_STD           0x00000010
MF_AXLE_F_MCPHERSON  0x00040000
MF_AXLE_R_MCPHERSON  0x00400000
                     ----------
strModelFlags        0x00440010  ->  <strModelFlags>440010</strModelFlags>

Field	Flag	Hex	Effect
strModelFlags	MF_IS_VAN	0x1	Van.
	MF_ABS_STD	0x10	ABS as standard.
	MF_NO_DOORS	0x100	The vehicle has no doors.
	MF_NO_WHEEL_BURST	0x2000000	Tires cannot burst.
	MF_IS_RC	0x10000000	Remote-controlled car.
strHandlingFlags	HF_HAS_RALLY_TYRES	0x8	Reverses the traction curve.
	HF_NO_HANDBRAKE	0x10	No handbrake.
	HF_STEER_REARWHEELS	0x20	Steers with the rear wheels.
	HF_NO_REVERSE	0x200	Cannot reverse.
	HF_CVT	0x1000	Continuously variable transmission.
	HF_OFFROAD_ABILITIES	0x100000	Extra gravity for off-road grip.
	HF_ARMOURED	0x8000000	Bullet proof.
strDamageFlags	DF_DRIVER_SIDE_FRONT_DOOR	0x1	Door damage flag for the driver door.
	DF_BONNET, DF_BOOT	0x10, 0x20	Door damage flags for bonnet and boot.

SubHandlingData holds up to four extra blocks, each for one kind of vehicle. Add the block that matches the vehicle and leave the other slots as <Item type="NULL" />. The game ignores a block of the wrong kind.

Block type	For	Examples of fields
CCarHandlingData	Cars	fToeFront, fCamberFront, fCastor, fEngineResistance, strAdvancedFlags
CBikeHandlingData	Motorcycles and bicycles	fMaxBankAngle, fWheelieBalancePoint, fInAirSteerMult, fJumpForce
CFlyingHandlingData	Planes and helicopters	fThrust, fYawMult, fRollMult, fPitchMult, fFormLiftMult
CBoatHandlingData	Boats	fBoxFrontMult, fAquaplaneForce, fRudderForce
CSpecialFlightHandlingData	Hover and flying modes on ground vehicles	mode, fMaxThrust, vecAngularDamping, strFlags
CSubmarineHandlingData, CTrailerHandlingData, CSeaPlaneHandlingData, CVehicleWeaponHandlingData	Submarines, trailers, seaplanes, weaponized vehicles	Dive speed, attach limits, pontoons, turret limits

The flight handling of the Nilo3D hoverboards is done this way, in the handling file with no script. In the bike block, the lean and balance angles are written in degrees and converted to radians on load.

The other files a board needs are listed in how a FiveM hoverboard works without a script.

Change one value at a time, restart the resource and drive the same stretch of road before changing the next one. Keep a copy of the last version that felt right. The stock entry of a similar vehicle is the best reference for whether a value is in a normal range: the game's own handling.meta has an entry for every stock vehicle.

Handling only takes effect when the entry is linked correctly: handlingName here, handlingId in vehicles.meta, and a HANDLING_FILE line in the manifest, as shown in how to add an add-on vehicle to FiveM. If the vehicle does not react to your edits at all, see the handling section of the troubleshooting guide.