ds-vehicletrustsystem

# DS Vehicle Trust System

- A FiveM resource that lets players **own** and **share** personal vehicles with trusted people.

Only owners and players you trust can drive your vehicles; everyone else is ejected.

Includes a **modern NUI**, **job vehicles**, **vehicle keys** integration, and optional **MySQL** storage.

**Frameworks:** ESX, QBCore, QBox (auto-detected)

**Storage:** JSON (default) or MySQL

## Features

| Feature | Description |

|--------|-------------|

| **My Vehicles** | See vehicles you’re allowed to drive; click to spawn. Fuel/engine/body and saved appearance (paint, extras, upgrades) when supported. |

| **Trust / Untrust** | Give or revoke another player’s permission to drive one of your owned vehicles (dropdown: player + vehicle). |

| **Job Vehicles** | Configure per-job vehicle lists; job members can spawn those vehicles with saved appearance. Manage via **Job** tab and `/vehwlsetjobvehicle` / `/vehwlremovejobvehicle`. |

| **Set Owner** (admin) | Assign a player as owner of a vehicle (dropdown: player + vehicle from whitelist). |

| **Clear** (admin) | Remove all data for a vehicle so it can be reassigned (dropdown: vehicle from whitelist). |

| **All Vehicles** (admin) | View all players and their vehicles (including offline); search by player or vehicle. |

| **Access check** | If someone drives a personal vehicle they’re not allowed to use, they are ejected and notified. |

| **Keys** | When you or a trusted player spawns or enters an allowed vehicle, the script can give keys (qb-vehiclekeys, vehicles_keys, ox_lib, etc.). |

| **Revoke on untrust** | When you untrust someone (or remove a job vehicle), their keys are revoked and, if they’re in that vehicle, they’re removed and the vehicle is despawned. |

| **Notifications** | Built-in NUI Notifications or your framework/third-party notify (QBCore, ox_lib, okokNotify, etc.). |

## Requirements

- **Optional:** ESX, QBCore, or Qbox (for notifications and job detection)

- **Optional:** oxmysql (only if using `Config.Storage = "mysql"`)

- **Optional:** A key script (e.g. qb-vehiclekeys, vehicles_keys) if you want keys given/revoked automatically

## Installation

1. Place the `ds-vehicletrustsystem` folder in your server’s `resources` directory.

2. Add to `server.cfg`:

ensure ds-vehicletrustsystem

If using **MySQL**, ensure oxmysql runs first and run the SQL file once:

ensure oxmysql

ensure ds-vehicletrustsystem

3. Run the SQL files in `sql/` on your database (only if using MySQL):

- `sql/ds_vehicle_trust.sql` – main whitelist table

- `sql/ds_vehicle_trust_jobs.sql` – job vehicles table

- Any migration files if you’re upgrading.

4. Configure `shared/config.lua` (see below).

## Configuration

Edit **`shared/config.lua`**. Main options:

| Option | Description |

|--------|-------------|

| **Config.Locale** | UI language: `"en"`, `"de"`, `"es"`. |

| **Config.Framework** | `"auto"` (recommended), `"esx"`, `"qbcore"`, `"qbox"`, or `"none"`. |

| **Config.Storage** | `"json"` (default, uses `saved/data/whitelist.json`) or `"mysql"`. |

| **Config.AdminDiscordUserIds** | List of **Discord user IDs** that can use admin tabs and commands. Get your ID: Discord → User Settings → App Settings → Developer Mode → Right‑click your name → Copy User ID. |

| **Config.ShowAdminTabs** | If `true`, everyone sees admin tabs (actions still require admin). If `false`, only Discord admins see them. |

| **Config.KeysResource** | `"auto"` (try supported key scripts), `""` (disable), or exact resource name (e.g. `"qb-vehiclekeys"`, `"vehicles_keys"`). |

| **Config.Notify** | `"auto"` (framework → third‑party → built‑in), `"builtin"` (NUI toasts only), or a specific system (qbcore, ox_lib, okokNotify, etc.). |

| **Config.NotifyDuration** | How long (ms) notifications stay on screen (default `5000`). |

| **Config.OpenCommand** | Command to open the UI (default: `vehicletrust`). |

| **Config.OpenKey** / **Config.OpenKeyModifier** | Keybind to open UI (e.g. F7 + Left Alt). Set `OpenKey` to `nil` to disable. |

| **Config.CheckInterval** | How often (ms) to check if the driver is allowed in the current vehicle (default `5000`). |

| **Config.Discordlogging** | Set to `true` and set **Config.DiscordWebhook** to log trust/untrust/setOwner/clear to Discord. |

