Can-Check Hooks

Hook functions that run before actions are executed. Return false to deny with an optional reason.

Can-check hooks allow you to intercept and control nearly every action in zyke_garages. Each hook function is called before its respective action executes. By default, all hooks return true, allowing the action to proceed.

To deny an action, return false along with an optional reason string. The reason is displayed to the player as a notification.

#File Locations

Side	File
Server	`server/unlocked/can_checks.lua`
Client	`client/unlocked/can_checks.lua`

Both files are unencrypted and safe to edit directly.

Types / Classes

All types / classes can be found in shared/unlocked/types.lua.

#How Reason Strings Work

When you return false, you can provide a second return value, a reason string, which is shown to the player as a notification.

#Server-side reasons

On the server, the reason string is returned in the callback response to the client. The client passes it to Z.notify(), which means it should be a locale key from your translations file.

If no reason is provided, a generic "noPermission" fallback is used.

Example:

lua
function CanSpawnVehicle(source, vin, garageId)
    if (someCondition) then
        return false, "noAccessToGarage"
    end

    return true
end

#Client-side reasons

On the client, the reason string is passed directly to Z.notify(). This means it should also be a locale key. If the reason is nil, no notification is shown at all.

Example:

lua
function CanOpenGarage(garageId, garageSettings)
    if (someCondition) then
        return false, "noAccessToGarage"
    end

    return true
end

#Server-Sided Hooks

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

#Can Lock Vehicle

Called before a vehicle is locked via the key fob.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param vehData table @PersistentVehicle entry
---@return boolean, string?
function CanLockVehicle(source, vin, vehData)
    return true
end

#Can Unlock Vehicle

Called before a vehicle is unlocked via the key fob.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param vehData table @PersistentVehicle entry
---@return boolean, string?
function CanUnlockVehicle(source, vin, vehData)
    return true
end

#Can Toggle Engine

Called before a vehicle's engine is toggled via the key fob.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param vehData table @PersistentVehicle entry
---@return boolean, string?
function CanToggleEngine(source, vin, vehData)
    return true
end

#Can Lockpick (Server)

Called before a player lockpicks a vehicle.

NOTE that this check also exists client-sided as CanLockpick in client/unlocked/can_checks.lua. Both checks must pass for the action to succeed.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param vehData table @PersistentVehicle entry
---@return boolean, string?
function CanLockpick(source, vin, vehData)
    return true
end

#Can Hotwire (Server)

Called before a player hotwires a vehicle.

NOTE that this check also exists client-sided as CanHotwire in client/unlocked/can_checks.lua. Both checks must pass for the action to succeed.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param vehData table @PersistentVehicle entry
---@return boolean, string?
function CanHotwire(source, vin, vehData)
    return true
end

#Can Spawn Vehicle

Called before a vehicle is spawned (taken out of a garage).

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param garageId string
---@return boolean, string?
function CanSpawnVehicle(source, vin, garageId)
    return true
end

#Can Store Vehicle (Server)

Called before a vehicle is stored (parked) in a garage.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param garageId string
---@return boolean, string?
function CanStoreVehicle(source, vin, garageId)
    return true
end

#Can Drive Away From Interior

Called before a vehicle is driven out of a garage interior.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param garageId string
---@return boolean, string?
function CanDriveAwayFromInterior(source, vin, garageId)
    return true
end

#Can Set New Owner

Called before a vehicle's ownership is changed.

NOTE that source can be a server ID, identifier, or "server" for internal transfers.

Example:

lua
---@param source PlayerId | string
---@param vin Vin
---@param newOwner string
---@return boolean, string?
function CanSetNewOwner(source, vin, newOwner)
    return true
end

#Can Transfer Garage

Called before a vehicle is transferred to another garage.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param garageId string
---@return boolean, string?
function CanTransferGarage(source, vin, garageId)
    return true
end

#Can Give Temp Keys

Called before temporary keys are given for an NPC vehicle.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@return boolean, string?
function CanGiveTempKeys(source, vin)
    return true
end

#Can Purchase Key

Called before a key is purchased from a garage.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@return boolean, string?
function CanPurchaseKey(source, vin)
    return true
end

#Can Impound Vehicle

Called before a vehicle is impounded.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param impoundDetails ImpoundDetails
---@return boolean, string?
function CanImpoundVehicle(source, vin, impoundDetails)
    return true
end

#Can Pay Impound

Called before an impound fee is paid.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@return boolean, string?
function CanPayImpound(source, vin)
    return true
end

#Can Apply Fake Plate

Called before a fake plate is applied to a vehicle.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param plate string
---@return boolean, string?
function CanApplyFakePlate(source, vin, plate)
    return true
end

#Can Remove Fake Plate

