> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/multi-framework/ak47_garage/exports/server.md).

# Server

### `GetPlayerVehicles`

Retrieves all player-owned vehicles for a given player server ID, formatted with real-time status and calculated parking fees.

```lua
local vehicles = exports['ak47_garage']:GetPlayerVehicles(source)
```

#### Parameters

| Parameter | Type     | Required | Description       |
| --------- | -------- | -------- | ----------------- |
| `source`  | `number` | **Yes**  | Player server ID. |

#### Return Values

| Type    | Description                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `table` | Array of owned vehicle objects from framework database with parsed modifications, location status, parking fees, and real-parking flags. |

#### Example

```lua
RegisterCommand('myvehicles', function(source)
    local vehicles = exports['ak47_garage']:GetVehicles(source)
    for _, v in ipairs(vehicles) do
        print(string.format("Plate: %s | Location: %s | Stored: %s", v.plate, v.garage or "None", tostring(v.stored)))
    end
end, false)
```

***

### `GetVehicleByPlate`

Queries the database directly and retrieves the raw database record for a vehicle plate.

```lua
local vehicle = exports['ak47_garage']:GetVehicleByPlate(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

#### Return Values

| Type         | Description                                  |
| ------------ | -------------------------------------------- |
| `table\|nil` | Vehicle database row, or `nil` if not found. |

***

### `IsVehicleOut`

Checks if a vehicle is currently active and intact in the game world (either as a spawned server entity, in the persistent vehicle cache, or in RealParking).

```lua
local isActive, entity, coords = exports['ak47_garage']:IsVehicleOut(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

#### Return Values

| Return     | Type           | Description                                                    |
| ---------- | -------------- | -------------------------------------------------------------- |
| `isActive` | `boolean`      | `true` if vehicle exists and has health > 0 in the world.      |
| `entity`   | `number\|nil`  | Server entity handle if active entity exists, otherwise `nil`. |
| `coords`   | `vector3\|nil` | World coordinates of the vehicle if active.                    |

#### Example

```lua
local isOut, entity, coords = exports['ak47_garage']:IsVehicleOut("AK47")
if isOut then
    print("Vehicle is currently out at coordinates:", coords)
else
    print("Vehicle is parked or impounded.")
end
```

***

### `GetVehicleLocation`

Retrieves world coordinates and entity handle for an active, real-parked, or persistent vehicle.

```lua
local coords, entity = exports['ak47_garage']:GetVehicleLocation(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

#### Return Values

| Return   | Type           | Description                              |
| -------- | -------------- | ---------------------------------------- |
| `coords` | `vector3\|nil` | Vehicle position in the world, or `nil`. |
| `entity` | `number\|nil`  | Server entity handle if entity exists.   |

***

### `TransferVehicle`

Transfers a vehicle to another garage location and deducts the destination garage's transfer fee from the player's bank account.

```lua
local success = exports['ak47_garage']:TransferVehicle(source, plate, gid)
```

#### Parameters

| Parameter | Type     | Required | Description               |
| --------- | -------- | -------- | ------------------------- |
| `source`  | `number` | **Yes**  | Player server ID.         |
| `plate`   | `string` | **Yes**  | Vehicle license plate.    |
| `gid`     | `string` | **Yes**  | Target garage identifier. |

#### Return Values

| Type      | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| `boolean` | `true` if transfer succeeded, `false` if player lacked funds or vehicle was invalid. |

***

### `TransferOwnership`

Transfers permanent ownership of a vehicle from one player to another. Validates ownership, checks blacklisted models/categories/plates, updates the database, removes keys, and sends Discord webhook audit logs.

```lua
local success, message = exports['ak47_garage']:TransferOwnership(source, targetSource, plate)
```

#### Parameters

| Parameter      | Type     | Required | Description                          |
| -------------- | -------- | -------- | ------------------------------------ |
| `source`       | `number` | **Yes**  | Server ID of current owner (sender). |
| `targetSource` | `number` | **Yes**  | Server ID of new owner (receiver).   |
| `plate`        | `string` | **Yes**  | Vehicle license plate.               |

#### Return Values

| Return    | Type      | Description                                         |
| --------- | --------- | --------------------------------------------------- |
| `success` | `boolean` | `true` if ownership transferred, `false` otherwise. |
| `message` | `string`  | Localized status or error response message.         |

#### Example

```lua
local success, msg = exports['ak47_garage']:TransferOwnership(source, targetId, "AK47")
if success then
    print("Ownership transferred:", msg)
else
    print("Transfer failed:", msg)
end
```

***

### `PayGarageFee`

Deducts the accumulated time-based parking fee for a stored vehicle from the owner's bank account and resets the timer in database.

```lua
local success = exports['ak47_garage']:PayGarageFee(source, plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `source`  | `number` | **Yes**  | Player server ID.      |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

#### Return Values

| Type      | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `boolean` | `true` if payment succeeded or not required, `false` if insufficient funds. |

***

### `SetVehicleStoredState`

Updates the stored state of a vehicle in the framework database, clears persistence caches, deletes active server entities, and cleans up RealParking dummies.

```lua
local success = exports['ak47_garage']:SetVehicleStoredState(plate, state, garageId, poundFee)
```

#### Parameters

| Parameter  | Type     | Required | Description                                                           |
| ---------- | -------- | -------- | --------------------------------------------------------------------- |
| `plate`    | `string` | **Yes**  | Vehicle license plate.                                                |
| `state`    | `number` | **Yes**  | `0` = Out in world, `1` = Stored in garage, `2` = Impounded / Seized. |
| `garageId` | `string` | No       | Optional target garage ID.                                            |
| `poundFee` | `number` | No       | Optional impound fee (QBCore / QBX).                                  |

#### Return Values

| Type      | Description                     |
| --------- | ------------------------------- |
| `boolean` | `true` if updated successfully. |

#### Example

```lua
-- Move vehicle to impound lot
exports['ak47_garage']:SetVehicleStoredState("AK47", 2, "Impound", 500)
```

***

### `ParkVehicleServer`

Programmatically stores a vehicle into a garage, deletes any active world entity, removes persistence records, and updates vehicle modifications in the database.

```lua
local success = exports['ak47_garage']:ParkVehicleServer(plate, garageId, vehicleProps)
```

#### Parameters

| Parameter      | Type     | Required | Description                                   |
| -------------- | -------- | -------- | --------------------------------------------- |
| `plate`        | `string` | **Yes**  | Vehicle license plate.                        |
| `garageId`     | `string` | **Yes**  | Destination garage identifier.                |
| `vehicleProps` | `table`  | No       | Optional vehicle modifications table to save. |

#### Return Values

| Type      | Description        |
| --------- | ------------------ |
| `boolean` | `true` on success. |

***

### `ImpoundVehicle`

Programmatically impounds a vehicle into an impound lot, sets stored state to `2`, deletes world entities, and cleans up persistence/dummies.

```lua
local success = exports['ak47_garage']:ImpoundVehicle(plate, impoundGid, fee)
```

#### Parameters

| Parameter    | Type     | Required | Description                                         |
| ------------ | -------- | -------- | --------------------------------------------------- |
| `plate`      | `string` | **Yes**  | Vehicle license plate.                              |
| `impoundGid` | `string` | No       | Target impound garage ID (defaults to `"Impound"`). |
| `fee`        | `number` | No       | Impound fee amount.                                 |

#### Return Values

| Type      | Description        |
| --------- | ------------------ |
| `boolean` | `true` on success. |

***

### `GetAllGarages`

Returns the complete internal master table of all registered garages.

```lua
local garages = exports['ak47_garage']:GetAllGarages()
```

#### Return Values

| Type    | Description                       |
| ------- | --------------------------------- |
| `table` | Garages table keyed by garage ID. |

***

### `GetGarageById`

Retrieves configuration and runtime settings for a specific garage ID.

```lua
local garage = exports['ak47_garage']:GetGarageById(gid)
```

#### Parameters

| Parameter | Type     | Required | Description        |
| --------- | -------- | -------- | ------------------ |
| `gid`     | `string` | **Yes**  | Garage identifier. |

#### Return Values

| Type         | Description                          |
| ------------ | ------------------------------------ |
| `table\|nil` | Garage object or `nil` if not found. |

***

### `GetVehicleModelStats`

Retrieves pre-calculated performance stats for a vehicle model from server memory cache (`ak47_vehicle_stats`).

```lua
local stats = exports['ak47_garage']:GetVehicleModelStats(modelKey)
```

#### Parameters

| Parameter  | Type             | Required | Description                 |
| ---------- | ---------------- | -------- | --------------------------- |
| `modelKey` | `string\|number` | **Yes**  | Vehicle model name or hash. |

#### Return Values

| Type         | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `table\|nil` | Stats object (`topSpeed`, `acceleration`, `handling`, `braking`, `driveType`, `power`, `weight`, `rarity`) or `nil`. |

***

### `GetPendingRescues`

Retrieves all active pending vehicle rescue operations currently queued on the server.

```lua
local rescues = exports['ak47_garage']:GetPendingRescues()
```

#### Return Values

| Type    | Description                                                                               |
| ------- | ----------------------------------------------------------------------------------------- |
| `table` | Pending rescues table keyed by trimmed vehicle plate (`{plate, owner, garage, endTime}`). |

***

### `ClearRescueTimer`

Cancels and clears an active rescue operation countdown for a vehicle plate.

```lua
exports['ak47_garage']:ClearRescueTimer(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

***

### `SaveVehiclePersistence`

Saves or updates a vehicle's full state into the persistent vehicles database (`ak47_garage_persistent_vehicles`) and memory cache.

```lua
exports['ak47_garage']:SaveVehiclePersistence(plate, coords, mods, health, status, fuel, locked, owner, model)
```

#### Parameters

| Parameter | Type             | Required | Description                                                                                                       |
| --------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `plate`   | `string`         | **Yes**  | Vehicle license plate.                                                                                            |
| `coords`  | `table`          | **Yes**  | Table with `{x, y, z, w}` coordinates and heading.                                                                |
| `mods`    | `table`          | No       | Vehicle modifications table.                                                                                      |
| `health`  | `table`          | No       | Health data (`engineHealth`, `bodyHealth`, `doorStatus`, `tireBurstState`, `windowStatus`).                       |
| `status`  | `table`          | No       | Extended status (`engineOn`, `lightState`, `handbrake`, `roofState`, `dirtLevel`, `radioStation`, `doorslocked`). |
| `fuel`    | `number`         | No       | Fuel level percentage (0 - 100).                                                                                  |
| `locked`  | `number`         | No       | Door lock state (`1` = unlocked, `2` = locked).                                                                   |
| `owner`   | `string`         | No       | Player identifier (auto-detected if omitted).                                                                     |
| `model`   | `number\|string` | No       | Vehicle model hash or name.                                                                                       |

***

### `RemoveVehiclePersistence`

Deletes a vehicle from the persistent cache and database table.

```lua
exports['ak47_garage']:RemoveVehiclePersistence(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

***

### `DeletePersistentVehicle`

Deletes a vehicle from the persistent cache and database table and remove the physical vehicle from game.

```lua
exports['ak47_garage']:DeletePersistentVehicle(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

### `ImpoundPersistentVehicle`

Auto-impounds a persistent vehicle and removing it from world persistence.

```lua
exports['ak47_garage']:ImpoundPersistentVehicle(plate, fee, reason)
```

#### Parameters

| Parameter | Type     | Required | Description                                                            |
| --------- | -------- | -------- | ---------------------------------------------------------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate.                                                 |
| `fee`     | `number` | No       | Optional impound fee amount.                                           |
| `reason`  | `string` | No       | Reason description (e.g., `"Submerged"`, `"Destroyed"`, `"Inactive"`). |

***

### `IsVehiclePersistent`

Checks whether a vehicle is currently tracked in the persistent vehicles memory cache.

```lua
local isPersistent = exports['ak47_garage']:IsVehiclePersistent(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

#### Return Values

| Type      | Description                                     |
| --------- | ----------------------------------------------- |
| `boolean` | `true` if currently tracked, `false` otherwise. |

***

### `GetPersistentVehicles`

Retrieves the entire persistent vehicles cache table.

```lua
local cache = exports['ak47_garage']:GetPersistentVehicles()
```

#### Return Values

| Type    | Description                         |
| ------- | ----------------------------------- |
| `table` | Cache table keyed by vehicle plate. |

***

### `ClearRealParkedVehicle`

Clears RealParking dummy data and database records for a vehicle plate, updating all clients to despawn the visual dummy.

```lua
exports['ak47_garage']:ClearRealParkedVehicle(plate)
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `plate`   | `string` | **Yes**  | Vehicle license plate. |

***

### `ClearGarageRealParking`

Clears all RealParked vehicles inside a specific garage, updating database records and despawning all visual dummies for that garage.

```lua
exports['ak47_garage']:ClearGarageRealParking(gid)
```

#### Parameters

| Parameter | Type     | Required | Description        |
| --------- | -------- | -------- | ------------------ |
| `gid`     | `string` | **Yes**  | Garage identifier. |

***

### `VehiclePlateChanged`

Updates all internal tracking when a vehicle's license plate is changed by an external script (e.g., fake plates, plate changers, DMV). Automatically updates active world entities, persistent vehicle memory caches, database persistence records (`ak47_garage_persistent_vehicles`), RealParking spots, and active pending rescues/transfers, while synchronizing the change across all clients to prevent vehicle duplication.

```lua
local success = exports['ak47_garage']:VehiclePlateChanged(oldPlate, newPlate)
```

#### **Parameters**

| Parameter  | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `oldPlate` | `string` | **Yes**  | Previous vehicle license plate. |
| `newPlate` | `string` | **Yes**  | New vehicle license plate.      |

#### **Return Values**

| Type      | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| `boolean` | `true` if plate transitioned and synchronized successfully, `false` otherwise. |