Exports & Events

General Information

Client vehicle arguments are local entity handles. Server creation arguments are network IDs. Material names are config keys: rope is the basic rope and metal is the steel cable. Omitted ends default to tower rear and towed front.

Types / Classes

All types / classes can be found in types/types.lua inside zyke_towing.

The tow exports describe rope/cable connections; they do not report vehicle-bed occupancy. There are currently no bed-loading exports.

#Complete Export Index

#Client Sided Exports

#Attach Tow Vehicle

Runs the normal attachment flow with progress, client checks, server validation, and configured item consumption. Returns true after attachment succeeds, otherwise false. Run from a yielding client context. skipProgress skips only the progress bar.

Example:

lua
---@param tower integer @ Vehicle doing the pulling
---@param towed integer @ Vehicle being pulled
---@param skipProgress? boolean @ Skips only the progress bar
---@param material? string @ Config key, defaults to rope
---@param towerEnd? "rear" | "front" @ Defaults to rear
---@param towedEnd? "rear" | "front" @ Defaults to front
---@return boolean attached
local attached = exports["zyke_towing"]:AttachTowVehicle(tower, towed, skipProgress, material, towerEnd, towedEnd)

#Detach Tow Vehicle

Detaches one connection from a vehicle using the player flow. The player must remain within reach of the relevant bumper throughout the progress action. An item-funded connection refunds its item to the detaching player. Returns a boolean; run from a yielding client context.

When the end is omitted, selection favors the closest connected bumper on foot; seated selection prefers the outgoing connection.

Example:

lua
---@param vehicle integer
---@param endName? "front" | "rear"
---@return boolean detached
local detached = exports["zyke_towing"]:DetachTowVehicle(vehicle, endName)

#Is Vehicle In Tow

Returns whether the vehicle participates in a cached rope/cable connection in either role.

Example:

lua
---@param vehicle integer
---@return boolean inTow
local inTow = exports["zyke_towing"]:IsVehicleInTow(vehicle)

#Is Vehicle Towing

Returns whether the vehicle is the pulling endpoint of a connection.

Example:

lua
---@param vehicle integer
---@return boolean towing
local towing = exports["zyke_towing"]:IsVehicleTowing(vehicle)

#Is Vehicle Towed

Returns whether the vehicle is the pulled endpoint of a connection. A middle vehicle in a chain can be both towing and towed.

Example:

lua
---@param vehicle integer
---@return boolean towed
local towed = exports["zyke_towing"]:IsVehicleTowed(vehicle)

#Get Tow Data

Returns a copy of one matching TowRecord, or nil. Selection uses the same nearest-bumper / outgoing-connection rules as detachment; this is not a list of every link on the vehicle. Chain orientation can change as drivers enter vehicles.

Example:

lua
---@param vehicle integer
---@return TowRecord? tow
local tow = exports["zyke_towing"]:GetTowData(vehicle)

#Get Simulation Vehicles

Returns a map of empty towed vehicle entity handles to network IDs eligible for simulation by this client. This is not an array or a list of every tow on the server. Ownership, driver control, and players entering vehicles affect eligibility. Treat the returned map as read-only.

Example:

lua
---@return table<integer, integer> vehicles @ Vehicle entity handles mapped to network IDs
local vehicles = exports["zyke_towing"]:GetSimulationVehicles()

#Is Carrying Rope

Returns whether the player currently has an active carrying state.

Example:

lua
---@return boolean carrying
local carrying = exports["zyke_towing"]:IsCarryingRope()

#Use Tow Rope

Equips the requested material on foot after action and inventory checks. Calling again with the currently carried material cancels carrying. Returns a boolean for the carry operation, not confirmation of a completed vehicle connection. Run from a yielding client context.

Material defaults to rope. Leave stow omitted for player integrations; true is used by the detach flow to briefly show and pocket the returned rope.

Example:

lua
---@param material? string @ Config key, defaults to rope
---@param stow? boolean @ Briefly shows and pockets a detached rope; omit for normal equipping
---@return boolean equipped
local equipped = exports["zyke_towing"]:UseTowRope(material, stow)

#Use Tow Cable

Calls UseTowRope("metal") with the same carry behavior and boolean result.

Example:

lua
---@return boolean equipped
local equipped = exports["zyke_towing"]:UseTowCable()

#Cancel Tow Carry

Cancels carrying. No return value.

Leave placed omitted for cancellation; the attachment flow uses true when placement has already succeeded.

Example:

lua
---@param placed? boolean @ Set only when the rope was successfully attached
exports["zyke_towing"]:CancelTowCarry(placed)

#Server Sided Exports

CreateTowRecord and RemoveTowRecord are trusted server operations. They bypass player action hooks, progress, inventory consumption/refunds, and player permission checks. Validate your own caller and gameplay requirements before using them. Do not expose them directly through an unrestricted network event.

#Create Tow Record

Creates and synchronizes a connection. Returns a TowRecord, or nil for invalid entities, ends, material, topology, or mismatched routing buckets. It does not apply the full player attachment rules such as speed, distance, locks, occupancy, or class restrictions.

Basic ropes ignore ropeLength and use defaultRopeLength. Cables round length up to a tenth of a meter and clamp it to their winch limits. When omitted or invalid, cable length falls back to the distance between vehicle centers; pass the measured bumper distance when available.

Example:

lua
---@param towerNetId integer @ Network ID of the pulling vehicle
---@param towedNetId integer @ Network ID of the pulled vehicle
---@param ropeLength? number @ Cable length in meters; ignored for basic ropes
---@param material? string @ Config key, defaults to rope
---@param towerEnd? "rear" | "front" @ Defaults to rear
---@param towedEnd? "rear" | "front" @ Defaults to front
---@return TowRecord? tow
local tow = exports["zyke_towing"]:CreateTowRecord(towerNetId, towedNetId, ropeLength, material, towerEnd, towedEnd)

#Remove Tow Record

Removes and synchronizes one connection by its string ID. Unknown IDs are ignored. No return value and no item refund.

Example:

lua
---@param towId string
exports["zyke_towing"]:RemoveTowRecord(towId)

#Get Active Tows

Returns the active map keyed by tow ID. Treat it and its records as read-only; use the creation/removal exports for changes.

Example:

lua
---@return table<string, TowRecord> tows @ Active connections keyed by tow ID
local tows = exports["zyke_towing"]:GetActiveTows()

#Tow Record

#Client Local Events

These are local integration notifications, not server-authorized requests.

#Simulation Vehicles Changed

Receives the same entity-handle-to-network-ID map as GetSimulationVehicles when the local simulation set changes. An empty map clears the set.

Example:

lua
---@param vehicles table<integer, integer> @ Vehicle entity handles mapped to network IDs
AddEventHandler("zyke_towing:SimulationVehiclesChanged", function(vehicles)
    for vehicle, netId in pairs(vehicles) do
        print(vehicle, netId)
    end
end)

#Query Simulation Vehicles

A callback-style alternative for integrations. A handler is present only while towing has active topology, so initialize your result to an empty map.

Example:

lua
---@type table<integer, integer>
local vehicles = {}

---@param result table<integer, integer> @ Vehicle entity handles mapped to network IDs
TriggerEvent("zyke_towing:GetSimulationVehicles", function(result)
    vehicles = result
end)

#On Personal Setting Changed

Fires when the player saves a personal setting. Receives its name and actual validated value, not the menu option index.

Example:

lua
---@param setting string
---@param value string | boolean | number
AddEventHandler("zyke_towing:OnPersonalSettingChanged", function(setting, value)
    print(setting, value)
end)

For custom permission rules, use Can-Check Hooks.