Called before a fake plate is removed from a vehicle.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@return boolean, string?
function CanRemoveFakePlate(source, vin)
    return true
end

#Can Set New Plate

Called before a vehicle's plate is permanently changed.

Example:

lua
---@param source PlayerId
---@param vin Vin
---@param plate string
---@return boolean, string?
function CanSetNewPlate(source, vin, plate)
    return true
end

#Can Scratch VIN

Called before a VIN is marked as scratched (untraceable).

Example:

lua
---@param vin Vin
---@return boolean, string?
function CanScratchVin(vin)
    return true
end

#Can Delete Scratched Vehicle

Called before a vehicle with a scratched VIN is deleted.

Example:

lua
---@param source PlayerId
---@param identifier string @VIN or plate
---@return boolean, string?
function CanDeleteScratchedVehicle(source, identifier)
    return true
end

#Client-Sided Hooks

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

#Can Open Garage

Called before a garage menu is opened.

Example:

lua
---@param garageId string
---@param garageSettings table @ClientGarage
---@return boolean, string?
function CanOpenGarage(garageId, garageSettings)
    if (garageId == "secret-garage") then
        return false, "noAccessToGarage"
    end

    return true
end

#Can Enter Garage Interior

Called before a player enters a garage interior.

Example:

lua
---@param garageId string
---@param garageSettings table @ClientGarage
---@return boolean, string?
function CanEnterGarageInterior(garageId, garageSettings)
    return true
end

#Can Store Vehicle (Client)

Called before a player stores a vehicle in a garage. This is a separate check from the server-sided CanStoreVehicle.

Example:

lua
---@param garageId string
---@param vehicle Vehicle
---@param vin Vin
---@return boolean, string?
function CanStoreVehicle(garageId, vehicle, vin)
    return true
end

#Can Steal Temp Keys

Called before a player starts searching for temporary keys in an NPC vehicle.

Example:

lua
---@param vehicle Vehicle
---@return boolean, string?
function CanStealTempKeys(vehicle)
    return true
end

#Can Rob NPC Keys

Called before a player robs keys from an NPC by aiming a weapon at them.

Example:

lua
---@param ped Ped
---@param vehicle Vehicle
---@return boolean, string?
function CanRobNpcKeys(ped, vehicle)
    return true
end

#Can Open Vehicle Management

Called before a player opens the vehicle management menu.

Example:

lua
---@param garageId string
---@return boolean, string?
function CanOpenVehicleManagement(garageId)
    return true
end

#Can Lockpick (Client)

Called before a player attempts to lockpick a vehicle.

NOTE that this check also exists server-sided as CanLockpick in server/unlocked/can_checks.lua. Both checks must pass for the action to succeed.

Example:

lua
---@param vehicle Vehicle
---@param vin Vin
---@return boolean, string?
function CanLockpick(vehicle, vin)
    return true
end

#Can Hotwire (Client)

Called before a player attempts to hotwire a vehicle.

NOTE that this check also exists server-sided as CanHotwire in server/unlocked/can_checks.lua. Both checks must pass for the action to succeed.

Example:

lua
---@param vehicle Vehicle
---@param vin Vin
---@return boolean, string?
function CanHotwire(vehicle, vin)
    return true
end

#Can Summon Vehicle

Called before a vehicle is summoned to the player via the key fob.

Example:

lua
---@param vin Vin
---@return boolean, string?
function CanSummonVehicle(vin)
    return true
end

#Can Open Locksmith

Called before the locksmith menu is opened.

Example:

lua
---@return boolean, string?
function CanOpenLocksmith()
    return true
end

#Common Patterns

#Deny an action for a specific garage

lua
function CanSpawnVehicle(source, vin, garageId)
    if (garageId == "police-impound") then
        local player = Z.getPlayer(source)
        if (not player or not player.job or player.job.name ~= "police") then
            return false, "noAccessToGarage"
        end
    end

    return true
end

#Deny an action based on vehicle data

lua
function CanStoreVehicle(source, vin, garageId)
    local vehData = GetPersistentVehicle(vin)
    if (vehData and vehData.metadata and vehData.metadata.noStore) then
        return false, "vehicleCannotBeStored"
    end

    return true
end

#Gate an action behind a specific item

lua
-- Client-side example
function CanOpenLocksmith()
    local hasItem = exports.ox_inventory:Search("count", "lockpick") > 0
    if (not hasItem) then
        return false, "youNeedALockpick"
    end

    return true
end

#Deny actions during an event or condition

lua
-- Server-side example
local serverEventActive = false

function CanSpawnVehicle(source, vin, garageId)
    if (serverEventActive) then
        return false, "serverEventActive"
    end

    return true
end