Documentation

Integrating Other Resources

Start the minigame from your own resources and check the result on the server.

Vehicle Keys and Wheel Clamp use the minigame automatically while zyke_lockpick is started. This page covers your own scripts. The exports are listed in Exports & Events.

There are two ways in. Offer locks to the pick by registering an action on the client, so using a pick from the inventory runs it on the nearest lock it offers. Or handle a usable item yourself and start the attempt.

Both end the same way: the server checks ConsumeLockpickResult(plyId) and only acts on "won". Do not wear or remove the pick yourself; zyke_lockpick already did.

The client's return value and the zyke_lockpick:PinSet event are not proof of a win. Always confirm with ConsumeLockpickResult on the server before unlocking anything. The result can be read once, within 30 seconds of the attempt ending.

#Offering Locks to the Pick

The pick must be listed in Config.Items.usable. Register the action again whenever zyke_lockpick restarts, since a stopped resource's actions are removed.

Client:

lua
local function registerLockpickAction()
    exports["zyke_lockpick"]:RegisterLockpickAction("pickDoor", {
        -- Every lock within range metres of the player, asked each time a pick is used
        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,
        -- Runs on the nearest point in its reach, with the slot of the pick that was used
        onUse = function(data, slot)
            if (not Z.callback.await("my_resource:StartPick", data.netId, slot)) then return end

            local opened = exports["zyke_lockpick"]:StartLockpick(6, {anchor = {coords = doorHandle, normal = doorNormal}, blend = 500})
            if (opened) then TriggerServerEvent("my_resource:DoorPicked") end
        end,
    })
end

AddEventHandler("onClientResourceStart", function(resource)
    if (resource == "zyke_lockpick") then registerLockpickAction() end
end)

CreateThread(function()
    if (GetResourceState("zyke_lockpick") == "started") then registerLockpickAction() end
end)

Server:

lua
Z.callback.register("my_resource:StartPick", function(plyId, netId, slot)
    if (not canPickDoor(plyId, netId)) then return false end

    return exports["zyke_lockpick"]:PrepareLockpick(plyId, slot)
end)

RegisterNetEvent("my_resource:DoorPicked", function()
    if (exports["zyke_lockpick"]:ConsumeLockpickResult(source) ~= "won") then return end

    -- Unlock the door
end)

Points take entity with an optional entity-local offset, or world coords, plus an optional reach (2.0 metres by default) and data for onUse.

#Your Own Usable Item

A usable pick item is handled in three steps:

  1. Server: from your usable-item handler, call PrepareLockpick(plyId, slot) with the used slot. It notifies the player and returns false when the slot is not a configured pick or the wrench is missing.
  2. Client: call StartLockpick(pins, options). It reserves the pick, runs the minigame, writes the wear, and returns once the close-up has closed.
  3. Server: before unlocking anything, call ConsumeLockpickResult(plyId) and only act on "won".

Example:

lua
-- Server
Z.registerUsableItem("lockpick", function(plyId, item)
    if (not exports["zyke_lockpick"]:PrepareLockpick(plyId, item.slot)) then return end

    TriggerClientEvent("my_resource:PickDoor", plyId)
end)

RegisterNetEvent("my_resource:DoorPicked", function()
    if (exports["zyke_lockpick"]:ConsumeLockpickResult(source) ~= "won") then return end

    -- Unlock the door
end)

-- Client
RegisterNetEvent("my_resource:PickDoor", function()
    local opened = exports["zyke_lockpick"]:StartLockpick(6, {anchor = {coords = doorHandle, normal = doorNormal}, blend = 500})
    if (opened) then TriggerServerEvent("my_resource:DoorPicked") end
end)

If you make a pick usable yourself, remove it from Config.Items.usable so it is not registered twice. Without PrepareLockpick, the attempt uses the first configured pick the player has.

#Placing the Lock

StartLockpick options are 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. 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.

#Result Validation

The server only accepts a win that took at least as long as the fastest possible solve for that pin count, and that left the pick with durability. Anything else is treated as cancelled, and a rejected win is printed to the server console. Attempts that take longer than five minutes on the server are also treated as cancelled.

#Reacting to Attempts

Use the server events zyke_lockpick:OnLockpickStarted and zyke_lockpick:OnLockpickFinished, or the hooks in server/unlocked/hooks.lua, for logs or dispatch alerts. Use the client event zyke_lockpick:PinSet to track progress during your own attempt, such as an alarm at the first pin. See Exports & Events.