Documentation

Picks & Wear

Pick items, the tension wrench, the lockpick kit, and how picks wear.

#Items

ItemPurpose
lockpick or hook_pickThe hook pick. Each pick keeps its own durability and wears with every attempt. Copy only one of the two names.
tension_wrenchRequired for every attempt. It has no durability and is never consumed.
lockpick_kitOptional. Using it gives 5 picks and 1 tension wrench by default, and uses up the kit.

The definitions are in extras/items/. See Setup for choosing between lockpick and hook_pick.

#Which Pick Is Used

Config.Items.lockpicks lists every pick an attempt may wear, in order of preference. By default it lists lockpick, then Vehicle Keys' veh_lockpick and veh_advancedlockpick.

When the calling resource prepared the slot the pick was used from, that exact pick is used. Otherwise the attempt uses the first configured pick the player has with durability left. A pick at 0 durability is never used.

Each entry can set a wear multiplier. veh_advancedlockpick wears at half the rate by default.

#Using a Pick From the Inventory

Picks listed in Config.Items.usable (lockpick by default) are usable items. Using one needs a tension_wrench, and picks the nearest lock another resource offers, such as a zyke_boosting contract car. With nothing in reach, the player is told there is nothing to pick. Using a pick in a vehicle, or while an attempt is open, does nothing.

Leave out picks another resource already makes usable, such as Vehicle Keys' picks.

#How Picks Wear

An attempt starts at the pick's current durability, so a worn pick also looks worn in the minigame. Tension above the brass band wears the pick, faster the higher it goes and faster again while lifting. Forcing a wrong, jammed, or already set pin while tension is in or above the band wears it too.

Every attempt removes at least Config.Items.minDurabilityLoss, even when it is cancelled. The wear is saved to the item each time the pick reaches a new wear stage, and again when the attempt ends. A player who disconnects mid-attempt keeps the wear saved at the last stage.

At 0 durability the pick snaps and the attempt ends. A snapped pick stays in the inventory at 0 durability unless Config.Items.removeBroken = true.

#Wear Stages & Icons

Picks with images in their Config.Items.lockpicks entry get the matching icon in metadata.image as they wear. hook_pick uses the same icons.

DurabilityPickmetadata.image
Above 75Intactlockpick
75 and belowWornlockpick_wear_1
50 and belowDamagedlockpick_wear_2
25 and belowCriticallockpick_wear_3
0Snappedlockpick_wear_4

The pick model in the minigame follows the same stages: gouges deepen and the blade bends as it wears, and a missing tip means it has snapped.

For an inventory that reads icons or labels from another metadata key, edit GetLockpickWearMetadata in server/unlocked/functions.lua. See Exports & Events.

#Pick Metadata

Every pick gets its own lockpickId and a durability of 100 in its metadata when it is given out. The lockpickId lets the wear follow the reserved pick if it moves to another slot during an attempt. This is why picks must not stack.

#Lockpick Kit

Using a lockpick_kit removes it and gives Config.Items.kit.lockpicks picks of Config.Items.kit.lockpick and Config.Items.kit.tensionWrenches tension wrenches. Each pick is given separately with its own durability. When the player cannot carry the contents, nothing is unpacked and they are told there is no room.

Config.Items.kit.lockpick must be one of the Config.Items.lockpicks entries, or the kit is disabled with a console warning. Set Config.Items.kit = false to disable the kit. The logic is in server/unlocked/kit.lua.