Config

Edit zyke_towing/shared/unlocked/config.lua. Examples below show current settings in the garages reference format. Distances are meters, speeds are km/h unless stated otherwise, and durations ending in Ms are milliseconds.

Keybinds can be changed in GTA / FiveM settings. Framework, inventory, target, and key-provider settings live in zyke_lib.

#Full Default Config

lua
Config = Config or {}

Config.Settings = {
    debug = false,
    commandPermission = "command",
    personalSettings = {
        command = "towsettings",
        kvp = "towing_personal_settings",
        settings = {
            -- The default applies on first use; players can then save their own preference
            -- Force applies the configured default and locks the menu without overwriting saved preferences
            -- Size multiplier for the in-world winch meter: 1.0 is normal size, 0.5 is half, 2.0 is double
            {
                name = "winchMeterScale",
                values = "slider",
                default = 1.0,
                force = false,
                min = 0.5,
                max = 3.0,
                step = 0.05,
            },
            -- Milliseconds the winch meter stays visible after winching stops, unless always-show is enabled
            {
                name = "winchMeterHideDelay",
                values = "slider",
                default = 600,
                force = false,
                min = 100,
                max = 3000,
                step = 100,
                unit = "milliseconds",
            },
            -- Keep the meter visible while near a cable or inside a connected vehicle, even when not winching
            {
                name = "winchMeterAlwaysShow",
                values = {false, true},
                default = false,
                force = false,
            },
        },
    },

    -- Attach one towline between two vehicles, then pull the rear vehicle with the front one
    -- Distances are anchor to anchor (tower rear bumper to towed front bumper) in meters
    towing = {
        -- Maximum basic-rope attachment distance; cables use their winch maximum
        attachDistance = 9.0,
        -- Maximum player distance to a vehicle when auto-selecting it for attach/detach
        selectDistance = 7.0,
        -- Both vehicles must be (almost) stationary to attach
        requireBothStopped = true,
        maxAttachSpeedKmh = 6.0,

        -- The towed vehicle must have no driver, set to false to allow towing occupied vehicles
        requireEmptyTowed = false,
        -- Locked vehicles can not be towed, prevents towing away other players vehicles
        requireUnlocked = false,
        -- Attaching consumes one rope item on success, set to false for itemless towing
        requireItem = true,

        -- Basic ropes start at this fixed length; cables start at the attachment distance
        defaultRopeLength = 7.0,

        -- Progress bar durations in ms, set to 0 to skip the bar
        attachTimeMs = 3500,
        detachTimeMs = 2000,

        -- Stand this close to a bumper to tie the rope to it
        carryEndDistance = 1.0,
        -- Minimum carry range; extended to the material attachment range plus player reach
        carryDistance = 12.0,
        -- Carrying expires after this long
        carryTimeoutMs = 300000,

        -- The rope physically pulls the rear vehicle, including when a player is driving
        -- Steering assistance applies only while the towed driver seat is empty
        -- Set to 0 for normal vehicle speed, or a positive value to cap towing speed
        maxTowSpeedKmh = 0,
        -- Extra pulling torque while the rope is taut, set to 1.0 for unassisted V2-style physics
        pullPowerMultiplier = 1.0,
        -- Scale only extra low-speed traction loss while towing: 0 disables it, 1 keeps normal handling
        launchTractionLossMultiplier = 0.0,

        -- Vehicle classes that can never be part of a tow (bicycles, boats, helis, planes, trains)
        blockedClasses = {
            [13] = true, -- Bicycles
            [14] = true, -- Boats
            [15] = true, -- Helicopters
            [16] = true, -- Planes
            [21] = true, -- Trains
        },

        -- Reads zyke_vehicleterrain state when it is started, towers on soft ground tow slower
        -- and stuck towed vehicles are called out in notifications
        terrainIntegration = {
            enabled = true,
            stuckDepthThreshold = 0.05,
            towerSoftPenalty = 0.5,
            -- Maximum fraction of pulling torque removed by the rear vehicle's terrain penalty
            -- Uses Vehicle Terrain materials, wheel type, class, speed and configured preset
            maxPullReduction = 0.65,
            -- Relieve terrain penalties for lighter loads: 0 = old behavior, 1 = full mass ratio
            -- Equal/heavier loads keep the original penalty; native physics handles their weight
            massInfluence = 0.5,
        },

        -- Every material owns its inventory item, attachment settings, visuals and break rules
        ropeMaterials = {
            rope = {
                ropeItem = "tow_rope",
                winch = false,
                carryProp = {
                    model = "prop_stag_do_rope",
                    bone = 57005,
                    ropeBone = "IK_R_Hand",
                    offset = vector3(0.35552558302879, 0.0128183029592, 0.00060697877779),
                    rotation = vector3(143.31787109375, 150.04833984375, -43.87148666381836),
                    rotationOrder = 1,
                    useSoftPinning = false,
                    collision = false,
                    syncRotation = true,
                    -- Ordered vehicle bones, with centered offsets in vehicle-local meters
                    front = {bones = {"neon_f", "bumper_f"}, offset = vector3(0.0, 0.1, -0.05)},
                    rear = {bones = {"neon_b", "bumper_r"}, offset = vector3(0.0, -0.1, -0.05)},
                },
                -- Set a break condition to false to disable it
                breakDistance = 18.0,
                breakSpeedKmh = 90.0,
                breakOnTowedDriven = false,
                rope = {ropeType = 2, spawnDistance = 75.0},
            },
            metal = {
                ropeItem = "tow_cable",
                -- Length limits and meters reeled per second while holding a winch key
                winch = {
                    minLength = 3.0, maxLength = 30.0, speed = 1.0,
                    -- Keep recovery faster than the drum so tyre resistance does not accumulate cable overstretch
                    catchupSpeed = 2.0,
                },
                carryProp = {
                    model = "prop_rope_family_3",
                    bone = 57005,
                    ropeBone = "IK_R_Hand",
                    offset = vector3(0.31782007217407, -0.03550132364034, -0.07096430659294),
                    rotation = vector3(31.97068405151367, 1.72993874549865, -5.64041757583618),
                    rotationOrder = 1,
                    useSoftPinning = false,
                    collision = false,
                    syncRotation = true,
                    -- Ordered vehicle bones, with centered offsets in vehicle-local meters
                    front = {bones = {"neon_f", "bumper_f"}, offset = vector3(0.0, 0.1, -0.05)},
                    rear = {bones = {"neon_b", "bumper_r"}, offset = vector3(0.0, -0.1, -0.05)},
                },
                -- Set a break condition to false to disable it
                breakDistance = false,
                breakSpeedKmh = false,
                breakOnTowedDriven = false,
                rope = {ropeType = 6, spawnDistance = 75.0},
            },
        },
    },

    -- Offsets locate the center of each deck floor relative to the carrier origin, in meters
    -- Each model maxVehicleSize limits vehicle width, length and height; slot maxVehicleHeight can override deck clearance
    -- Vehicle bounds are centered horizontally and their rotated bottom sits on the floor
    -- Add one slot per parking space, with separate Z offsets for upper and lower decks
    -- Keep clearance below the next deck, including its thickness
    beds = {
        -- Access mode: "jobs" requires a listed job, "keys" requires vehicle keys, "none" allows anyone
        -- In keys mode, trailers use the attached vehicle's keys; unattached trailers need no keys
        access = "keys",
        -- Job names allowed in jobs mode; an empty array allows no jobs
        jobs = {"mechanic"},
        -- Interaction range around the loading point, not the carrier center
        selectDistance = 10.0,
        -- Vehicle origin must be inside this carrier-aligned loading box
        loadingZoneSize = vector3(6.0, 8.0, 4.0),
        -- Allow only tiny physics jitter while stationary
        maxSpeedKmh = 0.1,
        models = {
            [GetHashKey("flatbed")] = {
                -- Maximum loaded vehicle dimensions: width, length, height in meters
                maxVehicleSize = vector3(2.8, 5.0, 3.0),
                -- Zone center relative to the carrier; also used to find an offloading position
                loadingZoneOffset = vector3(0.0, -9.0, 0.0),
                slots = {
                    {offset = vector3(0.0, -2.4, 0.4), rotation = vector3(0.0, 0.0, 0.0)},
                },
            },
            -- Three cars per deck; floor heights and pitch follow the stock tr2 collision surface
            [GetHashKey("tr2")] = {
                -- Maximum loaded vehicle dimensions: width, length, height in meters
                maxVehicleSize = vector3(2.6, 4.8, 3.0),
                -- Require the trunk/guard (door 5) to be open when loading or unloading
                requireTrunkOpen = true,
                -- The tr2 guard is client door 5 but replicates as server door 1
                trunkDoorServerIndex = 1,
                -- Zone center relative to the carrier; also used to find an offloading position
                loadingZoneOffset = vector3(0.0, -11.0, 0.0),
                slots = {
                    {offset = vector3(0.0, 5.0, 0.43), maxVehicleHeight = 1.8, rotation = vector3(0.0, 0.0, 0.0)},
                    {offset = vector3(0.0, 0.0, 0.563), maxVehicleHeight = 1.8, rotation = vector3(-3.14, 0.0, 0.0)},
                    {offset = vector3(0.0, -5.0, 0.508), maxVehicleHeight = 1.8, rotation = vector3(4.51, 0.0, 0.0)},
                    {offset = vector3(0.0, 5.0, 2.387), rotation = vector3(3.17, 0.0, 0.0)},
                    {offset = vector3(0.0, 0.0, 2.493), rotation = vector3(-5.35, 0.0, 0.0)},
                    {offset = vector3(0.0, -5.0, 2.73), rotation = vector3(-0.15, 0.0, 0.0)},
                },
            },
            [GetHashKey("trflat")] = {
                -- Maximum loaded vehicle dimensions: width, length, height in meters
                maxVehicleSize = vector3(2.8, 5.0, 3.0),
                -- Zone center relative to the carrier; also used to find an offloading position
                loadingZoneOffset = vector3(0.0, -11.0, 0.0),
                slots = {
                    {offset = vector3(0.0, 2.5, 0.41), rotation = vector3(0.0, 0.0, 0.0)},
                    {offset = vector3(0.0, -2.5, 0.41), rotation = vector3(0.0, 0.0, 0.0)},
                },
            },
        },
    },
}

