# Add Custom Vehicles to QBCore

A vehicle that spawns through an admin menu is not automatically registered for sale, owned by a character or stored in a garage. Work through four separate layers: **streamed asset → shared vehicle definition → shop/job integration → saved ownership and keys**.

This guide uses core `9b3cddcc`, vehicle shop `e8652970` and police job `3ad3d190` as source baselines. Example prices, coordinates and model names are illustrative. No third-party vehicle asset or in-game test result is supplied. Use a vehicle you are authorized to run and follow its publisher's edition/build requirements.

## Before you change anything

Back up the vehicle resource, affected QBCore configuration and database. Test on staging. Record the exact spawn model from the asset's `vehicles.meta`; the folder name, display label and spawn model need not be identical.

The model `docs_sedan` below is a **placeholder**, not a downloadable vehicle. Replace it consistently with the actual add-on model. Do not replace a working vendor manifest with a generic template when the asset requires additional audio, layout, tuning or escrow files.

If you still need an asset, the [FiveM car packs on RPScripts](https://rpscripts.net/product-category/assets/fivem-cars/) list their included models. RPScripts and qbcore.net are operated by the same owner. Apply the same streaming and spawn-model checks to any purchased pack.

## 1. Prove the vehicle streams correctly

For a simple asset with the files below, the resource shape is:

```text
resources/[vehicles]/docs_sedan/
  fxmanifest.lua
  data/
    vehicles.meta
    handling.meta
    carvariations.meta
    carcols.meta
  stream/
    docs_sedan.yft
    docs_sedan_hi.yft
    docs_sedan.ytd
```

A corresponding minimal manifest is:

```lua
fx_version 'cerulean'
game 'gta5'

files {
    'data/vehicles.meta',
    'data/handling.meta',
    'data/carvariations.meta',
    'data/carcols.meta'
}

data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
data_file 'HANDLING_FILE' 'data/handling.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'
data_file 'CARCOLS_FILE' 'data/carcols.meta'
```

Declare only files the asset actually ships. Additional metadata must use the appropriate data-file type. Retain the publisher's complete manifest for anything more complex. Check file capitalization, duplicate spawn models and conflicting handling entries.

Add the actual resource to the active server configuration. For a newly discovered resource, `refresh` rescans manifests and `ensure docs_sedan` starts it. **`refresh` does not rerun an already running core's shared Lua files.** Changes to core configuration need a coordinated staging restart or a deliberately implemented supported update mechanism.

Use your existing authorized admin spawning tool on staging. Confirm the exact model loads, the vehicle is visible and drivable, and another player sees it. If spawning fails, fix streaming/build/metadata issues before editing shops or inserting database records.

## 2. Add the correct shared vehicle entry

Open the deployed `qb-core/shared/vehicles.lua` and inspect its structure. In the pinned core, it contains `local Vehicles = { ... }`, an **array of entries**, followed by a numeric loop that constructs the model/hash lookup tables. Add a new array element inside that list:

```lua
{
    model = 'docs_sedan',
    name = 'Training Sedan',
    brand = 'Training',
    price = 25000,
    category = 'sedans',
    type = 'automobile',
    shop = 'pdm'
},
```

Do not add a keyed `['docs_sedan'] = { ... }` entry inside that array: the numeric loop does not visit string keys. Do not remove the loop or replace the whole shared table. Older forks may instead define the model-keyed table directly; match the structure and required fields of **your** source rather than mixing formats.

Use the [Vehicle Customizer](/tools/vehicle-customizer) to prepare the current array entry. Check the spawn model, vehicle type and shop before copying it. The tool generates configuration; it does not install the asset, create a dealer, grant keys or write ownership records.

| Field | Check |
| --- | --- |
| `model` | Exact spawn model, not the resource folder or display name |
| `name`, `brand` | Human-readable labels; do not use them as spawn identifiers |
| `price` | Server's intended sale price; illustrative values here are not economy advice |
| `category` | Category supported by the installed shop's filtering/menu |
| `type` | Correct entity type for that asset; `automobile` is not suitable for every boat, aircraft or bike |
| `shop` | An existing shop key or a supported list of shop keys; `none` for vehicles not sold by this configuration |

After the coordinated staging restart, check startup errors before opening a dealer. A misspelled `model` or an entry outside the array may fail independently of the vehicle's streamed files.

## 3. Connect a dealership or job garage

### Dealership path

In the pinned `qb-vehicleshop/config.lua`, shops live in `Config.Shops`. The sample `pdm` shop is free-use; `luxury` is managed and has a configured dealer job. Set the vehicle's `shop` to a real key, then verify the shop's access requirements and category selection.

`ShowroomVehicles` controls display slots. To display the add-on in an existing slot, edit that slot's `defaultVehicle` and `chosenVehicle` to the actual registered model while preserving its coordinates. A showroom slot is not an ownership record and does not replace shared vehicle registration.

Test model selection, display, a test drive and a real authorized purchase on a disposable staging character. Inspect server errors and the shop transaction before blaming the garage. See the [vehicle-shop reference](/docs/resources/qb-vehicleshop).

### Police or other job garage path

A police fleet vehicle need not be sold through a public dealership. In the referenced police job, add an entry inside the appropriate existing `Config.AuthorizedVehicles` grade table:

```lua
-- Inside Config.AuthorizedVehicles[0], not a replacement for the whole config:
docs_sedan = 'Training Patrol',
```

The pinned client builds the menu by checking grade tables from zero through the player's grade. Check that the job, duty state, grade, spawn point and actual asset are correct. A custom garage resource may use a different schema; do not paste this into an unrelated vendor's config.

A job fleet spawn and a privately purchased vehicle have different ownership lifecycles. Decide whether the vehicle should be temporary, assigned or persistent using the installed garage/job implementation. Do not turn every fleet spawn into a guessed `INSERT` in `player_vehicles`.

## 4. Verify ownership, storage and keys

Test the complete private-vehicle flow, not only an admin spawn:

| Step | What to verify |
| --- | --- |
| Purchase | Exactly one intended payment; the correct model and plate belong to the test character |
| Spawn | Correct model, plate, fuel and applicable properties |
| Keys | Authorized owner can unlock/start it; a different player does not gain access automatically |
| Store | The configured garage accepts the vehicle and the ownership/state record is updated |
| Retrieve | The intended stored vehicle returns without duplicate ownership or duplicate active instances |
| Reconnect/restart | Saved model, plate, garage and modifications survive according to the resource's persistence rules |

Use your [garage](/docs/resources/qb-garages) and [vehicle-key](/docs/resources/qb-vehiclekeys) integrations rather than a generic public “give keys” server event. Client visibility or knowledge of a plate is not ownership authorization. When replacing a keys/fuel/garage resource, inspect the actual calls made by the dealer and job scripts.

For a schema error, the referenced vehicle-shop schema is `vehshop.sql`. A read-only ownership inspection must use a trusted server-side citizen ID and a bound plate, and should not expose the full database to clients. Follow [vehicle-state diagnostics](/docs/troubleshooting/vehicle-state) and [database ownership](/docs/database) before changing saved data.

## Troubleshooting by layer

| Symptom | Investigate first |
| --- | --- |
| Model will not spawn anywhere | Asset files, actual spawn name, manifest and compatible game build/edition |
| Admin spawn works, dealer does not list it | Shared array entry, `shop`, category and coordinated restart |
| Dealer display works, purchase fails | Server transaction, owning schema and integration error |
| Vehicle is listed but model data is nil | Entry placement and missing `model`/`type`; do not mix old keyed and current array formats |
| Job menu does not show it | Correct job resource, grade table, duty/access conditions and model registration |
| Vehicle spawns but is locked | Keys integration for the authorized owner, not streaming |
| Bought vehicle disappears after reconnect | Ownership/save error or garage state; an admin-spawned entity is not a persisted purchase |
| Duplicate plates or duplicate vehicles | Purchase/spawn/storage logic; do not solve by clearing every player vehicle |

## Rollback and manual acceptance

Keep the last working config and source commit, restore only reviewed changes and restart the affected resource set during an approved maintenance window. If a staging purchase created a test record, clean up only that disposable record through a controlled process. Do not delete production ownership rows as a rollback shortcut.

Before release, record actual results for two players: streaming visibility, purchase, denied access, keys, storage, retrieval, reconnect and restart. These checks require FiveM and your asset; a passing documentation build does not execute them.

## Sources

- [Core vehicle list and lookup construction, 9b3cddcc](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/shared/vehicles.lua).
- [Vehicle-shop configuration, e8652970](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/config.lua) and [ownership schema](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/vehshop.sql).
- [Police-job configuration](https://github.com/qbcore-fivem/qb-policejob/blob/3ad3d190fa4d294f75506e2e3837b1124bfeb005/config.lua) and [grade-based vehicle menu](https://github.com/qbcore-fivem/qb-policejob/blob/3ad3d190fa4d294f75506e2e3837b1124bfeb005/client/job.lua).
- [Cfx.re resource manifests](https://docs.fivem.net/docs/scripting-reference/resource-manifest/) and [server commands](https://docs.fivem.net/docs/server-manual/server-commands/), checked 2026-09-21.
- [Cfx.re vehicle-integration support case](https://forum.cfx.re/t/qbcore-help/5240130), June 2024: an example of the gap between vMenu spawning and QBCore job integration, not a universal fix.