| **Config.DebugSoloTest** | If `true`, admins can use `/vehwl_solotest \` to set themselves as owner when testing alone. |

| **Config.SoloTestNoAdmin** | If `true`, anyone can use `/vehwl_solotest` (only for testing; set `false` on live). |

## Admin Setup

Admins are defined by **Discord user ID** only (no framework groups or ACE by default).

1. Get your Discord user ID (Developer Mode → Right‑click your name → Copy User ID).

2. In `shared/config.lua`, add it to **Config.AdminDiscordUserIds**:

Config.AdminDiscordUserIds = {

"xxxxxxxxxxxxxxxxxx",

"xxxxxxxxxxxxxxxxxx",

}

3. Restart the resource. You can now use the **Set Owner**, **Clear**, and **All Vehicles**

tabs and the `/setOwner` and `/clear` commands.

## Usage

### Players

- **Open UI:** `/vehicletrust` or the keybind (default: **Left Alt + F7**).

- **My Vehicles:** First tab lists vehicles you’re allowed to drive; click one to spawn it (with saved appearance when available).

- **Trust:** Choose a **player** and an **owned vehicle** from the dropdowns, then click **Trust**.

- **Untrust:** Same dropdowns; click **Untrust** to revoke access. Their keys are revoked and, if they’re in that vehicle, they’re removed and the vehicle is despawned.

- **Job tab:** If you have a job with vehicles configured, use the **Job** tab to spawn job vehicles and manage trusted/untrusted players for them.

- **Chat:** `/vehicles` – list your allowed vehicles in chat.

### Admins

- **Set Owner:** Open the **Set Owner** tab, choose **Player** and **Vehicle** from the dropdowns

(vehicles come from the whitelist), then click **Set Owner**.

- **Clear:** Open the **Clear** tab, choose **Vehicle** from the dropdown, then click **Clear vehicle data**.

- **All Vehicles:** View and search all players and their vehicles (including offline).

- **Chat:** `/setOwner \ \, \/clear \` (still work if you prefer typing).

## Commands

| Command | Who | Description |

|--------|-----|-------------|

| `/vehicletrust` | Everyone | Opens the UI. |

| `/vehicles` | Everyone | Lists vehicles you can drive (chat). |

| `/trust \ \ | Everyone | Trust player \id` for vehicle `spawncode` (you must own it). |

| `/untrust \ \` | Everyone | Revoke trust for that player and vehicle. |

| `/setOwner \ \ | Admin | Set player \id` as owner of `spawncode`. |

| `/clear \` | Admin | Clear all data for that vehicle. |

| `/vehwl_solotest \` | Admin (or anyone if SoloTestNoAdmin) | Set yourself as owner for testing (e.g. when alone). |

| `/vehwlsetjobvehicle \ \` | Players with that job | Add vehicle to your job’s list (run while in the vehicle to save appearance). |

| `/vehwlremovejobvehicle \ \` | Players with that job | Remove vehicle from your job’s list. |

## Key Scripts

When **Config.KeysResource** is `"auto"`, the script tries (in order) to give/revoke keys with:

- qbx_vehiclekeys, qb-vehiclekeys, qs-vehiclekeys

- Renewed-Vehiclekeys, mm_carkeys, MrNewbVehicleKeys, pb-vehiclekeys

- fivecode_carkeys, is_vehiclekeys, vehicles_keys

Set **Config.KeysResource** to the exact resource name if you use one of these, or to `"custom"` and

configure **Config.KeysCustom** / **Config.KeysCustomServer** for your key script.

Keys are given when a player spawns a vehicle or enters one they’re allowed to drive, and revoked when they’re untrusted or the vehicle is removed from their job.

## Notifications

- **Config.Notify = "auto"** – Uses your framework (QBCore, ESX, Qbox) or a supported third‑party notify (ox_lib, okokNotify, motion_notify, skys_notifications, knotify, rxnotify, mythic_notify, tab_notify, fivem_notify, sc_notify), then falls back to **built‑in NUI toasts** (top‑right).

- **Config.Notify = "builtin"** – Always use the built‑in toasts.

- **Config.NotifyDuration** – Duration in ms (default `5000`).

## Job Vehicles

- Configure job vehicles via the **Job** tab (if you have a job that’s not civilian/unemployed) or

with **/vehwlsetjobvehicle** and **/vehwlremovejobvehicle**.

- When you add a vehicle while in it, the current **appearance** (paint, extras, upgrades) is saved so job members spawn that look.

- Job vehicles are stored in `saved/data/job_vehicles.json` (JSON) or in the `ds_vehicle_trust_jobs` table (MySQL).

## Storage

- **JSON (default):** `saved/data/whitelist.json` (player trust data), `saved/data/job_vehicles.json` (job vehicles). No database required.

- **MySQL:** Set **Config.Storage = "mysql"**, ensure **oxmysql** is started before this resource,

and run the scripts in the `sql/` folder once. Tables: `ds_vehicle_trust`, `ds_vehicle_trust_jobs` (and migrations if provided).

## Testing When Alone

1. Add your **Discord user ID** to **Config.AdminDiscordUserIds** in `shared/config.lua`.

2. Set **Config.DebugSoloTest = true** (and optionally **Config.SoloTestNoAdmin = true** for quick testing).

3. In-game, run: `/vehwl_solotest ADDER` (or any spawn code). You become the owner of that vehicle.

4. Open the UI with `/vehicletrust` or the keybind – you should see the vehicle under **My Vehicles**, and

you can use **Trust** / **Untrust** (with another player), **Set Owner**, and **Clear** from the dropdowns.

5. Set **Config.SoloTestNoAdmin = false** and **Config.DebugSoloTest = false** on a live server.

## Locales

Set **Config.Locale** to `"en"`, `"de"`, or `"es"` (must match a file in `locales/`). Included:

- **locales/en.lua** – English

- **locales/de.lua** – German

- **locales/es.lua** – Spanish

You can add more locale files and set **Config.Locale** to their key.

## Credits

- Original concept: [VehicleTrustSystem]() by JaredScar.

- This version: **Deluxe Shop | UnknownGhostModz** – NUI, Discord admin, keys, job vehicles, appearance, revoke/despawn, and optional MySQL.