Config

Explanations for all config values.

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

All basic resource settings.

#debug

Enables wheel diagnostics and debug commands. Keep this disabled during normal production use.

Example:
lua
debug = false

#commandPermission

The ACE permission required to use admin and debug commands.

Example:
lua
commandPermission = "command"

#Config.WheelPop

All wheel integrity, failure, visual, item, and repair settings.

#preset

Selects the default wheel-failure profile. Available values are 1 for Arcade, 2 for Casual, 3 for Balanced, 4 for Realistic, and 5 for Hardcore. Balanced is recommended for most servers.

Example:
lua
preset = 3

#overrides

Overrides individual values after the selected preset is loaded. Use the exact keys defined in shared/unlocked/presets.lua. Small overrides are recommended so improvements to the preset defaults are retained.

Example:

lua
overrides = {
    wheelLossEnabled = true,
    wheelLossMaxWheelsPerEvent = 1,
    wheelLossDirectIntegrityDamage = 9.0,
}

Preset overrides cover general enablement and cooldowns, hard-landing detection, direct-impact detection, integrity damage, bike behavior, and per-class damage multipliers. The preset file is the authoritative list of supported keys and baseline values.

#wheelLossIntegrityNotifications

Settings for driver notifications when a wheel crosses an integrity threshold.

Example:

lua
wheelLossIntegrityNotifications = {
    enabled = true,
    minSpeedKmh = 5.0,
    stages = {
        {threshold = 45.0, key = "wheelIntegrityWarning"},
        {threshold = 20.0, key = "wheelIntegrityCritical"},
    },
}

#wheelLossIntegrityNotifications.enabled

Enables wheel integrity warning notifications.

Example:
lua
enabled = true

#wheelLossIntegrityNotifications.minSpeedKmh

Minimum vehicle speed in kilometres per hour before a warning can be displayed.

Example:
lua
minSpeedKmh = 5.0

#wheelLossIntegrityNotifications.stages

Notification stages evaluated by integrity threshold. Only the most severe newly crossed stage is shown.

Example:

lua
stages = {
    {threshold = 45.0, key = "wheelIntegrityWarning"},
    {threshold = 20.0, key = "wheelIntegrityCritical"},
}

#wheelLossIntegrityNotifications.stages[x].threshold

Integrity value at or below which this notification stage is triggered.

Example:
lua
threshold = 45.0

#wheelLossIntegrityNotifications.stages[x].key

Locale key used for the notification text.

Example:

lua
key = "wheelIntegrityWarning"

#wheelLossIntegrityMenu

Settings for the wheel integrity inspection menu.

Example:

lua
wheelLossIntegrityMenu = {
    enabled = true,
    item = "wheel_scanner",
    maxDistance = 5.0,
}

#wheelLossIntegrityMenu.enabled

Enables the wheel integrity menu and its configured usable item.

Example:
lua
enabled = true

#wheelLossIntegrityMenu.item

Inventory item registered to open the wheel integrity menu. Set this according to the item installed in your inventory.

Example:
lua
item = "wheel_scanner"

#wheelLossIntegrityMenu.maxDistance

Maximum distance from a vehicle when inspecting it outside the vehicle.

Example:
lua
maxDistance = 5.0

#wheelLossVisual

Settings for the wheel and prop visuals applied after a wheel fails.

Example:

lua
wheelLossVisual = {
    hideFailedWheel = true,
    spawnLooseWheel = true,
    wheelModel = "prop_wheel_01",
    rimModel = "prop_wheel_rim_03",
    propLifetime = 0,
}

#wheelLossVisual.hideFailedWheel

Hides the original vehicle wheel after it enters the failed state.

Example:
lua
hideFailedWheel = true

#wheelLossVisual.spawnLooseWheel

Spawns a synchronized loose-wheel prop when a wheel fails.

Example:
lua
spawnLooseWheel = true

#wheelLossVisual.wheelModel

Prop model used for a loose wheel with a tyre.

Example:

lua
wheelModel = "prop_wheel_01"

#wheelLossVisual.rimModel

Prop model used when the loose-wheel state requires a rim visual.

Example:
lua
rimModel = "prop_wheel_rim_03"

#wheelLossVisual.propLifetime

Lifetime of a loose-wheel prop in milliseconds. Set to 0 to keep it until the wheel is repaired or the entity is cleaned up.

Example:
lua
propLifetime = 0

#wheelItem

Settings for collecting a loose wheel as an inventory item.

Example:

lua
wheelItem = {
    enabled = true,
    item = "vehicle_wheel",
    maxDistance = 3.0,
    pickupAnimation = {
        enabled = true,
    },
}

#wheelItem.enabled

Enables loose-wheel pickup and inventory item creation.

Example:
lua
enabled = true

#wheelItem.item

Inventory item that receives the loose wheel and its fitment metadata.

Example:
lua
item = "vehicle_wheel"

#wheelItem.maxDistance

Maximum distance from the loose-wheel prop when picking it up.

Example:
lua
maxDistance = 3.0

#wheelItem.pickupAnimation.enabled

Enables the pickup animation when collecting a loose wheel.

Example:
lua
enabled = true

#repairItems

Settings for the tire kit and optional loose-wheel requirement when repairing failed wheels.

Example:

lua
repairItems = {
    enabled = true,
    consume = true,
    maxDistance = 5.0,
    wheelRequirement = "basic",
    wheelDistance = 1.0,
    tireKit = {
        enabled = true,
        item = "tirekit",
        duration = 7500,
    },
}

#repairItems.enabled

Enables the built-in tire-kit repair flow.

Example:
lua
enabled = true

#repairItems.consume

Consumes the configured tire 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.wheelRequirement

Controls whether repairing a simulated failed wheel requires a loose-wheel item. Use "none" for no item, "basic" for any configured wheel item, or "hardcore" for matching vehicle and wheel metadata. This requirement does not apply to ordinary tyre, wheel-health, or integrity repairs.

Example:
lua
wheelRequirement = "basic"

#repairItems.wheelDistance

Maximum distance from the failed wheel when starting a "basic" or "hardcore" repair.

Example:
lua
wheelDistance = 1.0

#repairItems.tireKit

Settings for the usable tire-kit item.

Example:

lua
tireKit = {
    enabled = true,
    item = "tirekit",
    duration = 7500,
}

#repairItems.tireKit.enabled

Enables registration of the configured tire-kit item.

Example:
lua
enabled = true

#repairItems.tireKit.item

Inventory item used to repair tyres and wheel damage.

Example:
lua
item = "tirekit"

#repairItems.tireKit.duration

Duration of the tire-kit repair action in milliseconds.

Example:
lua
duration = 7500

#fullRepairEvents

Client events from supported mechanic resources that should reset all Wheel Pop damage after a full vehicle repair. Add or remove events to match your server's repair resources.

Example:

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