Installation — ns-carthief

Requirements

oxmysql (required)
OneSync
Qbox (recommended), QBCore or ESX
Optional: ox_lib, ox_target or qb-target, ox_inventory, qbx_vehiclekeys or qb-vehiclekeys, a dispatch resource (ps-dispatch, cd_dispatch, rcore_dispatch, core_dispatch)

Without a target resource a built-in [E] prompt is shown next to the closest vehicle.

1. Files

Put ns-carthief into your resources (for example resources/[nullsect]/ns-carthief). Keep the folder name.

2. server.cfg

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_target
ensure [qbx]          # qbx_vehiclekeys, qbx_smallresources ...
ensure ns-carthief    # AFTER [qbx]: the lockpick item take-over must register last

add_ace group.admin ns-carthief.admin allow

The order matters when Config.Items.takeOverUse = true: the last resource that registers the lockpick item wins. If ns-carthief starts before qbx_vehiclekeys, using a lockpick still opens qbx_vehiclekeys' own skill check.

3. Database

Tables are created and updated on start (Config.Database.autoMigrate = true). Set it to false if you would rather import sql/ns-carthief.sql yourself.

Table	Holds
`ns_carthief_profiles`	thief level, XP and counters per character
`ns_carthief_meta`	schema version

The owner alert reads the framework's own vehicle table (player_vehicles on Qbox / QBCore, owned_vehicles on ESX). It never writes to it.

4. Items

The script uses items that already exist on a Qbox / ox_inventory server:

Config	Default item	Used for
`Config.Items.lockpick`	`lockpick`	lockpick
`Config.Items.advancedLockpick`	`advancedlockpick`	lockpick: wider sweet spot, more durable; used first
`Config.Items.hotwireTool`	`screwdriverset`	hotwire (`false` = no item needed)

On another inventory, create items with these names or change the names in the config.

5. Vehicle keys

Keys and door locks stay with your keys resource. A successful hotwire gives the keys through it and a picked lock is opened through it (qbx_vehiclekeys SetLockState, otherwise the doorslockstate statebag).
With Config.Items.takeOverUse = true, using a lockpick item opens our minigame. Away from a vehicle the use is forwarded as lockpicks:UseLockpick, so house robbery keeps working.
qbx_vehiclekeys decides which parked and driven NPC vehicles are locked (spawnLockedIfParked, spawnLockedIfDriven in qbx_vehiclekeys/config/shared.lua). Only locked vehicles show Pick the lock.
qbx_vehiclekeys' key search (H) is untouched. To make thieves always hotwire, set findKeysChance = 0.0 there.
Other keys resources: see Config.VehicleKeys in CONFIGURATION.md.

6. Check

Start the server. The console shows ready (framework=qbox, inventory=ox, keys=qbx_vehiclekeys, dispatch=...).
As an admin, set Config.Debug = true, restart the resource and run /carthieftest pick easy and /carthieftest wire easy. The minigames open without a vehicle and change nothing.
With a lockpick in your inventory, aim at a door of a locked parked car: Pick the lock.
With a screwdriverset, sit in the driver seat of a car you have no keys for: [G] Hotwire.

Set Config.Debug = false again when you are done.

Troubleshooting

Problem	Cause / fix
"The system is starting, try again in a moment." does not go away	The database is not reachable. The console shows an oxmysql error or `Database unavailable`. Fix the database, then restart the resource.
Pick the lock does not show	The vehicle is not locked, you are not aiming at a door, it is a protected class / model, or you are in a vehicle.
Using a lockpick opens qbx_vehiclekeys' skill check	`ensure ns-carthief` is above `[qbx]`. Move it below.
"Not enough police on duty."	`Config.Police.minOnDuty` is above 0 and fewer police are on duty.
"This vehicle cannot be stolen."	The model is in `blacklistModels`, the class in `blacklistClasses`, or it is a player vehicle and `Config.Vehicles.allowPlayerOwned = false`.
No police alert	`Config.Dispatch.enabled`, `alarmChance` / `hotwireChance`, and that police have the job in `Config.Police.jobs` and are on duty.