Documentation

Exports & Events

All exports, hooks and events available to integrate Lockpick into other resources.

General Information

pins is the lock's pin count, from 3 to 9. A result is "won", "snapped", or "cancelled". Durability is 0 to 100. plyId is the player's server ID, and slot is 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

ContextExports
ClientStartLockpick, CancelLockpick, RegisterLockpickAction, RemoveLockpickAction
ServerPrepareLockpick, 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 true when the lock was opened, false when the pick snapped, and nil when the attempt was cancelled or could not start. pins defaults to 6.

It returns nil straight away while another attempt is open or being reserved. It also returns nil, 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.

options is optional:

  • anchor = {coords = vector3, normal = vector3, entity? = entity} places the lock at a target such as a door handle. normal points out of the surface toward the player. With entity, 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 = ms eases 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 ConsumeLockpickResult before 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 false when 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, and onUse runs for the nearest point within its reach.

  • getPoints(range) returns every lock within range metres of the player. It is called each time a pick is used.
  • A point takes entity with an optional entity-local offset, or world coords, plus an optional reach (2.0 metres by default) and data for onUse.
  • onUse(data, slot) runs with the point's data and 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_lockpick restarts.

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, or false and "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 nil when 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. durability is the pick's durability at the start.

Example:

lua
AddEventHandler("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. result is the server-validated won, snapped, or cancelled. snapped is true when the pick is now at 0 durability, also after a won attempt that used up its last wear. durationMs is 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:

lua
AddEventHandler("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. owner is the resource that started the attempt, set is the number of pins set so far, and pins is 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; ConsumeLockpickResult on the server is the result.

Example:

lua
AddEventHandler("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.result is "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 to metadata.image, which ox_inventory and qb inventories read. Change the keys here for an inventory that reads icons or labels from elsewhere. durability and lockpickId are always set by the resource itself. stage is 0 intact, 1 worn, 2 damaged, 3 critical, or 4 snapped.

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