Exports & Events

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

Types & Classes

The public data shapes used by these exports are documented below in Data Types.

Suggestions?

If you wish to have any exports and 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

These are the public data shapes used by the exports below. Internal debug and runtime-only classes are not part of the public API.

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 deformation vector

---@alias VehicleDeformationEntry NativeDeformationEntry | VectorDeformationEntry

---@class WheelLossStateEntry
---@field index integer @ Wheel index detached from the vehicle
---@field reason? string @ Detach reason stored for repair/debug flows
---@field time? integer @ Server os.time timestamp when the wheel detached

---@class WheelLossStateData
---@field entries? WheelLossStateEntry[] @ Detached wheel entries in the vehicle state bag
---@field integrity? table<integer | string, number> @ Wheel integrity keyed by wheel index

---@class VehicleDamageData
---@field version integer @ Data format version
---@field deformation VehicleDeformationEntry[] | nil @ Saved vehicle body deformation
---@field wheelLoss WheelLossStateData | nil @ Saved wheel-loss and wheel-integrity state

#Client Exports

#Get Vehicle Damage Data

Grabs all custom damage data managed by this resource in one master table. Use this in framework vehicle-property or garage save functions so future damage data can be added without changing integrations again.

Example:

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

Example Data:

lua
{
    version = 1,
    deformation = {
        {1.20, -2.40, 0.00, 0.18},
    },
    wheelLoss = {
        entries = {},
        integrity = {
            [0] = 100.0,
            [1] = 74.5,
        },
    },
}

#Set Vehicle Damage Data

Applies custom damage data that was previously saved with Get Vehicle Damage Data. Run this after the framework has applied its normal vehicle properties.

This is the preferred integration export for garages and framework vehicle-property functions. The lower-level deformation and wheel-loss exports remain available for custom tools.

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

#Set Deformation

Sets the deformation of a vehicle. This should be triggered right when it is spawned, like in a garage script.

This shouldn't be triggered all by itself, it should only set the deformation that has been captured by the Get Deformation export.

Example:

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

Example Data:

lua
local deformation = {
    {1.20, -2.40, 0.00, 0.18},
    {-1.20, -2.40, 0.00, 0.11},
}

#Get Deformation

Grabs the deformation of a vehicle. This should be used when you want to save the current state to apply later, like when parking your vehicle in a garage.

This, by itself, does nothing. It should be used in combination with Set Deformation to retrieve & apply deformation.

Example:

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

Example Data:

lua
{
    {1.20, -2.40, 0.00, 0.18},
    {-1.20, -2.40, 0.00, 0.11},
}

#Fix Deformation

Fixes the deformation on a car. As this is written, all the export does is run the SetVehicleDeformationFixed native, but this may be changed in a future update. So if you want stability, trigger this export, even if it's not necessary right now.

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

#Wheel Index Reference

A wheel index is the number used to choose which wheel you want to check, damage, repair, or detach. Cars and bikes use different numbers.

Cars:

0 = Front left

1 = Front right

2 = Back left

3 = Back right
Bikes:

0 = Back wheel

1 = Front wheel
For example, 0 means front left on a car, but back wheel on a bike.

#Get Detached Wheels

Grabs the wheels currently tracked as detached on a vehicle. This is useful when another resource needs to save, inspect, or display the wheel-loss state.

Each entry contains the wheel index, the stored reason, and the server os.time() timestamp from when the wheel was detached. If the vehicle does not have detached wheels, this returns an empty table.

See Wheel Index Reference before displaying or manually using the returned index value.

Example:

lua
---@param veh integer
---@return WheelLossStateEntry[]
local detachedWheels = exports["zyke_realisticvehicles"]:GetDetachedWheels(veh)

Example Data:

lua
{
    {
        index = 0,
        reason = "landing_integrity_failure",
        time = 1747382400,
    },
    {
        index = 3,
        reason = "direct_hit",
        time = 1747382442,
    },
}

#Get Wheel Integrity

Grabs the current wheel integrity values for a vehicle. This is useful when a garage, repair, or inspection resource needs to show or save the current condition of each wheel.

The returned table is keyed by wheel index. A higher value means a healthier wheel. 0 means the wheel has fully failed, or has been detached by the wheel-loss system.

See Wheel Index Reference before turning the table keys into player-facing wheel labels.

If the vehicle is not valid, this returns an empty table.

Example:

lua
---@param veh integer
---@return table<integer, number>
local integrity = exports["zyke_realisticvehicles"]:GetWheelIntegrity(veh)

for wheelIndex, value in pairs(integrity) do
    print(("Wheel %d integrity: %.1f"):format(wheelIndex, value))
end

Example Data:

lua
{
    [0] = 100.0,
    [1] = 74.5,
    [2] = 0.0,
    [3] = 92.0,
}

Opens the zyke_lib context menu overview for wheel integrity. If a vehicle is passed, that vehicle is inspected. If no vehicle is passed, the export inspects the vehicle the player is in, or the closest supported vehicle within Config.DamageSystem.wheelLossIntegrityMenu.maxDistance.