#Config.Settings

#debug

Enables development diagnostics. Leave disabled for normal gameplay.

Example:

lua
debug = false

#commandPermission

Permission checked by tow action commands through zyke_lib. This is a permission identifier, not a job name. It does not replace the server action hooks.

Example:

lua
commandPermission = "command"

#personalSettings.command

Command that opens personal settings.

Example:

lua
command = "towsettings"

#personalSettings.kvp

Client KVP key used to store preferences. Changing it selects a different saved preference entry.

Example:

lua
kvp = "towing_personal_settings"

#personalSettings.settings

Definitions for the winch-meter settings. default applies before a player saves a preference; force = true applies and locks that default without overwriting the saved preference. Slider definitions use min, max, and step; choice settings use a values array. Keep the existing names used by the UI.

Example:

lua
settings = {
    {name = "winchMeterScale", values = "slider", default = 1.0, force = false, min = 0.5, max = 3.0, step = 0.05},
    {name = "winchMeterHideDelay", values = "slider", default = 600, force = false, min = 100, max = 3000, step = 100, unit = "milliseconds"},
    {name = "winchMeterAlwaysShow", values = {false, true}, default = false, force = false},
}

#towing.attachDistance

Maximum bumper-to-bumper attachment distance in meters for basic ropes. Cables use their winch maximum.

