FiveM vehicle damage: engine health, body health and handling tweaks

Typical symptoms:

Cars lose their engine after a small bump, explode when someone lightly hits a wall, or never take damage at all.

Damage in GTA is a handful of health values per vehicle, and a few handling numbers that scale how fast they drop. This article gives the ranges, the natives, the handling values and the idea behind realistic damage scripts.

#The health values

A vehicle has several health values you can read and write on the client:

A new car is at 1000.0 on all three. The engine is the unusual one because it goes below zero:

• At 1000, the engine is healthy.
• As the value drops, the car smokes and loses power.
• At 0 and below, the engine is dead and the car can catch fire. The range goes down to -4000.

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

print('engine', GetVehicleEngineHealth(vehicle))
print('body', GetVehicleBodyHealth(vehicle))
print('tank', GetVehiclePetrolTankHealth(vehicle))

The petrol tank matters for fires. When the tank health falls, it can leak, and a leaking tank can ignite. The engine and the tank are separate, so an engine at 1000 can still burn if the tank is hit.

#Setting the values

To repair or damage a vehicle, write the values back:

SetVehicleEngineHealth(vehicle, 1000.0)
SetVehicleBodyHealth(vehicle, 1000.0)
SetVehiclePetrolTankHealth(vehicle, 1000.0)

To fix a vehicle completely, including the visible deformation and the dirt, there are separate natives:

SetVehicleFixed(vehicle)
SetVehicleDeformationFixed(vehicle)
SetVehicleDirtLevel(vehicle, 0.0)

SetVehicleFixed resets health and repairs the model. SetVehicleDeformationFixed removes dents. Use both for a full repair.

To save the damage of an owned car, store the values with the other properties, see vehicle properties. If you do not, every car comes out of the garage fully repaired.

Tip: a vehicle that stalls at once and will not start again is often an engine health under 0. Setting it back to a value like 400.0 brings it back without a full repair, which is what many mechanic scripts do. See also the mechanic job.

#Handling multipliers

How fast the values drop is decided by the vehicle's handling. Three of them are the usual knobs:

A value of 1.0 is neutral, lower means less damage and higher means more. In a handling.meta they look like this:

<fCollisionDamageMult value="0.700000" />
<fDeformationDamageMult value="0.700000" />
<fEngineDamageMult value="1.500000" />

Small changes go a long way, so move by tenths. For where the file lives and how to apply the change, see editing vehicle handling. The same values can be changed at runtime with SetVehicleHandlingFloat, which affects one vehicle:

SetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fCollisionDamageMult', 0.7)

Runtime changes apply to that vehicle while it exists. Reapply them each time it spawns.

#Realistic damage scripts

Damage scripts do not change the engine of the game, they use the values above. The concept is simple:

1. A loop reads the engine and body health of the vehicle the player drives.
2. When the values fall below set thresholds, the script applies effects: less power with SetVehicleEnginePowerMultiplier, a stalling engine, a pulling steering, a warning on screen.
3. It keeps the engine from dying completely, for example by holding it at a small positive value, so the car limps instead of burning.
4. A mechanic or a repair kit sets the values back up.

The loop does not have to run every frame. A check every few hundred milliseconds is enough and cheaper, see how Wait works:

CreateThread(function()
    while true do
        local ped = PlayerPedId()
        local vehicle = GetVehiclePedIsIn(ped, false)

        if vehicle ~= 0 and GetPedInVehicleSeat(vehicle, -1) == ped then
            if GetVehicleEngineHealth(vehicle) < 200.0 then
                SetVehicleEngineHealth(vehicle, 200.0)
                SetVehicleEngineOn(vehicle, false, true, true)
            end
            Wait(500)
        else
            Wait(1500)
        end
    end
end)

This keeps the engine from burning, and switches it off instead. Treat it as a starting point: a real script adds a way to restart it, so the player is not stuck.

#Preventing explosions

If you only want fewer deaths by fire, the simplest safe options are the ones above: a lower damage multiplier, and keeping the engine and the tank health from falling to zero.

There are also natives that disable parts of the fire and explosion system for one vehicle, such as the ones that stop the engine from degrading. Use them on a specific vehicle, like a job vehicle, and read the native's documentation before you rely on them. Do not apply them to every vehicle on the server:

• Scripts like a car bomb or a heist depend on vehicles that can explode.
• Players use damage in roleplay: a chase, a crash scene, a police stop.
• A vehicle that cannot be destroyed is a griefing tool, and a way to avoid consequences.

Decide per use case, and prefer the multipliers.

#Damage after a restart or a respawn

If a car is repaired every time it spawns, the cause is one of these:

• The garage does not save engine and body health, so each spawn starts at 1000. Save the values on store and apply them on spawn.
• A script calls SetVehicleFixed on every spawn.
• The car is a fresh entity, and its health always starts full. Only your saved data carries damage over.

#Checklist