> ## Documentation Index
> Fetch the complete documentation index at: https://docs.9am.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FiveM Lockpick Script

> 9AM Lockpick is a standalone FiveM lockpick script with a Payday 3 inspired minigame, XP progression, and detailed configuration.

## 9AM Lockpick overview

9AM Lockpick is a standalone FiveM lockpick minigame for servers that want crime gameplay to feel tactile, skill-based, and worth mastering over time.

Both the escrow and open source editions expose the same `config.lua` and client exports. You can wire the minigame into doors, vehicles, or custom jobs without editing protected files.

## Public features

* Payday 3 inspired design
* Level and XP system
* Detailed config file
* 600+ lines of code
* Standalone support

## Compatibility and editions

| Type              | Details     |
| ----------------- | ----------- |
| Compatibility     | Standalone  |
| Escrow price      | `EUR 15.35` |
| Open source price | `EUR 35.58` |

Prices reflect the public store on March 22, 2026.

The minigame itself does not require a framework. Set `Config.Framework` so XP is stored against the correct player identifier.

## Config

Edit `config.lua` after install. Escrow customers get the same editable config file as open source.

```lua theme={null}
-- config.lua
Config = {}

Config.EearnXpRatio = 250 -- XP awarded per successful lockpick
Config.Level2Xp = 4000    -- XP required for level 2 (16 successes at default ratio)
Config.Level3Xp = 8000    -- XP required for level 3 (32 successes at default ratio)

Config.Framework = 'qb' -- 'qb', 'esx', or 'other'

Config.GetPlayerIdentifier = function(source)
    if Config.Framework == 'qb' then
        QBCore = exports['qb-core']:GetCoreObject()
        local Player = QBCore.Functions.GetPlayer(source)
        return Player.PlayerData.citizenid
    else
        return GetPlayerIdentifiers(source)[1]
    end
end
```

### Config options

| Option                | Type       | Default                         | Description                                                 |
| --------------------- | ---------- | ------------------------------- | ----------------------------------------------------------- |
| `EearnXpRatio`        | `number`   | `250`                           | XP added on each successful lockpick                        |
| `Level2Xp`            | `number`   | `4000`                          | XP threshold for level 2                                    |
| `Level3Xp`            | `number`   | `8000`                          | XP threshold for level 3                                    |
| `Framework`           | `string`   | `'qb'`                          | Identifier mode: `'qb'`, `'esx'`, or `'other'`              |
| `GetPlayerIdentifier` | `function` | QB citizenid / license fallback | Returns the player key used to store XP in `levelData.json` |

For ESX or custom stacks, set `Config.Framework` and adjust `GetPlayerIdentifier` so it returns a stable ID for each player.

Player XP is saved in `levelData.json` inside the resource. Higher levels feed into the minigame difficulty settings sent to the UI.

## Exports

Ensure `9am-lockpick` starts before any resource that calls these exports.

### Parameters

| Parameter     | Type       | Description                                                                                               |
| ------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `speed`       | `number`   | Pointer tick interval in ms. Lower is faster and harder (`1` is harder than `10`). `7` is a good default. |
| `isDecrease`  | `boolean`  | When `true`, the progress bar drains over time. If it hits zero, the attempt fails.                       |
| `randomSpeed` | `boolean`  | When `true`, speed can change after successful hits for more challenge.                                   |
| `callback`    | `function` | Used only by `createLockpickGameCb`. Receives `true` on success or `false` on fail.                       |

Both exports award XP automatically on success through the server.

### `createLockpickGame`

Awaitable export that returns a boolean.

```lua theme={null}
local success = exports['9am-lockpick']:createLockpickGame(7, false, true)

if success then
    -- Unlock the door, give loot, etc.
else
    -- Break the lockpick item, alert cops, etc.
end
```

### `createLockpickGameCb`

Same minigame, with the result delivered to a callback.

```lua theme={null}
exports['9am-lockpick']:createLockpickGameCb(7, false, true, function(success)
    if success then
        -- Unlock the door, give loot, etc.
    else
        -- Break the lockpick item, alert cops, etc.
    end
end)
```

## Usage examples

### Test commands

Use these while developing. Remove or protect them before production.

```lua theme={null}
RegisterCommand('lockpick', function()
    local result = exports['9am-lockpick']:createLockpickGame(7, false, true)
    if result == true then
        print('success')
    elseif result == false then
        print('fail')
    end
end)

RegisterCommand('lockpick2', function()
    exports['9am-lockpick']:createLockpickGameCb(7, false, true, function(result)
        if result == true then
            print('success')
        elseif result == false then
            print('fail')
        end
    end)
end)
```

### Vehicle lockpick

```lua theme={null}
RegisterCommand('pickvehicle', function()
    local ped = PlayerPedId()
    local vehicle = GetVehiclePedIsIn(ped, false)

    if vehicle == 0 then
        vehicle = GetClosestVehicle(GetEntityCoords(ped), 5.0, 0, 71)
    end

    if vehicle == 0 then
        return
    end

    local success = exports['9am-lockpick']:createLockpickGame(7, false, true)
    if success then
        SetVehicleDoorsLocked(vehicle, 1)
        SetVehicleDoorsLockedForAllPlayers(vehicle, false)
    end
end)
```

### Item-based trigger (QBCore example)

Call the export from your inventory item use handler. Keep item remove / reward logic in your own resource.

```lua theme={null}
-- Inside your items resource or qb-inventory use hook
exports['9am-lockpick']:createLockpickGameCb(8, false, true, function(success)
    if success then
        TriggerServerEvent('my-crime:server:lockpickSuccess')
    else
        TriggerServerEvent('my-crime:server:lockpickFailed')
    end
end)
```

### Difficulty presets

Tune `speed` and `randomSpeed` per interaction type.

```lua theme={null}
-- Easy house door
exports['9am-lockpick']:createLockpickGame(10, false, false)

-- Standard vehicle
exports['9am-lockpick']:createLockpickGame(7, false, true)

-- Hard safe or high-tier door
exports['9am-lockpick']:createLockpickGame(4, true, true)
```

## Best for

Choose this script if you want:

* A deeper lockpick minigame than one-click interactions
* Skill progression tied to repeated gameplay
* A standalone script that is easier to fit into mixed stacks

## Buy link

[Open Lockpick in the store](https://9am.dev/scripts/open-source/lockpick)