Example:

lua
attachDistance = 9.0

#towing.selectDistance

Maximum player-to-vehicle distance in meters for automatic attach/detach selection.

Example:

lua
selectDistance = 7.0

#towing.requireBothStopped

Requires both vehicles to be nearly stationary when attaching.

Example:

lua
requireBothStopped = true

#towing.maxAttachSpeedKmh

Maximum attachment speed when requireBothStopped is enabled, in km/h.

Example:

lua
maxAttachSpeedKmh = 6.0

#towing.requireEmptyTowed

Requires the towed driver seat to be empty. false allows a driver in the load.

Example:

lua
requireEmptyTowed = false

#towing.requireUnlocked

Rejects locked towed vehicles when enabled.

Example:

lua
requireUnlocked = false

#towing.requireItem

Consumes the material item after a successful player attachment. Manual detachment refunds item-funded connections; breakage does not.

Example:

lua
requireItem = true

#towing.defaultRopeLength

Fixed basic-rope length in meters. Cables start at attachment distance instead.

Example:

lua
defaultRopeLength = 7.0

#towing.attachTimeMs

Attachment progress duration in milliseconds; 0 skips the bar.

Example:

lua
attachTimeMs = 3500

#towing.detachTimeMs

Detachment progress duration in milliseconds; 0 skips the bar.

