QBCore Frameworkqbcore.netCommunity docs
On this page

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.ytd

A 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.

FieldCheck
modelExact spawn model, not the resource folder or display name
name, brandHuman-readable labels; do not use them as spawn identifiers
priceServer's intended sale price; illustrative values here are not economy advice
categoryCategory supported by the installed shop's filtering/menu
typeCorrect entity type for that asset; automobile is not suitable for every boat, aircraft or bike
shopAn 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:

StepWhat to verify
PurchaseExactly one intended payment; the correct model and plate belong to the test character
SpawnCorrect model, plate, fuel and applicable properties
KeysAuthorized owner can unlock/start it; a different player does not gain access automatically
StoreThe configured garage accepts the vehicle and the ownership/state record is updated
RetrieveThe intended stored vehicle returns without duplicate ownership or duplicate active instances
Reconnect/restartSaved 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

SymptomInvestigate first
Model will not spawn anywhereAsset files, actual spawn name, manifest and compatible game build/edition
Admin spawn works, dealer does not list itShared array entry, shop, category and coordinated restart
Dealer display works, purchase failsServer transaction, owning schema and integration error
Vehicle is listed but model data is nilEntry placement and missing model/type; do not mix old keyed and current array formats
Job menu does not show itCorrect job resource, grade table, duty/access conditions and model registration
Vehicle spawns but is lockedKeys integration for the authorized owner, not streaming
Bought vehicle disappears after reconnectOwnership/save error or garage state; an admin-spawned entity is not a persisted purchase
Duplicate plates or duplicate vehiclesPurchase/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

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website