7 min read
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 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:
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.ytdA corresponding minimal manifest is:
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:
{
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 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.
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:
-- 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 and vehicle-key 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 and database ownership 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.
- Vehicle-shop configuration, e8652970 and ownership schema.
- Police-job configuration and grade-based vehicle menu.
- Cfx.re resource manifests and server commands, checked 2026-09-21.
- Cfx.re vehicle-integration support case, June 2024: an example of the gap between vMenu spawning and QBCore job integration, not a universal fix.
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.
ox_target on QBCore
Use ox_target zones on QBCore, migrate qb-target options and handle job checks safely. Learn the limits of framework bridges and compatibility exports.
Pleb Masters Forge
Find GTA models with Pleb Masters Forge, check a vehicle on your FiveM client, distinguish names from hashes, and use the result in QBCore resources.