Example:

lua
detachTimeMs = 2000

#towing.carryEndDistance

Player reach in meters for bumper placement and detachment.

Example:

lua
carryEndDistance = 1.0

#towing.carryDistance

Minimum carrying range in meters. The allowed range extends to the material attachment distance plus player reach.

Example:

lua
carryDistance = 12.0

#towing.carryTimeoutMs

Maximum duration of a carrying session in milliseconds.

Example:

lua
carryTimeoutMs = 300000

#towing.maxTowSpeedKmh

Towing speed cap in km/h. 0 leaves normal vehicle speed uncapped by this setting.

Example:

lua
maxTowSpeedKmh = 0

#towing.pullPowerMultiplier

Pulling-torque assistance while the rope is taut. 1.0 leaves pulling unassisted.

Example:

lua
pullPowerMultiplier = 1.0

#towing.launchTractionLossMultiplier

Scales additional low-speed traction loss while towing. 0 disables that loss; 1 retains normal handling.

Example:

lua
launchTractionLossMultiplier = 0.0

#towing.blockedClasses

Vehicle classes excluded from towing. Default exclusions are bicycles, boats, helicopters, planes, and trains.

Example:

lua
blockedClasses = {[13] = true, [14] = true, [15] = true, [16] = true, [21] = true}

#towing.terrainIntegration.enabled

Reads Vehicle Terrain state when that resource is started.

Example:

lua
enabled = true

#towing.terrainIntegration.stuckDepthThreshold

Terrain depth threshold used to identify a stuck tow load in attachment feedback.

Example:

lua
stuckDepthThreshold = 0.05

#towing.terrainIntegration.towerSoftPenalty

Scales the soft-ground reduction of the configured towing speed cap. Applies only when maxTowSpeedKmh is positive.

Example:

lua
towerSoftPenalty = 0.5

#towing.terrainIntegration.maxPullReduction

Maximum fraction of pulling torque removed by the load terrain penalty.

Example:

lua
maxPullReduction = 0.65

#towing.terrainIntegration.massInfluence

Relieves terrain penalties for lighter loads. 0 disables mass-based relief; 1 uses the full mass ratio. Equal or heavier loads retain the original penalty.

Example:

lua
massInfluence = 0.5

#Rope Materials

Each entry under Config.Settings.towing.ropeMaterials owns its item, winch settings, carried prop, anchors, visuals, and break rules. Defaults use rope and metal. In the paths below, <material> means one of these keys.

#towing.ropeMaterials.<material>.ropeItem

Inventory item consumed for this material. Item definitions and usable-item registration must match.

Example:

