> For the complete documentation index, see [llms.txt](https://duddzy-scripts.gitbook.io/duddzy-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://duddzy-scripts.gitbook.io/duddzy-scripts-docs/scripts/duddzy-jail-3/configuration-overview/vehicle-persistence-config.md).

# Vehicle Persistence Config

Vehicle persistence allows purchased customisations to be saved to the owned vehicle database.

This means players can store and retrieve their vehicle from a garage while keeping the modifications they purchased.

***

### Persistence Config

Persistence is configured in:

```lua
Config.Persistence = {
    enabled = true,

    requireOwnedVehicle = true,

    trimPlate = true,

    database = {
        table = 'owned_vehicles',
        ownerColumn = 'owner',
        plateColumn = 'plate',
        vehicleColumn = 'vehicle'
    }
}
```

***

### Enable or Disable Persistence

Enable persistence:

```lua
Config.Persistence.enabled = true
```

Disable persistence:

```lua
Config.Persistence.enabled = false
```

If persistence is disabled, purchased modifications will apply to the current vehicle entity but will not be saved to the database.

***

### Require Owned Vehicle

```lua
requireOwnedVehicle = true
```

If enabled, players can only open/use DZ Customs with vehicles they own.

This is the recommended public-server setting.

***

### Allow Unowned Vehicles

```lua
requireOwnedVehicle = false
```

If disabled, players can customise any vehicle.

However:

```
Owned vehicles will save to the database.
Unowned vehicles will not be saved.
```

This can be useful for temporary/custom RP vehicles, but may confuse players if they pay for modifications that do not persist.

***

### Plate Trimming

```lua
trimPlate = true
```

This trims spaces before checking and saving vehicle plates.

Recommended:

```lua
trimPlate = true
```

Some garage systems store plates with padded spaces, so this helps avoid ownership mismatches.

***

### Database Settings

Default ESX owned vehicle table:

```lua
database = {
    table = 'owned_vehicles',
    ownerColumn = 'owner',
    plateColumn = 'plate',
    vehicleColumn = 'vehicle'
}
```

These values can be changed for custom garage systems.

***

### Standard ESX Example

Typical ESX structure:

| Column    | Description                     |
| --------- | ------------------------------- |
| `owner`   | Player identifier               |
| `plate`   | Vehicle plate                   |
| `vehicle` | JSON encoded vehicle properties |

Default config:

```lua
database = {
    table = 'owned_vehicles',
    ownerColumn = 'owner',
    plateColumn = 'plate',
    vehicleColumn = 'vehicle'
}
```

***

### How Saving Works

When a player successfully checks out:

```
Payment succeeds
→ Vehicle properties are collected
→ Server checks ownership by plate
→ Server updates owned_vehicles.vehicle
→ Player receives save notification
```

***

### Ownership Check

Ownership is checked server-side using:

```
player identifier
vehicle plate
owned vehicle table
```

If the vehicle is not owned and `requireOwnedVehicle` is enabled, the player cannot use the shop.

If the vehicle is not owned and `requireOwnedVehicle` is disabled, the shop may allow checkout, but no database save will happen.

***

### Garage Compatibility

DZ Customs saves standard ESX vehicle properties using the configured database column.

Your garage system must correctly load and apply saved vehicle properties when retrieving the vehicle.

If your garage does not apply certain properties, those properties may not appear after storing/retrieving.

***

### Add-On Vehicle Support

DZ Customs scans available mod options from the vehicle itself.

Add-on vehicles are supported as long as:

* The vehicle has valid mod data
* The mod kit is set correctly
* The garage saves/restores the vehicle properties correctly
* The vehicle supports the selected modification type

Some add-on vehicles may not have every mod category.

***

### Testing Persistence

Recommended test flow:

```
1. Take out an owned vehicle.
2. Drive into a DZ Customs shop.
3. Purchase a paint, wheel, or performance upgrade.
4. Checkout successfully.
5. Store the vehicle in your garage.
6. Retrieve the vehicle.
7. Confirm the modification is still applied.
```

Also test:

```
Unowned vehicle
Owned add-on vehicle
Vehicle with extras
Vehicle with livery
Vehicle with chameleon paint
Vehicle with tyre smoke
Vehicle with neon underglow
```

***

### Troubleshooting Persistence

#### Vehicle does not save

Check:

```lua
Config.Persistence.enabled = true
```

Make sure `oxmysql` is started.

Check server console for database errors.

***

#### Vehicle says not owned

Check your database settings:

```lua
table = 'owned_vehicles'
ownerColumn = 'owner'
plateColumn = 'plate'
vehicleColumn = 'vehicle'
```

Make sure the vehicle plate in-game matches the plate in the database.

Keep this enabled:

```lua
trimPlate = true
```

***

#### Modifications save but do not apply after garage retrieval

This is usually a garage issue.

Check that your garage correctly applies the saved JSON from the vehicle column.

Some garage scripts do not apply every GTA vehicle property by default.

***

#### Chameleon paint does not save

Make sure the optional chameleon paint resource is installed and started before DZ Customs.

Also make sure your garage applies the saved colour indexes correctly.

***

#### Wheel category or wheel mod does not restore

Make sure your garage saves and applies both:

```
wheel type
wheel mod index
```

Some garage scripts restore wheel mod index but forget wheel type, which can make wheels appear incorrect.