Config

General Information

The editable configuration is located in shared/unlocked/config.lua. Preset values and all available override keys are located in shared/unlocked/presets.lua.

#Config.Settings

General resource settings that affect development and diagnostics.

#debug

Enables debug behavior for the resource. Only enable this in development environments because it exposes dangerous commands.

Example:

lua
debug = false

#commandPermission

Permission required for admin and debug commands. The default uses the command ACE permission.

Example:

lua
commandPermission = "command"

#Config.DamageSystem

Configures the realistic vehicle damage system. The selected preset is loaded from shared/presets.lua, then any values in overrides are applied on top of that preset.

#deformationEnabled

Enables synchronized visual body deformation. Disable it when another resource owns deformation, without disabling the health-damage system.

Example:

lua
deformationEnabled = true

#damageMultipliersEnabled

Enables health damage multipliers and the progressive engine-damage loop. Torque loss, limp mode, flip prevention, and related preset behavior are part of this system.

Example:

lua
damageMultipliersEnabled = true

#preset

Selects the preset level that defines the default values for all damage-related settings. Valid levels are 1 for Arcade, 2 for Casual, 3 for Balanced, 4 for Realistic, and 5 for Hardcore. Balanced is the recommended default. If an invalid level is configured, the resource falls back to Balanced.

Example:

lua
preset = 3

#overrides

A table of key-value pairs that override individual damage settings after the preset is applied. Each key must match a valid damage system key from shared/presets.lua; for example, { limpMode = true, damageFactorEngine = 5.0 } changes only those values while keeping the rest of the selected preset.

Example:

lua
overrides = {}

#Choosing Between Presets And Overrides

Use preset when you want a complete difficulty profile. Use overrides when you like a preset overall but want to tune one or more values.

The resource resolves the damage system in this order:

1. Reads Config.DamageSystem.preset.
2. Loads that preset from shared/presets.lua.
3. Falls back to preset 3 if the selected preset does not exist.
4. Copies every value from the preset into Config.DamageSystem.
5. Applies every value from Config.DamageSystem.overrides on top.

You normally should not edit shared/presets.lua. Edit it only if you want to permanently change the built-in preset definitions for the whole resource. If you only want to customize your server, keep using shared/config.lua and place changed values inside overrides. After changing preset definitions and restarting the resource, players should re-enter their vehicle so the new handling values are applied.

lua
Config.DamageSystem = {
    deformationEnabled = true,
    damageMultipliersEnabled = true,
    preset = 3,
    overrides = {
        limpMode = true,
        damageFactorEngine = 5.0,
    },
}

#preventLowFuelHandling

Prevents GTA's low-fuel handling edge case by making the vehicle undriveable below lowFuelHandlingThreshold. This setting is independent of Wheel Pop and Vehicle Terrain.

Example:

lua
preventLowFuelHandling = true

#lowFuelHandlingThreshold

Fuel level at or below which preventLowFuelHandling makes the vehicle undriveable.

Example:

lua
lowFuelHandlingThreshold = 7.0

Wheel loss settings now belong in Config.WheelPop inside zyke_wheelpop. Terrain settings now belong in Config.Terrain inside zyke_vehicleterrain. Do not copy those settings into Config.DamageSystem.

#repairItems

Configures the optional full vehicle repair item. Wheel-only repairs and tirekit now belong to Wheel Pop.

Example:

lua
repairItems = {
    enabled = true,
    consume = true,
    maxDistance = 5.0,
    repairKit = {
        enabled = true,
        item = "repairkit",
        duration = 7500,
    },
}

#repairItems.enabled

Enables the built-in full vehicle repair item.

Example:

lua
enabled = true

#repairItems.consume

Consumes the configured repair kit after a successful repair.

Example:

lua
consume = true

#repairItems.maxDistance

Maximum distance from the target vehicle when beginning a repair.

Example:

lua
maxDistance = 5.0

#repairItems.repairKit

Settings for the usable full vehicle repair item.

Example:

lua
repairKit = {
    enabled = true,
    item = "repairkit",
    duration = 7500,
}

#repairItems.repairKit.enabled

Enables registration of the configured repair-kit item.

Example:

lua
enabled = true

#repairItems.repairKit.item

Inventory item used to complete a full vehicle repair.

Example:

lua
item = "repairkit"

#repairItems.repairKit.duration

Duration of the full repair action in milliseconds.

Example:

lua
duration = 7500

#fullRepairEvents

A list of external full-repair events that should also restore damage owned by Realistic Vehicles. Wheel Pop listens for its own copy of these integrations and repairs wheel state separately.

Example:

lua
fullRepairEvents = {
    "txcl:vehicle:fix",
    "esx:repairPedVehicle",
    "qb-mechanicjob:client:fixEverything",
    "qb-mechanicjob:client:repairVehicleFull",
    "vehiclemod:client:fixEverything",
}

#Preset Reference

#Preset Values

#Override Keys

#Default Class Multipliers

classDamageMultiplier lets you tune damage by GTA vehicle class. For example, the default table reduces damage for motorcycles, off-road vehicles, and industrial vehicles.

Cycles, helicopters, planes, and trains are excluded from the damage loop, so their default multipliers are listed for completeness but are not used by normal damage processing.

lua
overrides = {
    classDamageMultiplier = {
        [0] = 1.0,  -- Compacts
        1.0,        -- Sedans
        1.0,        -- SUVs
        1.0,        -- Coupes
        1.0,        -- Muscle
        1.0,        -- Sports Classics
        1.0,        -- Sports
        1.0,        -- Super
        0.45,       -- Motorcycles
        0.7,        -- Off-road
        0.25,       -- Industrial
        1.0,        -- Utility
        1.0,        -- Vans
        1.0,        -- Cycles
        0.5,        -- Boats
        1.0,        -- Helicopters
        1.0,        -- Planes
        0.75,       -- Service
        0.75,       -- Emergency
        0.75,       -- Military
        1.0,        -- Commercial
        1.0,        -- Trains
    },
}