Exports & Events
All exports, hooks and events available to integrate Lockpick into other resources.
General Information
pinsis the lock's pin count, from3to9. A result is"won","snapped", or"cancelled". Durability is0to100.plyIdis the player's server ID, andslotis an inventory slot.For complete integration examples, see Integrating Other Resources.
Suggestions?
If you wish to have any exports or events added, please head over to our Discord and create a suggestion post. We are happy to allow for easier integration within other resources.
#Complete Export Index
| Context | Exports |
|---|---|
| Client | StartLockpick, CancelLockpick, RegisterLockpickAction, RemoveLockpickAction |
| Server | PrepareLockpick, ConsumeLockpickResult |
#Client Sided Exports
#Start Lockpick
Reserves a pick on the server, runs the minigame, writes the wear, and returns once the close-up has closed. Returns
truewhen the lock was opened,falsewhen the pick snapped, andnilwhen the attempt was cancelled or could not start.pinsdefaults to6.It returns
nilstraight away while another attempt is open or being reserved. It also returnsnil, and notifies the player, when the player is dead, in a vehicle, or moving, when another camera or NUI menu is in use, or when the server finds no usable pick or tension wrench.
optionsis optional:
anchor = {coords = vector3, normal = vector3, entity? = entity}places the lock at a target such as a door handle.normalpoints out of the surface toward the player. Withentity, the lock and camera follow that entity if it is nudged, and the attempt closes if the entity is deleted. Without an anchor, or when the target has no clear camera view, the lock floats in front of the player.blend = mseases the camera in from the gameplay camera and back out.The client result is for your own flow only. Confirm it on the server with
ConsumeLockpickResultbefore unlocking anything.Example:
lua---@param pins? integer @ 3 to 9, defaults to 6 ---@param options? {anchor?: {coords: vector3, normal: vector3, entity?: integer}, blend?: integer} ---@return boolean? succeeded @ true opened, false snapped, nil cancelled or unavailable local opened = exports["zyke_lockpick"]:StartLockpick(6, {anchor = {coords = doorHandle, normal = doorNormal}, blend = 500})
#Cancel Lockpick
Closes an attempt started by the calling resource, for example when your own checks see the player pulled away. It also works while the pick is still being reserved. The pick still takes the minimum wear. Returns
falsewhen the calling resource has no attempt open.Example:
lua---@return boolean cancelled local cancelled = exports["zyke_lockpick"]:CancelLockpick()
#Register Lockpick Action
Offers locks to picks used from the inventory. When a player uses a pick listed in
Config.Items.usable, every registered action is asked for its points, andonUseruns for the nearest point within its reach.
getPoints(range)returns every lock withinrangemetres of the player. It is called each time a pick is used.- A point takes
entitywith an optional entity-localoffset, or worldcoords, plus an optionalreach(2.0metres by default) anddataforonUse.onUse(data, slot)runs with the point'sdataand the slot of the pick that was used.Registering again under the same name replaces the earlier action. Actions are removed when the resource that registered them stops, so register again when
zyke_lockpickrestarts.Example:
lua---@param name string ---@param action {getPoints: fun(range: number): table[], onUse: fun(data: any, slot: integer)} exports["zyke_lockpick"]:RegisterLockpickAction("pickDoor", { getPoints = function(range) local door = findDoorInRange(range) if (not door) then return {} end return {{entity = door, offset = vector3(0.4, 0.0, 1.0), reach = 2.0, data = {netId = NetworkGetNetworkIdFromEntity(door)}}} end, onUse = function(data, slot) -- Prepare the slot on the server, then call StartLockpick end, })
#Remove Lockpick Action
Removes an action registered with
RegisterLockpickAction.Example:
lua---@param name string exports["zyke_lockpick"]:RemoveLockpickAction("pickDoor")
#Server Sided Exports
#Prepare Lockpick
Makes the player's next attempt within 30 seconds use the pick in that slot. Call it from your usable-item handler with the used slot. It notifies the player when it refuses, so callers can stop without their own message. It also clears any result left from an earlier attempt.
Returns
true, orfalseand"lockpickMissing"when the slot is not a configured pick with durability left, or"tensionWrenchMissing"when the player has no tension wrench.Without
PrepareLockpick, an attempt uses the first configured pick the player has.Example:
lua---@param plyId integer ---@param slot integer ---@return boolean prepared ---@return string? reason @ "lockpickMissing" or "tensionWrenchMissing" local prepared, reason = exports["zyke_lockpick"]:PrepareLockpick(plyId, item.slot)
#Consume Lockpick Result
Returns the server-validated result and pin count of the player's last attempt. Each result can be read once, within 30 seconds of the attempt ending. Returns
nilwhen there is none. Only act on"won".Example:
lua---@param plyId integer ---@return "won" | "snapped" | "cancelled" | nil result ---@return integer? pins local result, pins = exports["zyke_lockpick"]:ConsumeLockpickResult(source) if (result ~= "won") then return end
#Server Local Events
These events are local server notifications. They are not network event entry points. Listen with AddEventHandler on the server. Each receives one data table, the same one passed to the matching hook in server/unlocked/hooks.lua.
#On Lockpick Started
Fires once the server has reserved a pick for an attempt.
durabilityis the pick's durability at the start.Example:
luaAddEventHandler("zyke_lockpick:OnLockpickStarted", function(data) print(data.source, data.itemName, data.pins, data.durability) end)
#On Lockpick Finished
Fires when an attempt ends, after the pick wear was written.
resultis the server-validatedwon,snapped, orcancelled.snappedistruewhen the pick is now at 0 durability, also after a won attempt that used up its last wear.durationMsis how long the attempt took.A player who disconnects mid-attempt keeps the wear saved at the last stage, and this event does not fire.
Example:
luaAddEventHandler("zyke_lockpick:OnLockpickFinished", function(data) print(data.source, data.itemName, data.pins, data.result, data.snapped, data.durationMs) end)
#Client Local Events
#Pin Set
Fires on the client each time a pin is set during an attempt started through
StartLockpick.owneris the resource that started the attempt,setis the number of pins set so far, andpinsis the lock's pin count. Practice locks do not fire it.A pin can drop again when tension is released, so the same count may come twice. It only reports progress, such as for an alarm that goes off at the first pin. Never open anything on it;
ConsumeLockpickResulton the server is the result.Example:
luaAddEventHandler("zyke_lockpick:PinSet", function(data) if (data.owner ~= GetCurrentResourceName()) then return end print(data.set, data.pins) end)
#Server Hooks
The hooks are in server/unlocked/hooks.lua. The file is unencrypted and safe to edit directly. Both hooks are notifications only, run before the matching event, and receive the same data table. Other resources can listen to the events instead of editing this file.
#On Lockpick Started
Runs once the server reserved a pick for an attempt.
Example:
lua---@param data {source: integer, itemName: string, pins: integer, durability: number} function OnLockpickStarted(data) end
#On Lockpick Finished
Runs when an attempt ends, after the pick wear was written.
data.resultis"won","snapped", or"cancelled".Example:
lua---@param data {source: integer, itemName: string, pins: integer, result: string, snapped: boolean, durationMs: integer} function OnLockpickFinished(data) end
#Editable Server Functions
#Get Lockpick Wear Metadata
In
server/unlocked/functions.lua. Returns extra metadata written to a pick when it is first given out and each time its wear changes. The default writes the wear icon tometadata.image, which ox_inventory and qb inventories read. Change the keys here for an inventory that reads icons or labels from elsewhere.durabilityandlockpickIdare always set by the resource itself.stageis0intact,1worn,2damaged,3critical, or4snapped.Example:
lua---@param itemName string ---@param durability number @ 0-100 ---@param stage integer @ 0 intact, 1 worn, 2 damaged, 3 critical, 4 snapped ---@return table<string, any> metadata function GetLockpickWearMetadata(itemName, durability, stage) return {image = GetLockpickImage(itemName, durability)} end