> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/vehicles/dealership-cc_vehicleshop.md).

# Dealership (cc\_vehicleshop)

Showroom with 3D preview, test drive and purchase with paint and custom plate, plus a dealership that runs itself: restock orders, delivery runs from a depot and a catalogue curated by the boss.

**Frameworks:** ESX Legacy, QBCore, QBox (detected automatically, see Framework Bridge).

## Features

* Five dealerships: cars (Premium Deluxe Motorsport), motorcycles, trucks (La Mesa), boats (Puerto Del Sol Marina) and aircraft (LSIA)
* The catalogue comes straight from your framework (ESX tables `vehicles`/`vehicle_categories`, QBCore/QBox shared vehicle list), so prices are maintained once for all scripts
* 3D preview, paint colour selection and custom licence plate (extra charge, server-side validation)
* Payment by cash, bank or the customer's choice
* Test drive with a time limit and a temporary key
* Delivery on the spot or straight into a cc\_garage/00%20Overview\.md) garage
* Discount campaigns per category or model
* Stock per dealership and model
* Order system: employees order vehicles at a wholesale price, pick them up at the depot (Elysian Island) and drive them to the dealership; drivers are paid from the company account
* Dealers curate their own range and set their own prices within limits
* Revenue goes into the company account
* Boats are placed in the water and anchored until the customer is seated
* Price, discount, stock, plate, distance, rank and double pickup are validated on the server, with a per-player rate limit

## Optional integrations

| Resource                                     | Effect                                                                          |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| cc\_keys/00%20Overview\.md)                  | Keys for purchases, test drives and delivery runs; without it buyers get no key |
| cc\_garage/00%20Overview\.md)                | Delivery into a garage (`Config.Delivery = 'garage'`)                           |
| cc\_images%20(cc\_images)/00%20Overview\.md) | Vehicle images; otherwise an icon is shown                                      |
| cc\_lib/00%20Overview\.md)                   | Shared notification style                                                       |

{% hint style="info" %}
The script is protected by Cfx asset escrow. `config/`, `locales/`, `sql/` and the framework bridge files in `shared/` remain editable.
{% endhint %}

## Pages

* Installation
* Configuration
* API
* FAQ

Need help? See Support.

## Installation

See also the general installation guide and dependencies.

### Requirements

| Resource                                                                                | Required             | Purpose                                               |
| --------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------- |
| `oxmysql`                                                                               | Yes                  | Database (declared as `dependency` in the fxmanifest) |
| ESX Legacy / QBCore / QBox                                                              | Yes                  | Players, money, jobs and the vehicle catalogue        |
| Job `cardealer`                                                                         | Yes                  | All dealerships belong to this job by default         |
| Company account (`esx_addonaccount`, `qbx_management`, `qb-management` or `qb-banking`) | For the order system | Purchasing and delivery pay                           |
| `cc_lib`, `cc_keys`, `cc_garage`, `cc_images`                                           | Optional             | See overview                                          |

### Steps

1. Copy the folder to `resources/[crankchaos]/cc_vehicleshop`.
2. Add to your `server.cfg` (after your framework):

```cfg
ensure oxmysql
ensure cc_lib          # optional
ensure cc_keys         # optional
ensure cc_garage       # optional
ensure cc_images       # optional
ensure cc_vehicleshop
```

3. Restart the server.

### Database

The tables `cc_shop_catalog` and `cc_shop_orders` are created automatically on first start. `cc_vehicle_stock` is created by the shared vehicle bridge.

#### Shipped SQL files (ESX Legacy only, optional)

| File                             | Content                                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `sql/03-crankchaos-jobs.sql`     | Job labels and grade labels for `cardealer`, the `fueler` job with grades and its society account, vehicle category labels |
| `sql/04-crankchaos-vehicles.sql` | Adds boats, planes, helicopters and commercial vehicles to the `vehicles` table                                            |

Both files can be imported repeatedly without harm. QBCore and QBox do not need them.

{% hint style="warning" %}
On ESX the boat, aircraft and truck dealerships stay empty unless `04-crankchaos-vehicles.sql` (or your own entries) adds those vehicles to the `vehicles` table.
{% endhint %}

