Can-Check Hooks

Can-check hooks allow you to control player actions in zyke_shredder before they execute. All hooks return true by default. Return false with an optional locale key to deny an action and notify the player.

#File Locations

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

Types / Classes

All types / classes can be found in types/types.lua. plyId is the requesting player's server ID. Server hooks receive the machine's ShredderMachineConfig; client hooks receive its id.

#How Reason Strings Work

#Server-side reasons

The server returns the reason to the client, which passes it to Z.notify(), so use a locale key. Missing reasons fall back to "noPermission". Refusals also fire zyke_shredder:OnActionRefused and are written to the activity log when logs.refusals is enabled, except for CanEquipShredderCan.

#Client-side reasons

Client checks also use locale keys and fall back to "noPermission". They provide immediate feedback; enforce trusted restrictions in the corresponding server hook. Add custom reason keys to every resource locale.

This server-side example allows only one machine to be started or stopped by players.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@param running boolean
---@return boolean allowed
---@return string? reason
function CanOperateShredder(plyId, machine, running)
    if (machine.id ~= "sandy_scrapyard") 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 distance, recipe, inventory, fuel, and capacity checks still apply.

Machines stopping by themselves, admin panel actions, and parts already on the line are not subject to player action hooks.

#Server-Sided Hooks

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

#Can Feed Shredder

Called before a part is loaded onto the infeed. item is the inventory item being loaded.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@param item Item @ Part being loaded onto the infeed
---@return boolean allowed
---@return string? reason
function CanFeedShredder(plyId, machine, item)
    return true
end

#Can Unload Shredder

Called before a part is taken back off the infeed. item is the part's item name.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@param item string @ Name of the part being taken back off the infeed
---@return boolean allowed
---@return string? reason
function CanUnloadShredder(plyId, machine, item)
    return true
end

#Can Operate Shredder

Called before a player starts or stops a machine. running is true when starting.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@param running boolean @ Whether the player is starting or stopping it
---@return boolean allowed
---@return string? reason
function CanOperateShredder(plyId, machine, running)
    return true
end

#Can Collect Shredder Bin

Called before a player takes scrap from the bin.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@return boolean allowed
---@return string? reason
function CanCollectShredderBin(plyId, machine)
    return true
end

#Can Equip Shredder Can

Called when a player uses a fuel can to take it out. Server only.

Example:

lua
---@param plyId PlayerId
---@param item Item @ Fuel can being taken out
---@return boolean allowed
---@return string? reason
function CanEquipShredderCan(plyId, item)
    return true
end

#Can Refuel Shredder

Called before the can in hand is poured into a generator.

Example:

lua
---@param plyId PlayerId
---@param machine ShredderMachineConfig
---@param item Item @ Can in hand being poured into the generator
---@return boolean allowed
---@return string? reason
function CanRefuelShredder(plyId, machine, item)
    return true
end

#Can Sell Scrap

Called before a player sells scrap to a buyer. buyer is the entry from buyer.positions.

Example:

lua
---@param plyId PlayerId
---@param buyer ShredderBuyerPosition
---@return boolean allowed
---@return string? reason
function CanSellScrap(plyId, buyer)
    return true
end

#Client-Sided Hooks

All client-sided hooks are in client/unlocked/can_checks.lua. The server re-validates every action.

#Can Feed Shredder

Called before the loading flow starts. slot is the inventory slot of the part.

Example:

lua
---@param machineId string
---@param slot integer @ Inventory slot of the part being loaded
---@return boolean allowed
---@return string? reason
function CanFeedShredder(machineId, slot)
    return true
end

#Can Unload Shredder

Called before a part is taken back off the infeed. loadId identifies the part on the belt.

Example:

lua
---@param machineId string
---@param loadId string @ Part riding the infeed being taken back off
---@return boolean allowed
---@return string? reason
function CanUnloadShredder(machineId, loadId)
    return true
end

#Can Operate Shredder

Called before the start or stop request is sent.

Example:

lua
---@param machineId string
---@param running boolean @ Whether the player is starting or stopping it
---@return boolean allowed
---@return string? reason
function CanOperateShredder(machineId, running)
    return true
end

#Can Collect Shredder Bin

Called before the bin menu collects scrap.

Example:

lua
---@param machineId string
---@return boolean allowed
---@return string? reason
function CanCollectShredderBin(machineId)
    return true
end

#Can Refuel Shredder

Called before pouring starts at the generator's filler.

Example:

lua
---@param machineId string
---@return boolean allowed
---@return string? reason
function CanRefuelShredder(machineId)
    return true
end

#Can Sell Scrap

Called before the sell request is sent. buyerIndex is the index in buyer.positions.

Example:

lua
---@param buyerIndex integer
---@return boolean allowed
---@return string? reason
function CanSellScrap(buyerIndex)
    return true
end

#Common Patterns

#Restrict the Scrap Buyer to a Job

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

Example:

lua
---@param plyId PlayerId
---@param buyer ShredderBuyerPosition
---@return boolean allowed
---@return string? reason
function CanSellScrap(plyId, buyer)
    if (not Z.isJob(plyId, "scrapyard")) then return false, "noPermission" end

    return true
end