Documentation

Can-Check Hooks

Hook functions that decide who may fit, remove, lockpick, grind, pay and pick up clamps. Return false to deny.

Can-check hooks allow you to control who may fit, remove, lockpick and grind clamps, use the windscreen keypad, smash a windscreen, pay a release fee, pick up a dropped clamp, use a supply ped, and answer assistance requests. Return false with an optional locale key to deny an action and notify the player.

#File Locations

SideFile
Serverserver/unlocked/can_checks.lua
Clientclient/unlocked/can_checks.lua

Both files are unencrypted and safe to edit directly. Edit the existing functions inside Wheel Clamp.

Types / Classes

All types / classes can be found in types/types.lua. Vehicle arguments are entity handles; plyId is the requesting player's server ID.


#How Reason Strings Work

#Server-side reasons

The server returns the reason to the client, which shows it through Z.notify(), so use a locale key from locales/. Missing reasons fall back to "noPermission".

#Client-side reasons

Client checks also use locale keys and fall back to "noPermission". They give early feedback and decide which options show; enforce trusted restrictions in the matching server hook. Add custom reason keys to every resource locale.


#Execution & Validation

Keep hooks fast and free of side effects, since they can run repeatedly. Returning true continues the normal flow; distance, vehicle speed, occupied wheel, and inventory checks stay in the locked code and always apply.

By default, the hooks check the job lists in jobRequirements, officer, vendor, and phone.assistance.

Server exports such as FitVehicleClamp don't run the player action hooks.


#Server-Sided Hooks

All server-sided hooks are in server/unlocked/can_checks.lua.

#Can Use Wheelclamp Item

Called when a player uses a clamp item, before aiming starts. Refuses items that aren't in clamps by default.

Example:

lua
---@param plyId integer
---@param itemName string
---@return boolean allowed
---@return string? reason
function CanUseWheelclampItem(plyId, itemName)
    if (not GetWheelclampDesign(itemName)) then return false, "clampItemUnknown" end

    return true
end

#Can Install Wheelclamp

Called before a clamp is fitted and the item is taken. Checks jobRequirements.install and that the player still has the clamp. wheel is the clamp slot, such as "lf" or "windscreen".

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param itemName string
---@return boolean allowed
---@return string? reason
function CanInstallWheelclamp(plyId, vehicle, wheel, itemName)
    if (not hasRequiredClampJob(plyId, "install")) then return false, "noPermission" end
    if (Config.Settings.wheelclamp.consumeItem == true and not Z.hasItem(plyId, itemName, 1)) then
        return false, "clampMissing"
    end

    return true
end

#Can Remove Wheelclamp

Called before a clamp is taken off with its key, by an officer, or without a key, before the item is returned. Checks jobRequirements.remove.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanRemoveWheelclamp(plyId, vehicle, wheel, clamp)
    if (not hasRequiredClampJob(plyId, "remove")) then return false, "noPermission" end

    return true
end

#Can Override Wheelclamp

Decides whether a player may take a keyed clamp off without its key. CanRemoveWheelclamp still applies. By default, players on officer.jobs while officer.override is on.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param clamp WheelclampRecord
---@return boolean allowed
function CanOverrideWheelclamp(plyId, vehicle, wheel, clamp)
    if ((Config.Settings.wheelclamp.officer or {}).override ~= true) then return false end

    return isClampOfficer(plyId)
end

#Can Lockpick Wheelclamp

Called before the pick takes damage and the clamp comes off. Checks jobRequirements.lockpick.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanLockpickWheelclamp(plyId, vehicle, wheel, clamp)
    if (not hasRequiredClampJob(plyId, "lockpick")) then return false, "noPermission" end

    return true
end

#Can Grind Wheelclamp

Called before the grinder starts and the clamp drops. Checks jobRequirements.grind.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanGrindWheelclamp(plyId, vehicle, wheel, clamp)
    if (not hasRequiredClampJob(plyId, "grind")) then return false, "noPermission" end

    return true
end

#Can Pay Wheelclamp Release

Called before any money is taken for a wheel clamp's release fee, from the notice, the phone app or the website. Allows everyone by default.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param wheel string
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanPayWheelclampRelease(plyId, vehicle, wheel, clamp)
    return true
end

#Can Use Windscreen Keypad

Narrows who may use a windscreen clamp's keypad to enter the code or pay. The code and payment are checked afterwards. Allows everyone by default.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanUseWindscreenKeypad(plyId, vehicle, clamp)
    return true
end

#Can Pay Windscreen Clamp

Called before any money is taken for a windscreen clamp's release fee. Allows everyone by default.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanPayWindscreenClamp(plyId, vehicle, clamp)
    return true
end

#Can View Windscreen Code

