Documentation

Exports & Events

All exports, events, hooks and state bags available to integrate Wheel Clamp into other resources.

General Information

Clamp slots are lf, rf, lr and rr for the front-left, front-right, rear-left and rear-right wheels, and windscreen. Vehicle arguments are entity handles unless stated otherwise. Plates are compared without spaces and case.

Types / Classes

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

Suggestions?

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

#Complete Export Index

ContextExports
ServerFitVehicleClamp, RemoveVehicleClamp, IsVehicleClamped, IsWheelclamped, GetWindscreenClampCode, GetWindscreenClampCodeByPlate, GetVehicleClampData, SetVehicleClampData, RestoreVehicleClamps, FlushVehicleClamps, ForgetVehicleClamps, GetVehicleClampPersistenceStats, GetClampAssistanceJobs
ClientIsVehicleClamped, GetVehicleClampData, SetVehicleClampData, IsClampAssistanceResponder, GetClampAssistanceRequests, RunClampAssistanceAction

#Server Sided Exports

Server exports are trusted operations. They bypass items, keys, payments, distance checks and the can-check hooks. Validate your own caller before using them, and don't expose them through an unrestricted network event.

#Fit Vehicle Clamp

Fits a clamp without a player or an item, for jobs, impounds and admin tools. The vehicle can be moving and nobody needs to stand beside it. item is a clamp from Config.Settings.wheelclamp.clamps, and a windscreen design only fits the windscreen slot. A windscreen clamp without a code gets a random one. Returns whether it fitted, the reason when it did not, and the release code of a windscreen clamp.

Example:

lua
---@param vehicle integer
---@param slot "lf" | "rf" | "lr" | "rr" | "windscreen"
---@param item string @ Clamp item, such as "clamp_triangle"
---@param options? {fee?: integer, code?: string, note?: string, keyTo?: integer, source?: integer}
---@return boolean fitted
---@return string? reason @ Locale key, such as "clampWheelOccupied"
---@return string? code @ Release code of a windscreen clamp
local fitted, reason, code = exports["zyke_wheelclamp"]:FitVehicleClamp(vehicle, "lf", "clamp_triangle", {
    fee = 1000, -- Release fee, the configured one when left out
    note = "Unpaid parking", -- Note on the clamp notice
    keyTo = plyId, -- Player who gets the clamp key
    source = plyId, -- Player named as the fitter
})

#Remove Vehicle Clamp

Takes the clamp in slot, or every clamp when slot is nil, off without a key or payment. Returns how many came off. With returnTo, that player gets the clamp items back; a clamp that doesn't fit their inventory drops beside the vehicle. Without it, the clamps are deleted.

Example:

lua
---@param vehicle integer
---@param slot? "lf" | "rf" | "lr" | "rr" | "windscreen"
---@param options? {returnTo?: integer, source?: integer}
---@return integer removed
local removed = exports["zyke_wheelclamp"]:RemoveVehicleClamp(vehicle, nil, {returnTo = plyId, source = plyId})

#Is Vehicle Clamped

Returns whether the vehicle has a clamp fitted, read from the stored record.

Example:

lua
---@param vehicle integer
---@return boolean clamped
local clamped = exports["zyke_wheelclamp"]:IsVehicleClamped(vehicle)

#Is Wheelclamped

The same as IsVehicleClamped, by network ID.

Example:

lua
---@param netId integer
---@return boolean clamped
local clamped = exports["zyke_wheelclamp"]:IsWheelclamped(netId)

#Get Windscreen Clamp Code

Returns the release code and fee of the windscreen clamp on this vehicle, or nil without one. Use it to hand the code out with a fine, for example once the fine is paid.

Example:

lua
---@param vehicle integer
---@return string? code
---@return integer? fee
local code, fee = exports["zyke_wheelclamp"]:GetWindscreenClampCode(vehicle)

#Get Windscreen Clamp Code By Plate

The same by plate, ignoring spaces and case. It also finds clamps on stored vehicles; a clamp on a vehicle that is out wins over a stored one with the same plate.

Example:

lua
---@param plate string
---@return string? code
---@return integer? fee
local code, fee = exports["zyke_wheelclamp"]:GetWindscreenClampCodeByPlate("ABC 123")

#Get Vehicle Clamp Data

Returns the vehicle's saved clamp record, or nil without clamps. clamps holds each fitted clamp by slot, with its item, model, fee, installedBy and, for a windscreen clamp, its code.

Example:

lua
---@param vehicle integer
---@return {id: string, version: integer, entity?: integer, clamps: table<string, WheelclampRecord>}? data
local data = exports["zyke_wheelclamp"]:GetVehicleClampData(vehicle)

#Set Vehicle Clamp Data

Puts a saved clamp record on a vehicle, for server-side vehicle property stores. A record id that still exists is bound to the vehicle; otherwise a new record is created from data. Returns whether it was applied.

Example:

lua
---@param vehicle integer
---@param data table @ A record from GetVehicleClampData
---@param identity? WheelclampIdentityInput
---@return boolean applied
local applied = exports["zyke_wheelclamp"]:SetVehicleClampData(vehicle, data)