lua
ropeItem = "tow_rope"

#towing.ropeMaterials.<material>.winch

Use false for fixed-length rope or a table for adjustable cable. The table below is the steel-cable default.

Example:

lua
winch = {minLength = 3.0, maxLength = 30.0, speed = 1.0, catchupSpeed = 2.0}

#towing.ropeMaterials.<material>.winch.minLength

Minimum cable length in meters.

Example:

lua
minLength = 3.0

#towing.ropeMaterials.<material>.winch.maxLength

Maximum cable length and cable attachment range in meters.

Example:

lua
maxLength = 30.0

#towing.ropeMaterials.<material>.winch.speed

Cable reel-in / pay-out speed in meters per second while holding a winch key.

Example:

lua
speed = 1.0

#towing.ropeMaterials.<material>.winch.catchupSpeed

Recovery catch-up speed used to prevent tyre resistance from accumulating cable overstretch; keep recovery faster than the drum.

Example:

lua
catchupSpeed = 2.0

#towing.ropeMaterials.<material>.breakDistance

Absolute bumper separation that breaks this material, in meters. Set to false to disable. Basic rope defaults to 18; steel cable disables it.

Example:

lua
breakDistance = 18.0

#towing.ropeMaterials.<material>.breakSpeedKmh

Pulling-vehicle speed threshold that breaks this material. Set to false to disable. Basic rope defaults to 90; steel cable disables it.

Example:

lua
breakSpeedKmh = 90.0

#towing.ropeMaterials.<material>.breakOnTowedDriven

Breaks the connection if the towed vehicle is driven when enabled. Disabled for both default materials.

Example:

lua
breakOnTowedDriven = false

#towing.ropeMaterials.<material>.rope.ropeType

FiveM rope type used for the line visual. Basic rope uses 2; steel cable uses 6.

Example:

lua
ropeType = 2

#towing.ropeMaterials.<material>.rope.spawnDistance

Distance in meters within which the line visual is spawned.

Example:

lua
spawnDistance = 75.0

#towing.ropeMaterials.<material>.carryProp.model

Prop shown while carrying the material. Basic rope uses prop_stag_do_rope; cable uses prop_rope_family_3.

Example:

lua
model = "prop_stag_do_rope"

#towing.ropeMaterials.<material>.carryProp.bone

Ped bone ID used to attach the carried prop.

Example:

lua
bone = 57005

#towing.ropeMaterials.<material>.carryProp.ropeBone

Ped bone name used for the carried rope endpoint.

Example:

lua
ropeBone = "IK_R_Hand"

#towing.ropeMaterials.<material>.carryProp.offset

Carried prop position relative to its ped bone. This is the basic-rope default; the full config includes cable alignment.

Example:

lua
offset = vector3(0.35552558302879, 0.0128183029592, 0.00060697877779)

#towing.ropeMaterials.<material>.carryProp.rotation

Carried prop rotation in degrees. This is the basic-rope default.

Example:

lua
rotation = vector3(143.31787109375, 150.04833984375, -43.87148666381836)

#towing.ropeMaterials.<material>.carryProp.rotationOrder

Rotation order passed to the prop attachment native.

Example:

lua
rotationOrder = 1

#towing.ropeMaterials.<material>.carryProp.useSoftPinning

Soft-pinning flag for the held prop attachment.

Example:

lua
useSoftPinning = false

#towing.ropeMaterials.<material>.carryProp.collision

Collision flag used for the held prop.

Example:

lua
collision = false

#towing.ropeMaterials.<material>.carryProp.syncRotation

Synchronizes the held prop rotation with its attachment.

Example:

lua
syncRotation = true

#towing.ropeMaterials.<material>.carryProp.front.bones

Ordered vehicle bone candidates for the front anchor.

Example:

lua
bones = {"neon_f", "bumper_f"}

#towing.ropeMaterials.<material>.carryProp.front.offset

Centered front-anchor adjustment in vehicle-local meters.

