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
| Side | File |
|---|---|
| Server | server/unlocked/can_checks.lua |
| Client | client/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.plyIdis the requesting player's server ID. Server hooks receive inventory items with theirname,slot, andmetadata. A grinder's metadata holds itshasDisc,discItem,durability,hasBattery, andbatteryDurability.
#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
mechanicjob 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.
stateis 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
truewhile 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 thattruedenies here. Other resources can add their own checks through theRegisterBusyCheckexport.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