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

# Configuration

> Detailed explanation of the configuration options for ts-persistence.

The configuration file is located at `shared/config.lua`. This page provides a line-by-line explanation of each setting.

> \[!NOTE]
> Are you looking for **Framework**, **Garage**, or **Keys** settings?
> ts-persistence is fully independent! All bridges (QBCore, ESX, qs-vehiclekeys, qb-garages...) are now handled exclusively by `ts-lib`. You can set them in `ts-lib/shared/config.lua`.

## Bridge Settings

<ResponseField name="Config.Bridge.VehicleDeformation" type="boolean" default="false">
  If set to `true`, the script will sync visual vehicle deformation using the [VehicleDeformation](https://github.com/Kiminaze/VehicleDeformation/) plugin. More info [here](/scripts/persistance/plugins/vehicle-deformation).
</ResponseField>

## Global Settings

<ResponseField name="Config.Global.trailerActive" type="boolean" default="true">
  When enabled, any trailer attached to a vehicle will also be saved and restored when the main vehicle spawns.
</ResponseField>

<ResponseField name="Config.Global.disableTemporaryVehicles" type="boolean" default="false">
  When enabled, all vehicle will be permanent. This means that vehicles will not be deleted after a reboot or script restart.
</ResponseField>

## Client Settings

<ResponseField name="Config.Client.debug" type="boolean" default="true">
  Enables or disables client-side debug prints in the F8 console.
</ResponseField>

<ResponseField name="Config.Client.fuel.Get" type="function">
  Function used to retrieve the current fuel level of a vehicle. By default, it uses the native `GetVehicleFuelLevel`.

  ```lua theme={null}
  Get = function(veh)
      -- return exports['LegacyFuel']:GetFuel(veh) -- Example for legacy fuel
      return GetVehicleFuelLevel(veh) -- Native
  end
  ```
</ResponseField>

<ResponseField name="Config.Client.fuel.set" type="function">
  Function called to apply fuel level to a vehicle. Custom fuel scripts (like LegacyFuel) can be integrated here.

  ```lua theme={null}
  set = function(veh, fuelAmount)
      SetVehicleFuelLevel(veh, fuelAmount)
      -- exports['LegacyFuel']:SetFuel(veh, fuelAmount) -- Example for legacy fuel
  end
  ```
</ResponseField>

<ResponseField name="Config.Client.spawnRadius" type="number" default="200.0">
  The distance (in units) at which a persisted vehicle will start to spawn when a player approaches. If the vehicle was not already spawned.
</ResponseField>

<ResponseField name="Config.Client.spawnTimeout" type="number" default="100">
  The maximum time (in ms) the client will wait for the vehicle entity to exist after the server triggers the spawn. Do not change this value unless you know what you are doing.
</ResponseField>

<ResponseField name="Config.Client.netWorkControlTimeout" type="number" default="100">
  The maximum time (in ms) the client will wait to gain network control of the spawned vehicle before giving up. Do not change this value unless you know what you are doing.
</ResponseField>

<ResponseField name="Config.Client.propsApplyTryCount" type="number" default="1">
  Number of attempts to re-apply vehicle properties (mods, colors) if a mismatch is detected after spawning. Default is 1. Do not change this value unless you know what you are doing.
</ResponseField>

<ResponseField name="Config.Client.setVehicleDoorStatusLocked" type="function">
  Handles local door locking. It receives the raw GTA lock status (1 = unlocked, 2 = locked, etc.). See more at [FiveM Natives](https://docs.fivem.net/natives/?_0xD72CEF2).

  ```lua theme={null}
  setVehicleDoorStatusLocked = function(entity, status)
      if not DoesEntityExist(entity) then return false end
      SetVehicleDoorsLocked(entity, status)
      SetVehicleDoorsLockedForAllPlayers(entity, status ~= 1)
  end
  ```
</ResponseField>

<ResponseField name="Config.Client.DisableSpawning" type="function">
  A function that returns `true` or `false`. If it returns `true`, no vehicles will spawn for that player (useful for Cinematics or certain player states).
</ResponseField>

## Server Settings

<ResponseField name="Config.Server.debug" type="boolean" default="true">
  Enables or disables server-side debug prints in the console.
</ResponseField>

<ResponseField name="Config.Server.getVehicleType" type="function">
  Function used server-side to determine the vehicle type for spawning (e.g. `automobile`, `boat`, `heli`). By default, it relies on the framework bridge: `Bridge.Framework.Server.Functions.GetVehicleType(model)`.
</ResponseField>

<ResponseField name="Config.Server.IsVehicleOwned" type="function">
  Function that checks if a given plate (and optional netId) belongs to an owned vehicle. This is used to decide whether a vehicle should be temporary or permanent. Uses the garage bridge from `ts-lib`.
</ResponseField>

<ResponseField name="Config.Server.afterSpawn" type="function">
  A callback function triggered on the server immediately after a vehicle is created. Useful for custom scripts that need to modify the vehicle after spawning.

  ```lua theme={null}
  afterSpawn = function(veh)
      -- You can add any code here that you want to run after a vehicle is spawned
  end
  ```
</ResponseField>

<ResponseField name="Config.Server.onRessourceStart.loadVehiclesToClients" type="boolean" default="true">
  If `true`, all persisted vehicles are sent to connected clients when the resource starts, so they can be managed by the client-side grid system immediately.
</ResponseField>

<ResponseField name="Config.Server.realTimeDBSync" type="boolean" default="false">
  <Warning>
    **Important Performance Note:**

    * **true**: Saves every change to the database immediately. High data safety but high resource usage.
    * **false**: (Recommended) Syncs data in memory and relies on auto-save intervals. Much better for server performance.
  </Warning>

  Check at for more infos : [Database DB Performance Issues](/scripts/persistance/issues#database-db-performance-issues)
</ResponseField>

<ResponseField name="Config.Server.autoSaveActive" type="boolean" default="true">
  Enables or disables the auto-save feature. When enabled, vehicles are automatically saved to the database at specified intervals.
</ResponseField>

<ResponseField name="Config.Server.autoSaveInterval" type="number" default="5">
  The interval (in minutes) at which vehicles are automatically saved to the database. Only applicable when `Config.Server.autoSaveActive` is `true`.
</ResponseField>

<ResponseField name="Config.Server.timeToDeleteActive" type="boolean" default="true">
  Enables or disables the time-based deletion feature. When enabled, vehicles can be automatically deleted based on their age and type.
</ResponseField>

<ResponseField name="Config.Server.timeToDeleteTemp" type="number" default="2">
  The age (in minutes) at which temporary vehicles are automatically deleted. For example, `120` would be 2 hours. Set to `false` to disable deletion of temporary vehicles. Only applicable when `Config.Server.timeToDeleteActive` is `true`.
</ResponseField>

<ResponseField name="Config.Server.timeToDeletePerm" type="number" default="false">
  The age (in minutes) at which permanent vehicles are automatically deleted. Set to `false` to disable deletion of permanent vehicles. Only applicable when `Config.Server.timeToDeleteActive` is `true`.
</ResponseField>

<ResponseField name="Config.Server.timeToDeleteCheckInterval" type="number" default="5">
  The interval (in minutes) at which the script checks for vehicles that should be deleted. Only applicable when `Config.Server.timeToDeleteActive` is `true`.
</ResponseField>

<ResponseField name="Config.Server.setVehicleOutsideStateOnStart" type="boolean" default="true">
  If `true`, vehicles will be set to the "outside" state when they are spawned by persistence. This ensures they behave correctly in the game world.
</ResponseField>

<ResponseField name="Config.Server.setVehicleDoorStatusLocked" type="function">
  Handles server-side locking and synchronization with key systems (like `qb-vehiclekeys`). It sets the `isLocked` state bag for synchronization and triggers the client bridge event.

  ```lua theme={null}
  setVehicleDoorStatusLocked = function(entity, lockStatus)
      TriggerClientEvent('ts-persistence:client:bridge:SetVehicleDoorStatusLocked', -1, entity, lockStatus)
  end
  ```
</ResponseField>

<ResponseField name="Config.Server.notifyPlayer" type="function">
  A callback function used to display notifications to players. It receives the player's source, a message string, and an optional type (e.g., 'success', 'error').

  ```lua theme={null}
  notifyPlayer = function(source, message, type)
      Bridge.Notify.Server.Functions.Notify(source, message, type or 'success')
  end
  ```
</ResponseField>

<ResponseField name="Config.Server.permissions" type="object">
  Configuration for permission checks for various commands.

  <ResponseField name="reload" type="function">
    Permission check for the `/persistence reload` command. By default, it uses the framework's bridge permission system or falls back to an ACE check.

    ```lua theme={null}
    reload = function(source)
        return TS.Bridge.HasPermission(source, 'admin')
    end
    ```
  </ResponseField>

  <ResponseField name="bringVehicle" type="function">
    Permission check for the `/bringvehicle` command. By default, it uses the framework's bridge permission system or falls back to an ACE check.

    ```lua theme={null}
    bringVehicle = function(source)
        return TS.Bridge.HasPermission(source, 'admin')
    end
    ```
  </ResponseField>

  <ResponseField name="setVehicleTemp" type="function">
    Permission check for the `/setvehicleasTemp` command. By default, it uses the framework's bridge permission system or falls back to an ACE check.

    ```lua theme={null}
    setVehicleTemp = function(source)
        return TS.Bridge.HasPermission(source, 'admin')
    end
    ```
  </ResponseField>
</ResponseField>