# Installation

> Setup guide for ML Vehicle Persistence

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

## Overview

`ml_vehicle_persistence` keeps vehicles in the world where they were parked. Parked vehicles survive owner disconnects and server restarts, respawning in place with their mods, colors, fuel and damage. Saved vehicles are held in memory and streamed into the world only when a player comes close, so a server can hold hundreds of them. On a survival server it can also register the first driver of any unowned vehicle as its permanent owner.

## 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).

Table — Purpose

`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