> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexdev.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Where every NEX Garages setting lives and what the important toggles do.

The config is split per domain — one file per topic, all under `config/` and
all editable (never escrowed):

| File                                                  | What it controls                                                                                           |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `config/main.lua`                                     | Locale, currency/date format, framework selector, UI accent color, cinematic mode, SQL auto-install, debug |
| `config/public-garages.lua`                           | Public garage locations                                                                                    |
| `config/job-garages.lua`                              | Job garage locations & spawner fleets                                                                      |
| `config/gang-garages.lua`                             | Gang garage locations                                                                                      |
| `config/impound-locations.lua`                        | Impound lot locations                                                                                      |
| `config/interior.lua`                                 | The walk-in showroom interior                                                                              |
| `config/garage-defaults.lua`                          | Shared blip & marker defaults for the location files                                                       |
| `config/custom-garages.lua`                           | The in-game garage editor (`/garagesadmin`) + staff ACE                                                    |
| `config/private-garages.lua`                          | Player-owned private garages                                                                               |
| `config/impound.lua`                                  | Impound command, society fund, hold durations, fee cap, proximity rule                                     |
| `config/features.lua`                                 | Capacity, store fees, repair, mileage, sharing, selling, pins, finance, auto-impound, audit, phone         |
| `config/vehicles.lua`                                 | Spawning & persistence, retrieval fees, transfers, vehicle classes, labels                                 |
| `config/vehicle-images.lua`                           | Thumbnail image sources                                                                                    |
| `config/integrations.lua`                             | Fuel / keys / notify / banking / gangs / textUI / target / radial                                          |
| `config/controls.lua`                                 | Key binds & interaction prompts                                                                            |
| `config/commands.lua`                                 | Staff & admin command names                                                                                |
| `config/word-filter.lua`                              | Blocked words for nicknames, impound reasons, etc.                                                         |
| `config/hooks-client.lua` / `config/hooks-server.lua` | Custom event hooks to veto or react to actions                                                             |
| `locales/*.json`                                      | Translations (English & Spanish included)                                                                  |

## Framework & locale (`config/main.lua`)

```lua theme={null}
Locale = "en",                -- matches a file in locales/
Framework = "auto",           -- "auto" | "QBCore" | "Qbox" | "ESX"
AutoRunSQL = true,            -- install the schema on start
```

Leave `Framework` on `"auto"` unless you run multiple frameworks side by side.

## UI accent color (`config/main.lua`)

The UI ships monochrome, but every highlight surface — primary buttons,
active tabs, condition bars, status chips, toasts, checkboxes — follows one
accent color you can change without touching the UI bundle:

```lua theme={null}
UI = {
  accentColor = "#FFFFFF",     -- try your server's brand color
  accentTextColor = "#000000", -- text on accent surfaces; use "#FFFFFF" for dark accents
},
```

Body text stays neutral so any accent keeps the panels readable.

## Cinematic garage mode — beta (`config/main.lua`)

<Warning>
  The cinematic garage is a **beta** feature. It's fully playable, but still
  being polished — if anything behaves oddly on your server, keep
  `enabled = false` and report it to us.
</Warning>

Prefer an in-world browser over the list menu? Enable the cinematic garage:

```lua theme={null}
CinematicGarage = {
  enabled = true,
  camera = {                            -- offsets relative to the previewed vehicle
    coords = vector3(3.0, 5.5, 0.3),
    focus = vector3(-0.75, 1.2, 0.0),
    fov = 35.0,
  },
  transitionMs = 650,
  switchMs = 350,
  screenEffects = true,   -- held vignette while browsing, bright pulse in/out
  vignetteStrength = 1.0, -- 0.0 - 1.0 intensity of the held vignette
  wipeTransition = true,  -- accent-edged wipe panel sweeping across on enter & exit
  seatPlayer = true,      -- sit the player in the previewed vehicle's driver seat
  hideHud = true,         -- hide minimap, GTA HUD and detected framework HUDs while browsing
},
```

