Skip to main content

Installation

1. Prepare the server​

  1. Install the dependencies.
  2. Back up your existing resource, config, and inventory definitions before upgrading.
  3. Disable competing vehicle-key/lock resources, such as qb-vehiclekeys or qbx_vehiclekeys. Check resources which call them before removing their startup entries.
  4. Place the release folder in your resources directory as wasabi_carlock.
danger

Keep the resource name wasabi_carlock. Do not rename it to wasabi_carlock_v3.

The release must include ui/build/index.html and its assets. The manifest loads that compiled UI, not the ui/src directory.

2. Set the start order​

Choose the tab for your framework. Insert your selected inventory, interaction resource, and optional dispatch before the final ensure wasabi_carlock line. These examples use Ox Inventory and the default interaction provider; substitute your installed providers.

ensure oxmysql
ensure ox_lib
ensure es_extended
ensure ox_inventory
ensure ox_target
ensure wasabi_carlock

If using textUI, remove the external target line and set interact = 'textUI' in the client config. In virtual-key mode you can omit the inventory line if your other enabled features do not need it.

3. Inventory items​

Open _invItems/data.lua in your downloaded resource and copy the block for your inventory into its existing item table. Do not install the entire file as an item table; it contains separate examples for different providers.

ProviderItem definition destination
Complete Inventorywasabi_inventory/data/items.lua
Ox Inventoryox_inventory/data/items.lua
QB / PS Inventoryqb-core/shared/items.lua
CodeM V2 / AIOcodem-inventoryv2/data/items.lua
TGIANNtgiann-inventory/items/items.lua, inside itemsData
Jaksamjaksam_inventory/_data/items.lua, inside Script.Items

Copy the supplied images from _invItems/images/ into your inventory's image directory:

  • carkeys.png
  • carkey_fob.png
  • flapper_device.png

Default profiles use carkeys for standard vehicles and carkey_fob for high-end vehicles. Both keys must be unique/non-stackable and retain plate metadata. flapper_device is an access tool, not a key. Also ensure the configured lockpick, locksmith materials (metalscrap by default), and item rewards (water by default) exist in your inventory.

Ox Inventory key example

Add this inside the existing items table; install the carkey_fob and flapper_device entries from the supplied file too.

['carkeys'] = {
    label = 'Car Keys',
    description = 'Keys to a vehicle.',
    weight = 100,
    stack = false,
    close = true,
    consume = 0,
    server = { export = 'wasabi_carlock.useKeyItem' },
},

Do not also register a framework usable handler for these keys. The server export handles the exact inventory slot and stops further item consumption/use processing.

CodeM V2 / AIO

Use the CodeM block, not the Ox server.export route. Keep key definitions at stack = false, consume = 0, and remoteUse = false. Do not add extra client/server use handlers, uses, degrade, or decay to keys. Apply these settings to custom profile key names too.

TGIANN: required editable callback

Insert this at the start of useItemEditable(src, itemData, itemSharedData) in tgiann-inventory/server/editable.lua, before its decay branch:

local ok, continueUse = pcall(function()
    return exports['wasabi_carlock']:useTgiannKeyItem(src, itemData)
end)
if ok and continueUse == false then return false end

This is not installed automatically. Use this route only, without a second framework usable or item-export handler for the same keys. Keep consume = 0, unique = true, and hasMetadata = true; remove decayTime, maxUseAmount, roleplay, and duplicate use handlers. Check effective /invadmin overrides as well as the file definitions.

If Carlock's export is unavailable, the snippet leaves the original inventory flow running. Nonconsumption then depends on the inventory definitions, and Carlock cannot perform a lock action.

QB / PS / Jaksam metadata display

Use the metadata display instructions in _invItems/data.lua: QB's formatKey can label vehicleLabel as Vehicle; PS includes a FormatItemInfo block for keys and fobs; Jaksam definitions include displayFields for plate and vehicleLabel.

Use the correct provider's unique/non-stackable flag rather than copying Ox's stack field into every inventory.

4. Configure Carlock​

Review all three config files:

  • config/shared/config.lua: key mode, security profiles, gameplay, locksmith costs, and dispatch.
  • config/client/config.lua: interaction provider, ignition, controls, and appearance.
  • config/server/config.lua: admin groups, NPC locking, and server validation.

See Configuration. Restart Carlock after edits so provider selection, item registrations, and cached settings are rebuilt.

5. Check ownership and integrations​

Carlock reads your framework's existing ownership tables through oxmysql; the release does not supply a Carlock SQL import or a legacy-key conversion script. Do not create a new ownership schema just for this resource.

For purchases, garages, rentals, and job vehicles, use Exports. A client grant returning true means queued, not granted. Prefer an authorized server integration when your script already controls spawning and purchases.

Upgrading an existing installation​

  • Reapply settings to the current split config files; do not replace them with an old monolithic config.
  • Replace _install_files references with the current _invItems setup.
  • Review physical key definitions and metadata before enabling metadata mode. Virtual-key ownership data is not an automatic inventory-key migration.
  • Update integrations relying on GiveKeyMenu (not exported in V3), a plate-string return from GiveKey, or GetAllKeys as a physical-key list.
  • Remove old direct state-changing event calls. Legacy hotwire/search claims are not accepted as proof of a completed action.

6. Verify in-game​

  • Confirm dependency, framework, inventory, and UI startup without errors.
  • Grant a key to a test vehicle and verify plate/name metadata and no consumption when using it.
  • Test U locking and K controls with a key; confirm no-key access is rejected.
  • Test both security profiles, locksmith costs, and dispatch on your installed providers.
  • Test vehicle purchase/garage flows and character reloads before deploying to players.

Use Common Issues if a feature is unavailable.