Exports & Events

All exports and events available to integrate this resource into others.

Types / Classes

The public data types used by the persistence exports are documented below.

Companion Resources

Wheel-specific exports are documented under Wheel Pop. Terrain-specific exports are documented under Vehicle Terrain.

Suggestions?

If you wish to have any exports or events added, please head over to our Discord and create a suggestion post. We are happy to allow for easier integration within other resources.

#Data Types

lua
---@class NativeDeformationEntry
---@field [1] number @ Local x offset
---@field [2] number @ Local y offset
---@field [3] number @ Local z offset
---@field [4] number @ Deformation strength

---@class VectorDeformationEntry
---@field [1] vector3 @ Local offset
---@field [2] number | vector3 @ Deformation strength or native vector

---@alias VehicleDeformationEntry NativeDeformationEntry | VectorDeformationEntry

---@class VehicleDamageData
---@field version integer
---@field deformation VehicleDeformationEntry[] | nil
---@field wheelLoss? WheelLossStateData @ Present when Wheel Pop is installed

#Client Sided Exports

#Get Vehicle Damage Data

Returns the persistence payload for a vehicle. Store it as zykeRealisticVehicles in garage and framework integrations. When Wheel Pop is running, the payload also includes its wheel state.

Example:

lua
---@param vehicle integer
---@return VehicleDamageData | nil
local damageData = exports["zyke_realisticvehicles"]:GetVehicleDamageData(vehicle)

#Set Vehicle Damage Data

Applies data returned by GetVehicleDamageData. Run this after the framework finishes applying its normal vehicle properties. The setter also accepts zykeDeformation and zykeWheelLoss data.

Example:

lua
---@param vehicle integer
---@param damageData VehicleDamageData
---@return boolean
local success = exports["zyke_realisticvehicles"]:SetVehicleDamageData(vehicle, damageData)

#Set Deformation

Applies deformation captured with GetDeformation.

Example:

lua
---@param vehicle integer
---@param deformation VehicleDeformationEntry[]
exports["zyke_realisticvehicles"]:SetDeformation(vehicle, deformation)

#Get Deformation

Returns the vehicle's current synchronized deformation for persistence.

Example:

lua
---@param vehicle integer
---@return NativeDeformationEntry[] | nil
local deformation = exports["zyke_realisticvehicles"]:GetDeformation(vehicle)

#Fix Deformation

Repairs visible body deformation through the resource-owned repair path.

Example:

lua
---@param vehicle integer
exports["zyke_realisticvehicles"]:FixDeformation(vehicle)

#Repair Vehicle Non-Wheel Damage

Repairs deformation, engine, body, petrol tank, windows, fire, and the Realistic Vehicles handling state without changing Wheel Pop data. If no vehicle is passed, the resource uses the vehicle occupied by the player.

Example:

lua
---@param vehicle? integer
---@return boolean | nil
local success = exports["zyke_realisticvehicles"]:RepairVehicleNonWheelDamage(vehicle)

#Repair Vehicle Damage

Repairs Realistic Vehicles damage and delegates wheel repair to Wheel Pop when it is installed. Use this after a mechanic resource performs a complete native repair. For a wheel-only repair, use Wheel Pop's RepairVehicleWheels export.

Example:

lua
---@param vehicle? integer
---@return boolean | nil
local success = exports["zyke_realisticvehicles"]:RepairVehicleDamage(vehicle)

#Is Torque Handling Reduced

Returns whether Realistic Vehicles is applying engine-damage torque or handling consequences to the vehicle. This is useful when coordinating handling changes with another resource.

Example:

lua
---@param vehicle? integer
---@return boolean
local reduced = exports["zyke_realisticvehicles"]:IsTorqueHandlingReduced(vehicle)

#Get Torque Handling Base

Returns the handling baseline stored before Realistic Vehicles applied its engine-damage consequences. This lets another resource avoid capturing an already penalized value as its baseline.

Example:

lua
---@param vehicle? integer
---@return table | nil
local handling = exports["zyke_realisticvehicles"]:GetTorqueHandlingBase(vehicle)

#Framework Persistence

Store GetVehicleDamageData as zykeRealisticVehicles with the framework's normal vehicle properties. Restore it after the framework finishes applying those properties. When Wheel Pop is running, the same payload also includes its wheel data.

#ESX

Open es_extended/client/functions.lua.

Reference points:

Add zykeRealisticVehicles to the table returned by ESX.Game.GetVehicleProperties:

