# Installation

> Setup guide for ML Vehicle Persistence

Category: VEHICLE PERSISTENCE · Source: https://miciomods.it/docs/ml-vehicle-persistence-installation · Last updated: 2026-09-23

## Overview

ml_vehicle_persistence saves eligible parked vehicles with their mods, colors, fuel and damage. Saved records survive disconnects and restarts; the vehicle entity streams in when a player is nearby. With World Vehicles enabled, the first driver can claim an eligible unowned vehicle, subject to exclusions and the parking limit.

## Quick Start

1. Download from [CFX Portal](https://portal.cfx.re)
2. Extract to your `resources` folder as `ml_vehicle_persistence`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_vehicle_persistence
```

> **WARNING:** Load Order
>
> `ml_vehicle_persistence` must start AFTER `ml_bridge`.

## Database

The table is created automatically on first start. Existing installs are patched in place (missing columns are added on boot).

`ml_vehicle_persistence`: Stores each persisted vehicle: plate, owner, model, position, properties, fuel, damage

The SQL is also shipped in `_INSTALL/schema.sql` for manual creation.

## Item Registration

All three items are optional. Register them in your inventory system for the features you enable:

- `vehicle_gps`: Lists the owner's persisted and garaged vehicles and sets a waypoint. Requires `Config.GpsItem`
- `gps_scanner`: Thief tool that locates and rips out a vehicle's GPS. Requires `Config.GpsScanner.enabled`
- `gps_module`: Consumed by the owner to reinstall a removed GPS. Requires `Config.GpsScanner.enabled`

The definitions are in `_INSTALL/items.lua`. Set `Config.GpsItem = false` and `Config.GpsScanner.enabled = false` to skip them entirely.

## Verify

After starting, the console prints the version banner and the load summary:

```lua
[ml_vehicle_persistence] loaded 0 persisted vehicles (0 already in world)
```

> **WARNING:** Server Artifact
>
> The script needs `SetEntityOrphanMode`, otherwise the engine can cull spawned vehicles and they would leave persistence. A red console error on boot means the FXServer artifact is too old.

**Troubleshooting**

- Vehicles not respawning after restart - confirm `Config.PersistThroughRestart = true` and that the database table has rows
- Saved vehicles never appear near the player - raise `Config.SpawnDistance` or lower `Config.ScanInterval`; vehicles only spawn when a player is close
- Claimed vehicles never appear - confirm `Config.WorldVehicles.enabled = true` and that the player sat in the driver seat
- A script vehicle gets saved when it should not - call `exports.ml_vehicle_persistence:DoNotSave(plate)` from the spawning resource
- An admin `/dv` brings the vehicle back - `Config.RespawnOnExternalDelete` is `true`; set it to `false` or route the delete through the hook
- Nothing persists at all - enable `Config.Debug = true` and read the console gate messages. A red `DATABASE WRITE TEST FAILED` on boot means the table does not match