This is meant for overview-style inspection tools. If Config.DamageSystem.wheelLossIntegrityMenu.enabled is false, this export returns false and does not open the menu.

Example:
lua
---@param veh? integer
---@return boolean
local opened = exports["zyke_realisticvehicles"]:OpenWheelIntegrityMenu(veh)
Example Result:
lua
true

Toggles the zyke_lib context menu overview for wheel integrity. If the overview is already open, it closes it. If it is closed, it behaves like Open Wheel Integrity Menu.

This is useful for keybinds, radial menu entries, or inspection tools that should use one action to open and close the overview.

Example:
lua
---@param veh? integer
---@return boolean
local toggled = exports["zyke_realisticvehicles"]:ToggleWheelIntegrityMenu(veh)
Example Result:
lua
true

#Detach Vehicle Wheel

Detaches a wheel from a vehicle and stores that wheel as detached in the vehicle state. This should be used when another resource wants to force a wheel-loss event, such as a mechanic tool, scripted crash, or admin/debug action.

The export also sets the wheel integrity to 0, stores the detach reason, and prevents the same wheel from being detached twice.

See Wheel Index Reference before choosing the wheelIndex, especially when supporting both cars and bikes.

This returns true when the wheel was detached and persisted. It returns false if the export fails for any reason.

Example:
lua
---@param veh integer
---@param wheelIndex integer
---@param reason? string
---@return boolean
local success = exports["zyke_realisticvehicles"]:DetachVehicleWheel(veh, wheelIndex, "mechanic_tool")
Example Result:
lua
true

#Clear Wheel Loss Data

Clears only the wheel-loss data from a vehicle. This removes the stored detached wheels and resets the stored wheel integrity state, so the wheel-loss system no longer treats the vehicle as having broken wheels.

This does not repair, reattach, or visually fix any wheels by itself. Use this when another resource has already repaired the vehicle and you only need to clear this resource's saved wheel-loss data.

This returns true when the data was cleared. It returns false if the export fails for any reason.

Example:
lua
---@param veh integer
---@return boolean
local success = exports["zyke_realisticvehicles"]:ClearWheelLossData(veh)
Example Result:
lua
true

#Repair Vehicle Wheels

Fixes the vehicle tyres and wheel health, then clears the wheel-loss data for that vehicle. This should be used by repair flows that are meant to reset wheel-loss tracking, not by save/load logic that only wants to clear stored data.

This returns true when the repair/reset ran. It returns false if the export fails for any reason.

Example:
lua
---@param veh integer
---@return boolean
local success = exports["zyke_realisticvehicles"]:RepairVehicleWheels(veh)
Example Result:
lua
true

#Repair Vehicle Damage

Clears this resource's custom repair state for a vehicle. This fixes deformation, clears saved deformation data, repairs wheel-loss damage, and clears wheel-loss data. Use this after another resource has already run its normal vehicle repair, such as SetVehicleFixed(vehicle).

This returns true when the repair/reset ran. It returns false or nil if no valid vehicle was provided or found.

Example:
lua
---@param veh integer
---@return boolean?
local success = exports["zyke_realisticvehicles"]:RepairVehicleDamage(veh)
Example Result:
lua
true

#Get Wheel Loss Data

Grabs all wheel-loss data in one table. This is the easiest export to use when saving vehicle properties in a garage or framework vehicle-property function.

The returned table contains detached wheel entries and wheel integrity values. Store it together with the rest of the vehicle properties, then apply it later with Set Wheel Loss Data.

Example:

lua
---@param veh integer
---@return WheelLossStateData
local wheelLoss = exports["zyke_realisticvehicles"]:GetWheelLossData(veh)

Example Data:

lua
{
    entries = {
        {
            index = 1,
            reason = "direct_hit",
            time = 1747382442,
        },
    },
    integrity = {
        [0] = 100.0,
        [1] = 36.5,
        [2] = 100.0,
        [3] = 100.0,
    },
}

#Set Wheel Loss Data

Applies wheel-loss data that was previously saved with Get Wheel Loss Data. This is meant for vehicle spawn/load flows, especially garages that already apply framework vehicle properties.

This restores detached wheels and partial wheel integrity. If nil is passed as the data, the stored wheel-loss data is cleared.

This returns true when the data was applied or cleared. It returns false if the export fails for any reason.

Example:
lua
---@param veh integer
---@param wheelLoss? WheelLossStateData | WheelLossStateEntry[]
---@return boolean
local success = exports["zyke_realisticvehicles"]:SetWheelLossData(veh, wheelLoss)
Example Result:
lua
true

Exports & Events

#Data Types

#Client Exports

#Get Vehicle Damage Data

#Set Vehicle Damage Data

#Set Deformation

#Get Deformation

#Fix Deformation

#Wheel Index Reference

#Get Detached Wheels

#Get Wheel Integrity

#Open Wheel Integrity Menu

#Toggle Wheel Integrity Menu

#Detach Vehicle Wheel

#Clear Wheel Loss Data

#Repair Vehicle Wheels

#Repair Vehicle Damage

#Get Wheel Loss Data

#Set Wheel Loss Data