#Restore Vehicle Clamps

Looks up the saved clamps for a vehicle and puts them back on it, for garage integrations. identity can be a record id or an explicit vehicle identity. Without it, the vehicle is matched through its state bags and the owned vehicle tables.

Example:

lua
---@param vehicle integer
---@param identity? string | WheelclampIdentityInput
---@return boolean restored
local restored = exports["zyke_wheelclamp"]:RestoreVehicleClamps(vehicle)

#Flush Vehicle Clamps

Writes pending clamp changes to the database straight away, instead of after the 5 second save delay. Takes a vehicle, a record id or a vehicle identity id; nil flushes everything.

Example:

lua
---@param vehicleOrId? integer | string
---@return boolean flushed
local flushed = exports["zyke_wheelclamp"]:FlushVehicleClamps()

#Forget Vehicle Clamps

Deletes the saved clamp record of a vehicle, record id or vehicle identity id, and clears the clamps from the vehicle if it is out. No events are fired and no items are returned.

Example:

lua
---@param vehicleOrId integer | string
---@return boolean forgotten
local forgotten = exports["zyke_wheelclamp"]:ForgetVehicleClamps(vehicle)

#Get Vehicle Clamp Persistence Stats

Returns the state of clamp saving, for diagnostics.

Example:

lua
---@return {ready: boolean, records: integer, dirty: integer, databaseWrites: integer, saveDelayMs: integer} stats
local stats = exports["zyke_wheelclamp"]:GetVehicleClampPersistenceStats()

#Get Clamp Assistance Jobs

Returns the jobs that answer assistance requests, or an empty table while assistance is off. zyke_towing uses it to register its Tow Dispatch app for them.

Example:

lua
---@return table jobs @ Entries in the job list format
local jobs = exports["zyke_wheelclamp"]:GetClampAssistanceJobs()

#Client Sided Exports

#Is Vehicle Clamped

Returns whether the vehicle shows a clamp, read from its state bag. Use the server export for anything that matters.

Example:

lua
---@param vehicle integer
---@return boolean clamped
local clamped = exports["zyke_wheelclamp"]:IsVehicleClamped(vehicle)

#Get Vehicle Clamp Data

Returns a pointer to the vehicle's saved clamps, or nil without clamps. Used to save clamps in framework vehicle properties; see Vehicle Properties.

Example:

lua
---@param vehicle integer
---@return {id: string, version: integer}? data
local data = exports["zyke_wheelclamp"]:GetVehicleClampData(vehicle)

#Set Vehicle Clamp Data

Asks the server to put back the clamps a saved pointer refers to. It also accepts a whole properties table holding zykeWheelclamp. The server checks the vehicle, its owner and the player before restoring, and the call never hangs, so it is safe in a properties setter.

Example:

lua
---@param vehicle integer
---@param data {id: string, version: integer}
---@return boolean restored
local restored = exports["zyke_wheelclamp"]:SetVehicleClampData(vehicle, props.zykeWheelclamp)

#Is Clamp Assistance Responder

Returns whether the local player is on the jobs that answer assistance requests. Fitters, who are only known per request, still answer from the phone app or the website.

Example:

lua
---@return boolean responder
local responder = exports["zyke_wheelclamp"]:IsClampAssistanceResponder()

#Get Clamp Assistance Requests

Returns the assistance requests the local player can answer, newest first, as shown in the app.

Example:

lua
---@return table[] requests
local requests = exports["zyke_wheelclamp"]:GetClampAssistanceRequests()

#Run Clamp Assistance Action

Runs a responder action on a request: "Respond", "Waypoint" or "CloseRequest". Returns whether it worked and the message to show.

Example:

lua
---@param action "Respond" | "Waypoint" | "CloseRequest"
---@param requestId string
---@return boolean done
---@return string? message
local done, message = exports["zyke_wheelclamp"]:RunClampAssistanceAction("Respond", requestId)

#Client Local Events

#On Clamp Assistance Changed

Fires whenever the assistance requests change. Read them again with GetClampAssistanceRequests.

Example:

lua
AddEventHandler("zyke_wheelclamp:OnClampAssistanceChanged", function()
    local requests = exports["zyke_wheelclamp"]:GetClampAssistanceRequests()
end)

#Server Local Events

These events are local server notifications, not network events. Listen with AddEventHandler on the server.

The clamp events share one shape: source (the player, nil for scripts, burst tyres and broken glass), vehicle (netId, plate, model and coords), slot, item, fee and installedBy.

#On Clamp Fitted

Fires for every clamp fitted. method is "item" or "script".

Example:

lua
---@param data WheelclampEventData
AddEventHandler("zyke_wheelclamp:OnClampFitted", function(data)
    print(data.source, data.vehicle.plate, data.slot, data.item, data.fee, data.method)
end)

#On Clamp Removed

Fires for every clamp taken off. method is one of:

