Documentation

Can-Check Hooks

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

Can-check hooks allow you to control player actions in zyke_anglegrinder before they execute. Return false with an optional locale key to deny an action and notify the player.

Every hook allows its action by default.

#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 Angle Grinder.

Types / Classes

All types / classes can be found in types/types.lua. plyId is the requesting player's server ID. Server hooks receive inventory items with their name, slot, and metadata. A grinder's metadata holds its hasDisc, discItem, durability, hasBattery, and batteryDurability.


#How Reason Strings Work

#Server-side reasons

The server passes the reason to Z.notify(), so use a locale key. Missing reasons fall back to "noPermission".

#Client-side reasons

Client checks also use locale keys. CanUseGrinderTool falls back to "noPermission", and IsPlayerHandsBusy to "handsBusy". They provide immediate feedback; enforce trusted restrictions in the corresponding server hook. Add custom reason keys to every file in locales/.

This server-side example only lets players with the mechanic job take the grinder out.

Example:

lua
---@param plyId PlayerId
---@param item Item
---@return boolean allowed
---@return string? reason
function CanEquipGrinder(plyId, item)
    if (not Z.isJob(plyId, "mechanic")) then return false, "noPermission" end

    return true
end

#Execution & Validation

Keep hooks synchronous and free of side effects. Returning true continues the normal flow; built-in checks for death, vehicles, busy hands, a running grind, and inventory space still apply.

Server hooks run before the fitting or holster animation plays. Putting the grinder away is not subject to CanEquipGrinder.

Whether a target can be cut, and by whom, is decided by the integration that offers it. These hooks only cover the grinder itself.


#Server-Sided Hooks

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

#Can Equip Grinder

Called before a player takes a grinder out, including when swapping to another grinder.

Example:

lua
---@param plyId PlayerId
---@param item Item @ Grinder item being equipped
---@return boolean allowed
---@return string? reason
function CanEquipGrinder(plyId, item)
    return true
end

#Can Load Grinder Disc

Called before a disc is fitted to the held grinder, from the disc item or the grinder menu.

Example:

lua
---@param plyId PlayerId
---@param grinderItem Item @ Equipped grinder receiving the disc
---@param discItem Item @ Disc item being consumed
---@return boolean allowed
---@return string? reason
function CanLoadGrinderDisc(plyId, grinderItem, discItem)
    return true
end

#Can Unload Grinder Disc

Called before the fitted disc is ejected from the grinder menu.

Example:

lua
---@param plyId PlayerId
---@param grinderItem Item @ Equipped grinder losing its disc
---@return boolean allowed
---@return string? reason
function CanUnloadGrinderDisc(plyId, grinderItem)
    return true
end

#Can Load Grinder Battery

Called before a battery is attached to the held grinder, from the battery item or the grinder menu.

Example:

lua
---@param plyId PlayerId
---@param grinderItem Item @ Equipped grinder receiving the battery
---@param batteryItem Item @ Battery item being consumed
---@return boolean allowed
---@return string? reason
function CanLoadGrinderBattery(plyId, grinderItem, batteryItem)
    return true
end

#Can Unload Grinder Battery

Called before the attached battery is detached from the grinder menu.

Example:

lua
---@param plyId PlayerId
---@param grinderItem Item @ Equipped grinder losing its battery
---@return boolean allowed
---@return string? reason
function CanUnloadGrinderBattery(plyId, grinderItem)
    return true
end

#Client-Sided Hooks

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

#Can Use Grinder Tool

Called when the use key is pressed on an aimed point, after the disc and battery checks pass. state is the fitted disc's state. Client only; the integration's server decides whether the cut may start.

Example:

lua
---@param state GrinderDiscState @ Disc state on the equipped grinder
---@return boolean allowed
---@return string? reason
function CanUseGrinderTool(state)
    return true
end

#Is Player Hands Busy

Return true while the player's hands are full, such as when handcuffed, carrying, or in an emote. A busy player cannot take the grinder out, put it away, or swap its disc or battery. Note that true denies here. Other resources can add their own checks through the RegisterBusyCheck export.

Example:

lua
---@return boolean busy
---@return string? reason @ Locale key, defaults to handsBusy
function IsPlayerHandsBusy()
    return false
end

#Common Patterns

#Block the Grinder While Handcuffed

Uses the game's own cuffed state. Replace it with the check your handcuff resource provides.

Example:

lua
---@return boolean busy
---@return string? reason
function IsPlayerHandsBusy()
    if (IsPedCuffed(PlayerPedId())) then return true, "handsBusy" end

    return false
end

#Restrict Battery Swaps to a Job

Uses the server hooks so the restriction cannot be bypassed from the client.

Example:

lua
---@param plyId PlayerId
---@param grinderItem Item
---@param batteryItem Item
---@return boolean allowed
---@return string? reason
function CanLoadGrinderBattery(plyId, grinderItem, batteryItem)
    if (not Z.isJob(plyId, "mechanic")) then return false, "noPermission" end

    return true
end