### Framework notes

* The job `cardealer` must exist in your framework. On ESX it needs a society account for the company account features.
* Prices are changed in the framework catalogue (ESX table `vehicles`, QBCore/QBox shared vehicles), not in the config.

### Permissions

No ACE permissions are required. Ordering and catalogue management are controlled by job and grade.

## Configuration

Editable files: `config/config.lua` (gameplay), `config/ui.lua` (look, language, `Config.Debug`), `locales/de.json`, `locales/en.json`, and the framework bridge in `shared/`. Set `locale = 'en'` in `config/ui.lua` for English.

### Interaction and map

```lua
Config.OpenKey = 38 -- E
Config.Distance = 3.0
Config.Blips = true
Config.BlipDefaults = { sprite = 326, colour = 3, scale = 0.8, shortRange = true }
```

`Config.Peds` (model `a_m_y_business_01`) places a seller at each dealership; `Config.Marker` draws a ground marker where no seller stands.

### Purchase

```lua
Config.Delivery = 'spawn'        -- 'spawn' or 'garage'
Config.DeliveryGarage = 'legion' -- must exist in cc_garage
Config.PaymentAccount = 'any'    -- 'cash', 'bank' or 'any'
Config.CustomPlatePrice = 6000   -- 0 disables custom plates
Config.Plate = {
    minLength = 2,
    maxLength = 8,
    pattern = '^[A-Z0-9 ]+$',    -- Lua pattern for allowed characters
}
```

{% hint style="info" %}
`Config.Plate.pattern` is a Lua pattern, not a regular expression. Length is set only via `minLength`/`maxLength`.
{% endhint %}

### Stock, test drive, offers

```lua
Config.Stock = { enabled = true, default = 5 }   -- default = initial stock per model
Config.TestDrive = { enabled = true, duration = 45 }
Config.Offers = {
    { category = 'sports', percent = 15 },
    { model = 'sultan', percent = 25 },
}
```

### Order system

```lua
Config.Order = {
    enabled = true,
    maxAmount = 10,       -- max units per order
    wholesale = 0.55,     -- purchase price as share of the framework list price
    payFrom = 'society',  -- 'society' or 'bank'
    leadTime = 300,       -- seconds until the order is ready
    minGrade = 1,         -- grade needed to order and pick up
    dropRadius = 25.0,    -- delivery radius around the dealership
    deliveryPay = 750,    -- driver pay per vehicle, from the company account
    keyMinutes = 30,      -- validity of the temporary delivery key
}
```

Flow: order, pay (list price x `wholesale` x amount), wait `leadTime`, pick up **one** vehicle at the depot, deliver within `dropRadius` (stock +1, driver receives `deliveryPay`). Each driver can have only one delivery at a time.

### Depot

```lua
Config.Depot = {
    enabled = true,
    ped = vector4(-41.54, -2513.28, 6.16, 311.58),
    pedModel = 's_m_m_dockwork_01',
    blip = { sprite = 477, colour = 47, scale = 0.7 },
    spots = {
        vector4(-46.58, -2503.58, 6.01, 237.01),
        { coords = vector4(-798.39, -1499.15, 0.37, 109.87), classes = { 14 } },
        { coords = vector4(-1691.08, -2938.44, 13.94, 243.23), classes = { 15, 16 } },
    },
}
```

A spot is a `vector4` or a table with `classes` to restrict it to GTA classes (14 boat, 15 helicopter, 16 plane).

### Own catalogue

```lua
Config.Catalog = {
    enabled = true,
    mode = 'extend',   -- 'extend' or 'only'
    minGrade = 'boss', -- 'boss' or a grade number
    minRatio = 0.5,
    maxRatio = 3.0,
}
```

* `extend`: all vehicles of the dealership's categories plus models the boss adds; own prices apply, removed models disappear.
* `only`: only the models the boss added.
* Own prices are clamped to `minRatio`-`maxRatio` of the list price. `Config.Offers` still apply. Newly added models start with stock 0.

### Paint, images, preview