diff
         modWindows = GetVehicleMod(vehicle, 46),
         modLivery = GetVehicleMod(vehicle, 48) == -1 and GetVehicleLivery(vehicle) or GetVehicleMod(vehicle, 48),
         modLightbar = GetVehicleMod(vehicle, 49),
+        zykeRealisticVehicles = exports["zyke_realisticvehicles"]:GetVehicleDamageData(vehicle),
     }
 end

Apply it in ESX.Game.SetVehicleProperties after ESX restores props.tyreBurst, before the function closes:

diff
     if props.tyreBurst ~= nil then
         for k, v in pairs(props.tyreBurst) do
             if v then
                 k = tonumber(k)
                 if k then
                     SetVehicleTyreBurst(vehicle, k, true, 1000.0)
                 end
             end
         end
     end
+
+    if (props.zykeRealisticVehicles ~= nil) then
+        exports["zyke_realisticvehicles"]:SetVehicleDamageData(vehicle, props.zykeRealisticVehicles)
+    end
 end

#QBCore

Open qb-core/client/functions.lua.

Reference points:

Add zykeRealisticVehicles to the table returned by QBCore.Functions.GetVehicleProperties:

diff
             modLivery = modLivery,
             modKit49 = GetVehicleMod(vehicle, 49),
             liveryRoof = GetVehicleRoofLivery(vehicle),
+            zykeRealisticVehicles = exports["zyke_realisticvehicles"]:GetVehicleDamageData(vehicle),
         }
     else
         return
     end
 end

Apply it in QBCore.Functions.SetVehicleProperties after the existing vehicle properties, before the outer end:

diff
         if props.liveryRoof then
             SetVehicleRoofLivery(vehicle, props.liveryRoof)
         end
+        if (props.zykeRealisticVehicles ~= nil) then
+            exports["zyke_realisticvehicles"]:SetVehicleDamageData(vehicle, props.zykeRealisticVehicles)
+        end
     end
 end

#Qbox / ox_lib

Open ox_lib/resource/vehicleProperties/client.lua.

Reference points:

Add zykeRealisticVehicles to the table returned by lib.getVehicleProperties:

diff
             tyres = damage.tyres,
             bulletProofTyres = GetVehicleTyresCanBurst(vehicle),
             driftTyres = gameBuild >= 2372 and GetDriftTyresEnabled(vehicle),
+            zykeRealisticVehicles = exports["zyke_realisticvehicles"]:GetVehicleDamageData(vehicle),
             -- no setters?
             -- leftHeadlight = GetIsLeftVehicleHeadlightDamaged(vehicle),

Apply it in lib.setVehicleProperties after fixVehicle, before the final return:

diff
     if fixVehicle then
         SetVehicleFixed(vehicle)
     end
+
+    if (props.zykeRealisticVehicles ~= nil) then
+        exports["zyke_realisticvehicles"]:SetVehicleDamageData(vehicle, props.zykeRealisticVehicles)
+    end

     return not NetworkGetEntityIsNetworked(vehicle) or NetworkGetEntityOwner(vehicle) == cache.playerId
 end

For Qbox persistence, also add the property to watchedKeys in qbx_core/client/vehicle-persistence.lua:

diff
 local watchedKeys = {
     'bodyHealth',
     'engineHealth',
     'tankHealth',
     'fuelLevel',
     'oilLevel',
     'dirtLevel',
     'windows',
     'doors',
     'tyres',
+    'zykeRealisticVehicles',
 }

Finally, copy the changed property into the stored vehicle properties in qbx_core/server/vehicle-persistence.lua before SaveVehicle:

diff
     if diff.tyres then
         props.tyres = diff.tyres ~= 'deleted' and diff.tyres or nil
     end
+
+    if diff.zykeRealisticVehicles then
+        props.zykeRealisticVehicles = diff.zykeRealisticVehicles ~= 'deleted' and diff.zykeRealisticVehicles or nil
+    end

     exports.qbx_vehicles:SaveVehicle(vehicle, {
         props = props,
     })

#Repair Script Integration

After a mechanic script performs a complete native repair, call RepairVehicleDamage to clear synchronized deformation and delegate wheel repair to Wheel Pop when installed:

lua
if (GetResourceState("zyke_realisticvehicles") == "started") then
    exports["zyke_realisticvehicles"]:RepairVehicleDamage(vehicle)
end

Only add this to full repairs. Basic repairs that should preserve deformation or wheel condition should not call it.