ds-advanceddealership

# DS Advanced Dealership

Advanced Dealership — full car dealership system for **QBCore**, **QBox**, and **ESX**, with a showroom, player-run dealer jobs, financing, trade-ins, test drives, walkable vehicle displays, and a management/employee tablet.

## Requirements

| Dependency | Required | Notes |

| [ox_lib](https://github.com/overextended/ox_lib) | Yes | Core utility library |

| [oxmysql](https://github.com/overextended/oxmysql) | Recommended | Needed for persistence (finance contracts, saved vehicles, displays). Set `Config.Database = "off"` to run without a database. |

| QBCore / QBox / ESX | One of these | Framework is auto-detected (`Config.Framework = 'auto'`) |

| A target system | Optional | `ox_target`, `qb-target`, `qtarget`, or plain "Press E" (`Config.Target`) |

| A vehicle-keys resource | Optional | `qb-vehiclekeys`, `qs-vehiclekeys`, `wasabi_carlock`, `mk_vehiclekeys`, or none |

| A fuel resource | Optional | `LegacyFuel`, `qb-fuel`, `ps-fuel`, `lc_fuel`, `lj-fuel`, `ox_fuel`, `nd_fuel`, or none |

| `ox_inventory` (or your inventory) | Only if using the tablets | See **Tablet items** below |

## Installation

1. Drop the `ds-advanceddealership` folder into your `resources` directory.

1. Add ensure ds-advanceddealership to your server.cfg, **below** your framework, `ox_lib`, and `oxmysql`.

3. Start (or restart) your server. With `Config.DatabaseAutoInstall = true` (default), the required tables are created automatically from:

   - `sql/qb-qbx/install.sql` (QBCore / QBox)

   - `sql/esx/esx_vehicles.sql` (ESX)

4. If you use the Management/Employee tablets, add the item definitions — see below.

1. Open config/config.lua and config/locations.lua and set up your dealership locations, jobs, and framework options (see **Configuration**).

### Tablet items (management_tablet / employee_tablet)

If you want players to carry the tablets as inventory items:

• **ox_inventory**: paste the entries from `install/ox_items.txt` into `data/items.lua`, then copy `install/images/*.png` into `ox_inventory/web/images/`.

• **qb-inventory / qs-inventory**: see `install/qb_items.txt` for the equivalent entries.

## Configuration quick reference

Most day-to-day setup lives in two files:

• **`config/config.lua`** — framework, target/keys/fuel integrations, financing rules, test drive rules, trade-in rules, dealer job commission/pricing limits, webhooks, anti-cheat, and UI options.

• **`config/locations.lua`** — vehicle colour swatches, category list, and every dealership lot (`Config.DealershipLocations`): showroom/management/sell/trade coords, purchase & test-drive spawn points, camera angles, which categories/job/shop it sells, and per-lot toggles for test drive, sell, trade-in, finance, and coupons.

A few settings worth knowing about before you go live:

- `Config.Database` — `"off"` disables MySQL entirely (nothing persists); `"auto"`/`"oxmysql"` enables real saves.

- `Config.DealerJob` — controls player-run dealerships: which jobs count as dealer staff, commission %, and the min/max % of list price employees can sell at.

- `Config.Finance` — down payment %, interest rate, term length, and repossession-after-missed-payments behaviour.

- `Config.AdminCommand` (default `dealeradmin`) — change the command name/ACE permission for the admin menu.

- `Config.Webhooks` — Discord webhook URLs for purchases, financing, missed payments, repossessions, and admin actions (leave blank to disable any category).

## Commands

| Command | Who | Purpose |

| `/dealeradmin` | ACE `command.dealeradmin` (configurable) | Opens the admin menu |

| `/createcoupon` | Admin | Creates a discount coupon code |

| `/sell` | Dealer job staff, near their lot's sell point | Sell a vehicle to a customer |

| `/repo \` | Admin, or dealer staff whose job matches that lot | Repossess a vehicle by plate |

## Everyday usage

• **Customers**: walk up to a dealership showroom marker, press **E** to browse categories → vehicles → detail screen (test drive, apply coupon, pay cash/bank, or finance).

• **Test drives**: time-limited, optionally with a deposit and speed cap; the vehicle is returned automatically when the timer ends.

• **Trade-ins**: available at lots with a trade point enabled; pays out a % of the vehicle's listed price, subject to minimum engine/body health.

• **Dealer staff**: use the Employee Tablet (or `/sell`) to sell vehicles directly to a customer at your dealership's sale point.

• **Boss/management**: use the Management Tablet to manage stock, pricing, employees, and place walkable **display vehicles** for customers to browse in person

## Localization

Nine languages are bundled in `locales/` (`en`, `es`, `fr`, `de`, `it`, `pl`, `pt`, `ru`, `tr`). Set `Config.Locale` in `config/config.lua` to switch, or edit a locale file directly to change wording.