> For the complete documentation index, see [llms.txt](https://prfortiq.gitbook.io/wolfstudio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prfortiq.gitbook.io/wolfstudio/fivem/ws-advanced-vehicleshop-system.md).

# WS Advanced Vehicleshop System

<figure><img src="https://3577248138-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfrEiBDiEXkx8P9LNYgAl%2Fuploads%2F7fAJajPxt3ICcblf42Kq%2Fbd20178c-9b07-4bb7-9407-9578b6da6302.png?alt=media&amp;token=757006e2-8afe-4bb3-8c0e-6d82fb47b1f9" alt=""><figcaption></figcaption></figure>

A modern vehicle shop with categories, search, price filter, sorting and a test-drive feature. Compatible with **QBCore** and **ESX**.

{% hint style="info" %}
**QBox support will follow in a later update.** The scripts are currently shipped and officially supported for QBCore and ESX. As soon as the QBox version is ready, it will be provided free of charge as an update.
{% endhint %}

## Features

* Multiple shops (PDM, Luxury, Boats, Truck – fully configurable)
* Categories, live search, price-range filter & sorting
* Test drive with time limit and cost
* Blips & seller ped, either with a target system or `[E]` interaction
* Multilingual (English / German) via `Config.Locale`

## Requirements

| Dependency                            |  Required  | Purpose                                             |
| ------------------------------------- | :--------: | --------------------------------------------------- |
| `oxmysql`                             |      ✅     | Database connection                                 |
| `qb-core` **or** `es_extended`        |      ✅     | Framework                                           |
| `ox_target` / `qb-target` / `qtarget` | ⭕ optional | Interaction at the seller (otherwise `[E]`)         |
| `LegacyFuel`                          | ⭕ optional | Fill the tank on purchase (ox\_fuel etc. also work) |

{% hint style="danger" %}
`ws-vehicleshop` **must** be started after the framework and `oxmysql`, otherwise the core will not be detected.
{% endhint %}

## Installation – QBCore

{% stepper %}
{% step %}

### Add the resource

Copy the `ws-vehicleshop` folder into your `resources` folder (e.g. into `[ws]` or `[custom]`).
{% endstep %}

{% step %}

### server.cfg

```cfg
ensure oxmysql
ensure qb-core
ensure ws-vehicleshop
```

{% endstep %}

{% step %}

### Framework setting

In `config.lua`:

```lua
Config.Framework = 'auto' -- 'auto', 'qb', or 'esx'
```

* `'auto'` detects QBCore automatically (`qb-core`).
* Or set it explicitly to `'qb'`.
  {% endstep %}

{% step %}

### Where do the vehicles come from?

Under QBCore the vehicles are read directly from the core's shared vehicle list (`QBCore.Shared.Vehicles`). You do **not** need to import anything – every vehicle your core knows is available.

**Assigning a vehicle to a shop** via the vehicle's `shop` field:

```lua
-- in qb-core/shared/vehicles.lua
{ model = 'blista', name = 'Blista', ... , shop = 'pdm' },

-- multiple shops possible:
{ model = 'adder',  name = 'Adder',  ... , shop = { 'pdm', 'luxury' } },
```

The value must match the shop ID in `Config.Shops` exactly (e.g. `pdm`, `luxury`, `boats`, `truck`). Vehicles **without** a `shop` field are assigned via the shop's `categories` list instead (see Configuration).
{% endstep %}

{% step %}

### Database

Purchases are written to the existing QBCore table `player_vehicles` – **no** additional SQL file is required.
{% endstep %}
{% endstepper %}

## Installation – ESX

{% stepper %}
{% step %}

### Add the resource

Copy the `ws-vehicleshop` folder into your `resources` folder.
{% endstep %}

{% step %}

### server.cfg

```cfg
ensure oxmysql
ensure es_extended
ensure ws-vehicleshop
```

{% endstep %}

{% step %}

### Framework setting

In `config.lua`:

```lua
Config.Framework = 'auto' -- 'auto', 'qb', or 'esx'
```

* `'auto'` detects ESX automatically (`es_extended`).
* Or set it explicitly to `'esx'`.
  {% endstep %}

{% step %}

### Where do the vehicles come from?

Under ESX the vehicles are read from the database:

* Table `vehicles`
* Table `vehicle_categories`

These tables must be filled (standard on most ESX servers).

ESX vehicles do **not** have a `shop` field – the assignment is done via the **categories**. Define per shop in `config.lua` which categories are shown:

```lua
['pdm'] = {
    -- ...
    ['categories'] = { 'compacts', 'sports', 'super', 'muscle', 'suvs' }
}
```

{% hint style="danger" %}
Under ESX the `categories` list is **MANDATORY** – if it is empty or does not match the vehicles' `category` values, the vehicle list stays empty.
{% endhint %}
{% endstep %}

{% step %}

### Boats (optional)

An SQL file for the boat shop is included: `ws-vehicleshop/esx_boats.sql`. Only run it if you want to sell boats under ESX.
{% endstep %}

{% step %}

### Replace the old esx\_vehicleshop

If you previously used `esx_vehicleshop`, replace it with `ws_vehicleshop` in the dependencies of your job scripts (the script provides `provide 'ws_vehicleshop'`):

{% code title="esx\_policejob/fxmanifest.lua" %}

```lua
dependencies {
    'es_extended',
    'esx_billing',
    'ws_vehicleshop'   -- before: 'esx_vehicleshop'
}
```

{% endcode %}

{% code title="esx\_ambulancejob/fxmanifest.lua" %}

```lua
dependencies {
    'es_extended',
    'esx_skin',
    'ws_vehicleshop'   -- before: 'esx_vehicleshop'
}
```

{% endcode %}

{% code title="esx\_boat/fxmanifest.lua" %}

```lua
dependencies {
    'es_extended',
    'ws_vehicleshop'   -- before: 'esx_vehicleshop'
}
```

{% endcode %}
{% endstep %}

{% step %}

### Database

Purchases are written to the existing ESX table `owned_vehicles`.
{% endstep %}
{% endstepper %}

## Configuration

All settings are located in `config.lua`.

### General settings

```lua
Config.Framework     = 'auto'  -- 'auto', 'qb', or 'esx'
Config.Locale        = 'de'    -- Language: 'de' or 'en'
Config.TestDriveCost = 500     -- Cost per test drive
Config.TestDriveTime = 60      -- Test drive duration in seconds
Config.Currency      = 'bank'  -- 'bank' or 'cash' for purchase & test drive
```

| Setting                | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| `Config.Framework`     | Framework selection. `'auto'` detects QBCore/ESX automatically. |
| `Config.Locale`        | UI language (`locales/de.lua` or `locales/en.lua`).             |
| `Config.TestDriveCost` | Cost per test drive.                                            |
| `Config.TestDriveTime` | Test drive duration in seconds.                                 |
| `Config.Currency`      | `'bank'` or `'cash'` for purchase & test drive.                 |

### Setting up shops

Each shop is defined under `Config.Shops`:

```lua
['pdm'] = {
    ['ShopLabel']      = 'Premium Deluxe Motorsport', -- Name (blip/marker)
    ['showBlip']       = true,                        -- Show blip?
    ['blipSprite']     = 326,                         -- Blip icon
    ['blipColor']      = 3,                           -- Blip color
    ['Location']       = vector3(-45.67, -1098.34, 26.42),        -- Seller/blip
    ['VehicleSpawn']   = vector4(-56.79, -1109.85, 26.43, 71.5),  -- Spawn after purchase
    ['TestDriveSpawn'] = vector4(-56.79, -1109.85, 26.43, 71.5),  -- Test drive spawn
    ['categories']     = { 'compacts', 'sports', 'super' } -- ESX only (see below)
},
```

**Categories (`categories`):**

* **QBCore:** not required – vehicles are assigned via their `shop` field.
* **ESX:** **mandatory** – determines which vehicle categories appear in the shop.

Available default categories:

```
compacts, coupes, sedans, muscle, suvs, offroad, motorcycles, sports,
sportsclassics, super, vans, commercial, industrial, service, utility,
boats, planes, helicopters, cycles, military, emergency
```

### Category labels & language

* The displayed category names come from the `locales/` files (table `categories`) and follow `Config.Locale`.
* Under ESX, labels from the `vehicle_categories` table take priority.
* For custom text/additional languages: edit the files under `locales/`, then `restart ws-vehicleshop`.

### Target system

If one of these systems is detected, the seller is triggered through it – otherwise `[E]` interaction is used automatically: `ox_target`, `qb-target`, `qtarget`.

## Important Notice

{% hint style="danger" %}
**Info**

Our scripts are available exclusively on tebex. All other third-party providers are considered leaks and therefore violate our terms of use and intellectual property rights.

If you discover that our scripts are found on third-party websites such as vag.gg, Launcher-Leaks, or other shopping systems that have nothing to do with fivem and cfx.re, please report them urgently via Discord. The third-party provider will face appropriate consequences.

It is also not permitted to download, purchase, upload, sell, or use third-party scripts. This can have consequences for both users and server owners.

If our scripts contain errors or you need help, you can also report them via our Discord.
{% endhint %}