Updated 2026-10-11 · 4 min read
qb-vehiclekeys: keys, locks and exports
qb-vehiclekeys tracks access to vehicle plates, lock/unlock actions, key sharing, carjacking and hotwiring. For integrations, use its server exports, not internal network events. This reference is pinned to commit 36b54c2.
Installation and dependencies
- Start
qb-corefirst. The resource's server code also usesqb-inventoryfor lockpick removal. - Start
qb-vehiclekeyswith itsNUIassets, locales, client/server scripts andconfig.lua. - Ensure vehicle shop, garage and custom spawn scripts follow the same plate format and assign keys through the server.
- Test spawned, owned, job and borrowed vehicles, plus reconnect and resource restart.
Official server exports
These functions are exported in server.lua.
| Export | Signature | Behavior |
|---|---|---|
GiveKeys | GiveKeys(playerSource, plate) | Grants key access; if plate omitted, tries the player's current vehicle |
RemoveKeys | RemoveKeys(playerSource, plate) | Revokes key access for the plate |
HasKeys | HasKeys(playerSource, plate) | Returns boolean for a player's plate access |
-- In a trusted server-side vehicle-delivery handler:
local playerSource = source
local plate = 'DEMO123' -- Use your server-created vehicle's real plate
if not exports['qb-vehiclekeys']:HasKeys(playerSource, plate) then
exports['qb-vehiclekeys']:GiveKeys(playerSource, plate)
end
-- When server-owned rules require revoking the same access:
-- exports['qb-vehiclekeys']:RemoveKeys(playerSource, plate)Do not let an arbitrary client select the player ID or plate to grant. The handler responsible for a purchase, spawn or job vehicle must establish the vehicle and player's entitlement server-side. The example is an integration fragment, not an event handler accepting user input.
Client helpers
client.lua also exports HasKeys for the local client and addNoLockVehicles / removeNoLockVehicles for local no-lock vehicle lists. Use the server version for authorization-sensitive decisions.
Real configuration options
| Option | Purpose |
|---|---|
Config.PersistentKeys | Enables restoring saved keys from player metadata on reconnect |
Config.SharedKeys | Job-related key sharing rules |
Config.UseKeyfob | Keyfob lock UI behavior |
Config.LockToggleDist | Lock interaction distance |
Config.LockNPCDrivingCars / Config.LockNPCParkedCars | NPC vehicle locking |
Config.CarJackEnable | Enables/disables carjacking behavior |
Config.CarjackChance / Config.HotwireChance | Chance-based gameplay |
Config.AlertCooldown | Police alert cooldown |
Config.ImmuneVehicles / Config.NoLockVehicles | Vehicle exceptions |
With PersistentKeys enabled, GiveKeys updates PlayerData.metadata.vehicleKeys, and HasKeys consults that metadata when needed. Changing the setting does not by itself migrate key data to a custom garage schema.
Events and commands
The reviewed source registers these internal server events: qb-vehiclekeys:server:GiveVehicleKeys, AcquireVehicleKeys, RemoveVehicleKeys, breakLockpick and setVehLockState (all with the qb-vehiclekeys:server: prefix). The acquisition event expects a vehicle network ID and checks proximity, but a proximity check alone does not establish ownership. Custom scripts should use the trusted server exports instead.
Available commands in this revision:
/givekeys— initiates key sharing through the client flow./addkeys— admin command to grant keys by player/plate./removekeys— admin command to remove keys by player/plate.- Client commands
/togglelocksand/enginecontrol local lock/engine actions.
Never grant keys through a client-controlled net event simply because a vehicle is nearby.
Why do my car keys disappear?
| Symptom | First check |
|---|---|
| Keys missing after reconnect | Config.PersistentKeys and saved vehicleKeys metadata |
| Keys work for another vehicle | Plate normalization: trim whitespace consistently in garage, shop and key resources |
| Car spawns without keys | Did the trusted server spawn/delivery flow call GiveKeys with the actual plate? |
| Job vehicle access is wrong | Config.SharedKeys and the player's active job/grade |
| No keys after upgrading | Compare old and new persistent-key model; test metadata and live-session cache separately |
No such export GiveKeys | Ensure caller is on the server, resource started and correct revision deployed |
Update checklist
- Pin current
qb-vehiclekeys,qb-core,qb-inventoryand garage/vehicle-shop revisions. - Test server
GiveKeys,RemoveKeysandHasKeys(including invalid player IDs). - Verify access after logout and after resource restart with persistent keys on and off.
- Audit all scripts using
AcquireVehicleKeysorsetVehLockStateand move privileged operations to server-authorized exports.
Sources
Repository · Server exports and events · Client helpers · Configuration
For garage/vehicle persistence see vehicle-state troubleshooting.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