`Config.Colours` lists the selectable paints (`index` = GTA colour, `hex` for the UI). `Config.Images` works like in cc\_garage (`base = 'https://cfx-nui-cc_images/vehicles'`, `extension = 'webp'`). `Config.Preview` sets the preview camera.

### Dealerships

```lua
{
    id = 'pdm',
    label = 'Premium Deluxe Motorsport',
    categories = { 'compacts', 'coupes', 'muscle', 'offroad', 'sedans',
                   'sports', 'sportsclassics', 'super', 'suvs', 'vans' },
    coords = vector3(-56.7, -1096.6, 26.4),
    ped = vector4(-56.3404, -1098.5220, 26.4224, 27.2502),
    spawn = vector4(-44.8, -1097.8, 26.4, 68.0),
    testSpawn = vector4(-44.8, -1097.8, 26.4, 68.0),
    blip = { sprite = 326, colour = 3, scale = 0.8 },
    job = 'cardealer',
}
```

| ID       | Categories                                    |
| -------- | --------------------------------------------- |
| `pdm`    | Road cars (see above)                         |
| `bikes`  | `motorcycles`                                 |
| `trucks` | `commercial`, `industrial`, `utility`, `vans` |
| `boats`  | `boats`                                       |
| `planes` | `planes`, `helicopters`                       |

A different `job` per dealership separates orders, company account and depot list automatically. `pedModel` overrides the seller model per dealership.

## Exports, Events & Commands

cc\_vehicleshop provides **no exports**, no public events and no state bags. It uses cc\_keys/03%20Exports%2C%20Events%20%26%20Commands.md) (`GiveKeys`/`RemoveKeys`) and cc\_garage/00%20Overview\.md) when they are running.

### Commands

| Command / key         | Effect                                                           | Permission                                        |
| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
| E (at seller / depot) | Open dealership or depot                                         | Everyone; ordering and catalogue by job and grade |
| `/ccshop [id]`        | Open a dealership from anywhere, only when `Config.Debug = true` | Everyone (debug only)                             |
| `/ccdepot`            | Open the depot from anywhere, only when `Config.Debug = true`    | Everyone (debug only)                             |

### Database tables

| Table              | Content                                                         |
| ------------------ | --------------------------------------------------------------- |
| `cc_vehicle_stock` | Stock per dealership and model                                  |
| `cc_shop_catalog`  | The dealer's own range and prices                               |
| `cc_shop_orders`   | Orders and their progress (completed orders remain as a record) |

## FAQ & Troubleshooting

**The boat, aircraft or truck dealership is empty (ESX).** Import `sql/04-crankchaos-vehicles.sql` or add those vehicles to the `vehicles` table with the matching categories.

**How do I change vehicle prices?** In your framework catalogue (ESX table `vehicles`, QBCore/QBox shared vehicles). Dealers can also set their own prices in the catalogue tab within `Config.Catalog.minRatio`-`maxRatio`.

**Nobody can order vehicles or edit the catalogue.** The player needs the dealership's `job` (default `cardealer`) and at least `Config.Order.minGrade` (ordering) or `Config.Catalog.minGrade` (catalogue, default the boss grade). If the company account is not ready at start, nobody counts as boss.

**Orders cannot be paid.** With `payFrom = 'society'` the company account must exist and contain enough money. On ESX this needs `esx_addonaccount` and a society account for the job.

**Buyers do not get a key.** Install cc\_keys/00%20Overview\.md).

**Ordered boats or aircraft cannot be picked up.** The depot needs spots with matching `classes` (in the water for boats, on the runway for aircraft). The shipped config contains one of each; add more if needed.

**Purchased vehicles should go to a garage.** Set `Config.Delivery = 'garage'` and `Config.DeliveryGarage` to a garage ID from cc\_garage/00%20Overview\.md).

**A custom plate is rejected.** It must match `Config.Plate.pattern`, respect `minLength`/`maxLength` and be unique.

**Known limitation:** the distance to the dealership is checked once when opening, not continuously, because the 3D preview moves the player.

Still stuck? See Support.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ccfivem.gitbook.io/ccfivem-docs/vehicles/dealership-cc_vehicleshop.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.