Example:

lua
offset = vector3(0.0, 0.1, -0.05)

#towing.ropeMaterials.<material>.carryProp.rear.bones

Ordered vehicle bone candidates for the rear anchor.

Example:

lua
bones = {"neon_b", "bumper_r"}

#towing.ropeMaterials.<material>.carryProp.rear.offset

Centered rear-anchor adjustment in vehicle-local meters.

Example:

lua
offset = vector3(0.0, -0.1, -0.05)

#Vehicle Beds

#beds.access

Access mode: "keys" requires carrier keys, "jobs" requires a listed job, and "none" allows anyone through this access check. In keys mode attached trailers use the towing vehicle keys; unattached trailers need no keys. Command permissions and hooks still apply.

Example:

lua
access = "keys"

#beds.jobs

Job names allowed in jobs mode. An empty array allows nobody.

Example:

lua
jobs = {"mechanic"}

#beds.selectDistance

Interaction range around the carrier loading point, not the vehicle center.

Example:

lua
selectDistance = 10.0

#beds.loadingZoneSize

Global blue loading-box dimensions: width, length, and height in meters. The load vehicle origin must be inside it.

Example:

lua
loadingZoneSize = vector3(6.0, 8.0, 4.0)

#beds.maxSpeedKmh

Maximum speed for stationary bed operations. The small nonzero default allows physics jitter.

Example:

lua
maxSpeedKmh = 0.1

#beds.models

Supported model hashes and their carrier layout. Default models are flatbed, tr2, and trflat. The example defines a one-slot flatbed.

Example:

lua
models = {
    [GetHashKey("flatbed")] = {
        maxVehicleSize = vector3(2.8, 5.0, 3.0),
        loadingZoneOffset = vector3(0.0, -9.0, 0.0),
        slots = {
            {offset = vector3(0.0, -2.4, 0.4), rotation = vector3(0.0, 0.0, 0.0)},
        },
    },
}

#beds.models.<model>.maxVehicleSize

Maximum load width, length, and height. Flatbed and trflat use 2.8 × 5.0 × 3.0; tr2 uses 2.6 × 4.8 × 3.0.

Example:

lua
maxVehicleSize = vector3(2.8, 5.0, 3.0)

#beds.models.<model>.loadingZoneOffset

Loading-zone center relative to the carrier, also used as the offloading reference. Flatbed uses Y = -9; tr2 and trflat use Y = -11.

Example:

lua
loadingZoneOffset = vector3(0.0, -9.0, 0.0)

#beds.models.<model>.requireTrunkOpen

When enabled, requires the guard/trunk to be open for loading or unloading. Enabled for tr2; omitted for the other default models.

Example:

lua
requireTrunkOpen = true

#beds.models.<model>.trunkDoorServerIndex

Replicated door index for server trunk checks. Defaults to 5 when omitted; tr2 uses 1 because its client door 5 replicates as server door 1.

Example:

lua
trunkDoorServerIndex = 1

#beds.models.<model>.slots

One entry per parking space, ordered by one-based slot index. Add separate floor heights for multi-deck layouts.

Example:

lua
slots = {
    {offset = vector3(0.0, -2.4, 0.4), rotation = vector3(0.0, 0.0, 0.0)},
}

#beds.models.<model>.slots.<slot>.offset

Center of the deck floor in carrier-local meters. Vehicle bounds are centered horizontally and their rotated bottom rests on this plane.

Example:

lua
offset = vector3(0.0, -2.4, 0.4)

#beds.models.<model>.slots.<slot>.rotation

Loaded vehicle rotation relative to the carrier in degrees.

Example:

lua
rotation = vector3(0.0, 0.0, 0.0)

#beds.models.<model>.slots.<slot>.maxVehicleHeight

Optional slot-specific height limit overriding the model height. The three lower tr2 slots use 1.8 meters to leave upper-deck clearance.

Example:

lua
maxVehicleHeight = 1.8