`hideHud` auto-detects common HUD resources (`qbx_hud`, `qb-hud`, `ps-hud`,
`jg-hud`, `izzy-hud`, `0r-hud`) — pick one explicitly or turn it off with the
`hud` option in `config/integrations.lua`.

Pressing **E** at a garage then previews your stored vehicles one at a time at
the spawn point — with your mods, livery and plate — behind a cinematic
camera. **← / →** browse, **E / ENTER** drives, **↑** opens the actions
drawer (pin, repair, track, transfer, share, sell, rename, go inside —
navigate with **↑ / ↓**, confirm with **ENTER**), and **BACKSPACE / ESC**
exits. A slim HUD shows the vehicle's name, plate, condition, mileage, class
and status badges.

Previews are only visible to you and can't be entered or damaged. Impound
lots and job spawner garages always keep the classic menu, and the classic
panel still opens when nothing is parked at the garage — nothing from the
regular menu is ever out of reach.

## Spawning & persistence (`config/vehicles.lua`)

```lua theme={null}
Nex.Config.Spawning = {
  saveDamage = true,        -- persist & restore body/engine damage
  advancedDamage = true,    -- per-panel deformation (bundled)
  savePropsOnStore = true,  -- persist mods/props when a vehicle is stored
  checkVehicleModel = true, -- entity model must match the DB row
  useServerSetter = false,  -- create vehicles server-side from the start
}
```

`Nex.Config.Retrieval.returnCost` is the towing fee charged when a vehicle
was left out or destroyed. `Nex.Config.Transfers` controls garage-to-garage
and player-to-player transfers, their cost, a spawn-name blacklist, and
`nearbyPlayerRadius` — player transfers, shares and sales only list and
allow players within that range (default 10 m, `false` = whole server).

## Vehicle classes (`config/vehicles.lua`)

Speed tiers (D–S) derived from each vehicle's `fInitialDriveMaxFlatVel`
handling value. Give any garage `vehicleClasses = { "C", "D" }` to restrict
what can park there; omit it to allow everything. Per-vehicle overrides and a
fallback class are available under `Nex.Config.VehicleClasses`.

## Feature toggles (`config/features.lua`)

Every gameplay extra has its own block with an `enabled` flag: capacity
limits, store fees, finance blocking, auto-impound, mileage & service
reminders, paid repairs, selling to players, shared access, pins, the track
blip, the audit log, and phone exports. Open the file — each block is
commented.

## Vehicle thumbnails (`config/vehicle-images.lua`)

Thumbnails load from a URL template — no image files ship with the resource.
The default CDN covers every base-game vehicle. For addon cars, add direct
links per spawn name in `Nex.Config.VehicleImageLinks`
(`config/vehicles.lua`), or point the `url` template at your own image host.
Set `url = false` to disable thumbnails — the UI falls back to a monogram.

## Discord webhooks (server.cfg)

Webhook URLs are read from convars so they never live inside resource files.
Add the categories you want to `server.cfg` and restart:

```cfg theme={null}
set nex_garages_webhook_store_takeout   "https://discord.com/api/webhooks/..."
set nex_garages_webhook_player_transfer "https://discord.com/api/webhooks/..."
set nex_garages_webhook_garage_transfer "https://discord.com/api/webhooks/..."
set nex_garages_webhook_impound         "https://discord.com/api/webhooks/..."
set nex_garages_webhook_private_garages "https://discord.com/api/webhooks/..."
set nex_garages_webhook_custom_garages  "https://discord.com/api/webhooks/..."
```

Leave a convar unset to disable that category.

<Warning>
  Use `set`, not `setr` — replicated convars are visible to every client, and
  webhook URLs must stay server-side.
</Warning>

## Hooks (`config/hooks-client.lua` / `config/hooks-server.lua`)

`hooks-client.lua` ships with events that fire on store, impound, take-out
and transfer, plus verification callbacks you can return `false` from to veto
the action — no core edits needed. `hooks-server.lua` is a stub for your own
server-side additions.