MethodMeaning
keyUnlocked with its key.
overrideAn officer took it off without the key.
removeTaken off without needing a key.
lockpickLockpicked.
grindCut off with an angle grinder.
paidThe release fee was paid.
releaseReleased at the windscreen keypad.
smashThe windscreen was broken.
burstThe tyre burst.
adminRemoved with the admin command.
scriptRemoved by the RemoveVehicleClamp export.

Example:

lua
---@param data WheelclampEventData
AddEventHandler("zyke_wheelclamp:OnClampRemoved", function(data)
    print(data.source, data.vehicle.plate, data.slot, data.method)
end)

#On Clamp Paid

Fires for every release fee paid. amount is the fee taken, society the account it went to, and remote whether it was paid in the phone app or on the website.

Example:

lua
---@param data WheelclampEventData
AddEventHandler("zyke_wheelclamp:OnClampPaid", function(data)
    print(data.source, data.vehicle.plate, data.amount, data.society, data.remote)
end)

#On Windscreen Code Viewed

Fires when an officer reads a windscreen release code on the keypad.

Example:

lua
---@param data WheelclampEventData
AddEventHandler("zyke_wheelclamp:OnWindscreenCodeViewed", function(data)
    print(data.source, data.vehicle.plate)
end)

#On Dropped Clamps Cleared

Fires when /clearclamps deleted dropped clamps.

Example:

lua
---@param data {source: integer, count: integer, radius: number}
AddEventHandler("zyke_wheelclamp:OnDroppedClampsCleared", function(data)
    print(data.source, data.count, data.radius)
end)

#On Police Alert

Fires for every police alert that goes out, after the chance, delay and cooldown. type is "lockpick", "grind" or "alarm", and reason is "moved", "tamper" or "smash" for alarms. For dispatch, prefer editing OnWheelclampAlert in server/unlocked/police_alert.lua, which receives the same data.

Example:

lua
---@param data WheelclampAlertData
AddEventHandler("zyke_wheelclamp:OnPoliceAlert", function(data)
    print(data.type, data.reason, data.plate, data.coords, data.netId, data.source)
end)

#On Clamp Assistance Requested

Fires for every assistance request sent from the phone app or website, with plate, coords, message and the recipients it reached.

Example:

lua
---@param request ClampAssistanceRequest
AddEventHandler("zyke_wheelclamp:OnClampAssistanceRequested", function(request)
    print(request.plate, request.coords, request.message, #request.recipients)
end)

#Server Hooks

These functions live in unencrypted files and are safe to edit.

HookFilePurpose
OnWheelclampAlert(data)server/unlocked/police_alert.luaRuns for every police alert. Call your dispatch here.
OnWindscreenClampFitted(plyId, vehicle, code, fee)server/unlocked/windscreen.luaRuns after a windscreen clamp is fitted. Hand the release code to your fine, billing, MDT or phone resource here.
OnClampAssistanceRequested(request)server/unlocked/phone.luaRuns for every assistance request. Call your dispatch here with request.coords, request.plate and request.message.
GetWheelclampReleaseFee(plyId, vehicle, wheel)server/unlocked/notice.luaPrices a wheel clamp's release fee when it is fitted.
GetWindscreenClampFee(plyId, vehicle)server/unlocked/windscreen.luaPrices a windscreen clamp's release fee when it is fitted.
GetClampFitterNumber(plyId)server/unlocked/notice.luaReturns the fitter's phone number for the notice when fitterNumber is on.
PayClampSociety(society, amount)server/unlocked/notice.luaPays a release fee into the society account. Route fees elsewhere here.

#Logs

server/unlocked/hooks.lua listens to the server events above and sends zyke_lib webhook logs. Set a Discord webhook URL for each action in zyke_lib/webhooks/wheelclamp.lua; empty URLs are skipped.

ActionLogged When
ClampFittedA clamp is fitted.
ClampRemovedA clamp is taken off with its key, without needing a key, paid off, released at the keypad, or by a script.
ClampForcedA clamp is lockpicked, ground off, smashed off or burst off.
ClampPaidA release fee is paid.
OfficerOverrideAn officer takes a clamp off without its key, or reads a windscreen release code.
AdminActionAn admin removes clamps or clears dropped clamps.

#Client Hooks

HookFilePurpose
CallClampContact(contact)client/unlocked/notice.luaRuns when a number on a notice is tapped. Copies it by default; dial it through your phone here.
RequestWindscreenFitCode(vehicle, defaultFee)client/unlocked/windscreen.luaAsks the fitter for the release code. Return a code straight away to skip the form, for example one from your MDT.
ShowClampAssistanceAlert(alert, area)client/unlocked/phone.luaShows an assistance request to a responder: notification, phone banner, laptop notification and blip.

#State Bags

State BagContents
zyke_wheelclamp:clampsThe vehicle's fitted clamps by slot, without release codes or notes.
zyke_wheelclamp:clampRecordThe id and version of the vehicle's saved clamp record.

Read them, but change clamps through the server exports. The server writes back any change a client makes to these bags.

For custom permission rules, use Can-Check Hooks.