Decides whether a player sees the release code on the keypad. By default, players on officer.jobs while officer.codeLookup is on. Every lookup fires OnWindscreenCodeViewed.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param clamp WheelclampRecord
---@return boolean allowed
function CanViewWindscreenCode(plyId, vehicle, clamp)
    if ((Config.Settings.wheelclamp.officer or {}).codeLookup ~= true) then return false end

    return isClampOfficer(plyId)
end

#Can Smash Windscreen Clamp

Called before the windscreen is smashed and the alarm trips. Allows everyone holding a configured weapon by default.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param clamp WheelclampRecord
---@return boolean allowed
---@return string? reason
function CanSmashWindscreenClamp(plyId, vehicle, clamp)
    return true
end

#Can Pickup Dropped Clamp

Called before a dropped clamp is picked up and the item is given. Allows everyone by default.

Example:

lua
---@param plyId integer
---@param prop integer @ Dropped clamp entity
---@param record WheelclampDroppedRecord
---@return boolean allowed
---@return string? reason
function CanPickupDroppedClamp(plyId, prop, record)
    return true
end

#Can Use Clamp Vendor

Called for every purchase from and sale to a supply ped. Checks the ped's jobs and onDutyOnly.

Example:

lua
---@param plyId integer
---@param vendor WheelclampVendor
---@return boolean allowed
---@return string? reason
function CanUseClampVendor(plyId, vendor)
    if (type(vendor.jobs) == "table" and #vendor.jobs > 0 and not Z.isJob(plyId, vendor.jobs)) then return false, "noPermission" end

    local job = vendor.onDutyOnly == true and Z.getJob(plyId) or nil
    if (job and job.onDuty == false) then return false, "vendorOffDuty" end

    return true
end

#Can Request Clamp Assistance

Called before an assistance request is sent from the phone app or website. Allows everyone by default.

Example:

lua
---@param plyId integer
---@param vehicle integer @ Clamped vehicle the request is for
---@return boolean allowed
---@return string? reason
function CanRequestClampAssistance(plyId, vehicle)
    return true
end

#Can Respond To Clamp Assistance

Decides who an assistance request reaches and who may answer it: the clamp's fitter with notifyFitter, and players on phone.assistance.jobs, on duty with onDutyOnly.

Example:

lua
---@param plyId integer
---@param request ClampAssistanceRequest
---@return boolean allowed
function CanRespondToClampAssistance(plyId, request)
    local settings = Config.Settings.wheelclamp.phone.assistance
    if (settings.notifyFitter == true and request.fitters[Z.getIdentifier(plyId)]) then return true end

    local jobs = settings.jobs
    if (type(jobs) ~= "table" or #jobs == 0 or not Z.isJob(plyId, jobs)) then return false end

    local job = settings.onDutyOnly == true and Z.getJob(plyId) or nil

    return not job or job.onDuty ~= false
end

#Client-Sided Hooks

All client-sided hooks are in client/unlocked/can_checks.lua. CanUseWheelclampItem, CanInstallWheelclamp, CanRemoveWheelclamp, CanOverrideWheelclamp, CanLockpickWheelclamp, CanGrindWheelclamp, CanUseWindscreenKeypad, CanSmashWindscreenClamp, CanPickupDroppedClamp and CanUseClampVendor mirror the server hooks without the plyId argument. Mirror your server rules there. They refuse an action before it starts, and CanUseClampVendor and CanPickupDroppedClamp also hide their option.

#Can Display Wheelclamp Remove

Decides whether "Remove wheelclamp" shows on a clamped vehicle. By default it shows to players allowed by jobRequirements.remove who carry the matching key, or are officers. Runs while the option is visible, so keep it fast.

Example:

lua
---@param vehicle integer
---@param wheel? string @ Slot of the interaction point; the target menu checks every wheel
---@return boolean visible
function CanDisplayWheelclampRemove(vehicle, wheel)
    -- Default body in client/unlocked/can_checks.lua
end

#Is Clamp Assistance Responder

Mirrors the job rule of CanRespondToClampAssistance, so other resources such as zyke_towing can show their responder page. Also available as an export.

Example:

lua
---@return boolean responder
function IsClampAssistanceResponder()
    -- Default body in client/unlocked/can_checks.lua
end

#Common Patterns

#Only Mechanics Can Grind Clamps Off

Set the job in the config, or check it in the server hook.

Example:

lua
jobRequirements = {
    install = {},
    remove = {},
    lockpick = {},
    grind = {"mechanic"},
}

#Only Police Can Pick Up Dropped Clamps

Check the job in the server hook, and mirror it in the client hook so the pickup option only shows to police.

Example:

lua
-- server/unlocked/can_checks.lua
function CanPickupDroppedClamp(plyId, prop, record)
    if (not Z.isJob(plyId, {"police"})) then return false, "noPermission" end

    return true
end

-- client/unlocked/can_checks.lua
function CanPickupDroppedClamp(prop)
    if (not Z.isJob({"police"})) then return false, "noPermission" end

    return true
end