> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/es/nucleo/cuxial-garages/developers.md).

# Exports y eventos

API pública de Cuxial Garages: exports para llaves, garajes de casa, depósito y limpieza de vehículos.

Da y comprueba llaves de vehículo, abre un garaje de casa, incauta un vehículo o inicia una limpieza desde tus propios recursos. Los recursos escritos para `qbx_vehiclekeys` no necesitan cambios.

{% hint style="info" %}
Los exports de llaves solo existen con `enabled = true` en `data/keys.lua`, y los de limpieza solo con `enabled = true` en `data/carwipe.lua`.
{% endhint %}

## Exports de servidor

### GiveKeys

Da a un jugador la llave de una matrícula. No hace nada si el jugador ya la tiene.

```lua
exports.cuxial_garages:GiveKeys(source, plate)
```

| Parámetro | Tipo   | Descripción                                                                             |
| --------- | ------ | --------------------------------------------------------------------------------------- |
| `source`  | number | Id de servidor del jugador.                                                             |
| `plate`   | string | Matrícula del vehículo. Se ignoran los espacios de los extremos y se pasa a mayúsculas. |

**Devuelve:** `boolean`. `true` cuando el jugador acaba con la llave.

```lua
exports.cuxial_garages:GiveKeys(source, 'ABC12345')
```

### HasKeys

Indica si un jugador lleva la llave de una matrícula.

```lua
local has = exports.cuxial_garages:HasKeys(source, plate)
```

| Parámetro | Tipo   | Descripción                 |
| --------- | ------ | --------------------------- |
| `source`  | number | Id de servidor del jugador. |
| `plate`   | string | Matrícula del vehículo.     |

**Devuelve:** `boolean`.

```lua
if not exports.cuxial_garages:HasKeys(source, plate) then return end
```

### RemoveKeys

Retira del inventario del jugador todas las llaves de esa matrícula.

```lua
exports.cuxial_garages:RemoveKeys(source, plate)
```

| Parámetro | Tipo   | Descripción                 |
| --------- | ------ | --------------------------- |
| `source`  | number | Id de servidor del jugador. |
| `plate`   | string | Matrícula del vehículo.     |

**Devuelve:** `boolean`. `true` cuando se ha retirado al menos una llave.

```lua
exports.cuxial_garages:RemoveKeys(source, plate)
```

### ImpoundStoredVehicle

Envía un vehículo al depósito a partir de su id en la base de datos, sin agente. Pensado para vehículos guardados: no retira un vehículo que esté fuera, en el mundo.

```lua
local result = exports.cuxial_garages:ImpoundStoredVehicle(data)
```

| Parámetro        | Tipo   | Descripción                                                                                 |
| ---------------- | ------ | ------------------------------------------------------------------------------------------- |
| `data.id`        | number | Id del vehículo en la tabla de vehículos. Obligatorio.                                      |
| `data.cost`      | number | Tasa para retirarlo. Por defecto `defaultPrice` de `data/impound.lua`.                      |
| `data.reason`    | string | Motivo que ve el dueño. Hasta 255 caracteres.                                               |
| `data.sentBy`    | string | Nombre que aparece como quien lo incautó. Hasta 100 caracteres.                             |
| `data.job`       | string | Trabajo que queda registrado como origen de la incautación.                                 |
| `data.depot`     | string | Id del depósito que lo retiene. Sin él, el vehículo se puede retirar en cualquier depósito. |
| `data.fromState` | number | Estado en el que debe estar el vehículo. Por defecto guardado (`1`).                        |

**Devuelve:** `table`. Si sale bien, `{ ok = true, cost, depot, depotLabel }`. Si falla, `{ ok = false, reason }`, donde `reason` es `'bad_request'`, `'no_vehicle'` o `'not_stored'`.

```lua
local result = exports.cuxial_garages:ImpoundStoredVehicle({
    id = vehicleId,
    cost = 2500,
    reason = 'Embargado por orden judicial',
    sentBy = 'Departamento de Justicia',
    job = 'police',
})
if result.ok then print('Incautado por $' .. result.cost) end
```

### GetVehicleMdtInfo

Devuelve el apodo y la ficha de incautación de una matrícula. Pensado para tablets policiales.

```lua
local info = exports.cuxial_garages:GetVehicleMdtInfo(plate)
```

| Parámetro | Tipo   | Descripción                         |
| --------- | ------ | ----------------------------------- |
| `plate`   | string | Matrícula de un vehículo con dueño. |

**Devuelve:** `table`, o `nil` cuando la matrícula no tiene dueño.

| Campo      | Tipo          | Descripción                                                                                                                                            |
| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nickname` | string \| nil | Apodo puesto por el dueño.                                                                                                                             |
| `impound`  | table \| nil  | `nil` cuando el vehículo no está incautado. Si lo está: `depot`, `cost`, `reason`, `selfRetrievable`, `sentBy`, `authorizedBy` y `date` (tiempo Unix). |

```lua
local info = exports.cuxial_garages:GetVehicleMdtInfo('ABC12345')
if info and info.impound then
    print(('Incautado por %s: %s'):format(info.impound.sentBy, info.impound.reason or '-'))
end
```

### StartCarWipe

Inicia una limpieza de vehículos tras una cuenta atrás que ven todos los jugadores.

```lua
local ok, message = exports.cuxial_garages:StartCarWipe(seconds)
```

| Parámetro | Tipo   | Descripción                                                                        |
| --------- | ------ | ---------------------------------------------------------------------------------- |
| `seconds` | number | Cuenta atrás en segundos. Opcional; por defecto `countdown` de `data/carwipe.lua`. |

**Devuelve:** `boolean, string`. `false` cuando ya hay una limpieza en curso. El texto es el mensaje a mostrar.

```lua
local ok, message = exports.cuxial_garages:StartCarWipe(90)
print(message)
```

### CancelCarWipe

Cancela la limpieza en curso.

```lua
local ok, message = exports.cuxial_garages:CancelCarWipe()
```

**Devuelve:** `boolean, string`. `false` cuando no hay ninguna limpieza en curso.

### IsWipeInProgress

Indica si hay una cuenta atrás de limpieza en marcha.

```lua
local running = exports.cuxial_garages:IsWipeInProgress()
```

**Devuelve:** `boolean`.

## Exports de cliente

### GiveKeys

Pide al servidor la llave de una matrícula para el jugador local. El servidor solo la concede cuando el jugador es dueño del vehículo o la matrícula no tiene dueño.

```lua
exports.cuxial_garages:GiveKeys(plate, vehicleEntity)
```

| Parámetro       | Tipo   | Descripción                                                                                                                                                                      |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plate`         | string | Matrícula del vehículo.                                                                                                                                                          |
| `vehicleEntity` | number | Handle del vehículo. Opcional. Si se indica, el jugador puede usar ese vehículo al momento, sin esperar al ítem. Úsalo con vehículos que generes tú, como pruebas de conducción. |

```lua
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
exports.cuxial_garages:GiveKeys(GetVehicleNumberPlateText(vehicle), vehicle)
```

### HasKeys

Indica si el jugador local lleva la llave de una matrícula. Consulta al servidor, así que llámalo desde un hilo.

```lua
local has = exports.cuxial_garages:HasKeys(plate)
```

**Devuelve:** `boolean`.

### RemoveKeys

Retira al jugador local la llave de una matrícula.

```lua
exports.cuxial_garages:RemoveKeys(plate)
```

### IsVehicleAccessible

Indica si el jugador local puede usar un vehículo: con su llave, o por las llaves compartidas de su trabajo. Consulta al servidor, así que llámalo desde un hilo.

```lua
local allowed = exports.cuxial_garages:IsVehicleAccessible(vehicle)
```

| Parámetro | Tipo   | Descripción          |
| --------- | ------ | -------------------- |
| `vehicle` | number | Handle del vehículo. |

**Devuelve:** `boolean`.

```lua
if not exports.cuxial_garages:IsVehicleAccessible(cache.vehicle) then return end
```

### OpenGarage

Abre un garaje de casa en una posición que da tu recurso de propiedades. El garaje no se guarda en la base de datos ni dibuja marcador: tu recurso gestiona el punto de interacción.

```lua
exports.cuxial_garages:OpenGarage(id, opts)
```

| Parámetro       | Tipo     | Descripción                                                                                     |
| --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `id`            | string   | Id único del garaje, hasta 64 caracteres. Los vehículos guardados ahí quedan ligados a este id. |
| `opts.coords`   | vector4  | Posición de acceso, que también se usa como plaza cuando no se dan `spawns`. Obligatorio.       |
| `opts.category` | string   | `'car'`, `'motorcycle'`, `'air'` o `'sea'`. Opcional; por defecto todas las categorías.         |
| `opts.label`    | string   | Nombre que se ve en la interfaz. Opcional, hasta 48 caracteres.                                 |
| `opts.capacity` | number   | Vehículos por jugador, de 1 a 100. Opcional. Solo se aplica con `capacity.enabled = true`.      |
| `opts.spawns`   | table\[] | Plazas como `{ x, y, z, h }`. Opcional, hasta 16, cada una a menos de 30 metros de `coords`.    |

```lua
exports.cuxial_garages:OpenGarage('house:' .. property.id, {
    coords = vector4(x, y, z, heading),
    category = 'car',
    label = 'Garaje de casa',
    capacity = 4,
})
```

### StoreVehicle

Guarda en un garaje de casa el vehículo que conduce el jugador local. No hace nada si el jugador no es el conductor.

```lua
exports.cuxial_garages:StoreVehicle(id, opts)
```

| Parámetro | Tipo   | Descripción                                                                                 |
| --------- | ------ | ------------------------------------------------------------------------------------------- |
| `id`      | string | Id del garaje, el mismo que se usa con `OpenGarage`.                                        |
| `opts`    | table  | Opcional. Los mismos campos que `OpenGarage`. Sin `coords`, se usa la posición del jugador. |

```lua
exports.cuxial_garages:StoreVehicle('house:' .. property.id, { category = 'car' })
```

{% hint style="warning" %}
`OpenGarage` y `StoreVehicle` solo funcionan con `externalGarages = true` en `shared/config.lua`. El servidor comprueba además que el jugador esté a menos de `interactDistance` (8 metros por defecto) de `coords`, y acepta hasta 25 garajes de casa por jugador y sesión.
{% endhint %}

### OpenImpound

Abre el formulario de incautación del vehículo más cercano al jugador local, igual que `/impound`. El jugador sigue necesitando un trabajo con permiso para incautar.

```lua
exports.cuxial_garages:OpenImpound()
```

## Compatibilidad con qbx\_vehiclekeys

Cuxial Garages responde a estas llamadas con el nombre de `qbx_vehiclekeys`, así que los recursos que las usan siguen funcionando:

| Llamada                                                             | Comportamiento                                                                                              |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `exports.qbx_vehiclekeys:GiveKeys(source, vehicle)`                 | Servidor. `vehicle` es un handle de vehículo o una matrícula.                                               |
| `exports.qbx_vehiclekeys:HasKeys(source, plate)`                    | Servidor. Igual que `HasKeys` de arriba.                                                                    |
| `exports.qbx_vehiclekeys:RemoveKeys(source, plate)`                 | Servidor. Igual que `RemoveKeys` de arriba.                                                                 |
| `lib.callback('qbx_vehiclekeys:server:giveKeys', false, cb, netId)` | Se llama desde el cliente. Concede la llave de ese vehículo cuando el jugador es su dueño o no tiene dueño. |

```lua
exports.qbx_vehiclekeys:GiveKeys(source, vehicle)
```

## State bags

| State bag        | En       | Significado                                                                                                                     |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `vehicleid`      | Vehículo | Id en la base de datos de un vehículo con dueño entregado por un garaje. Los vehículos que no lo tienen cuentan como sin dueño. |
| `doorslockstate` | Vehículo | Estado de bloqueo de puertas que pone el sistema de llaves. Por encima de `1` = cerrado.                                        |
| `ignoreLocks`    | Vehículo | Ponlo a `true` desde tu recurso para dejar un vehículo fuera del sistema de cierre.                                             |
| `rentalcode`     | Vehículo | Código de ticket de un vehículo alquilado.                                                                                      |

```lua
Entity(vehicle).state:set('ignoreLocks', true, true)
```

## Eventos

Cuxial Garages no expone eventos públicos. Usa los exports de arriba.

## Integraciones propias

Tres opciones apuntan a un recurso por su nombre. Para usar tu propio recurso en lugar del de por defecto, debe ofrecer estos exports de servidor:

| Opción                                    | Exports que debe ofrecer tu recurso                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `dispatch.resource` en `data/keys.lua`    | `SendDispatchAlert(data)`                                                                                                       |
| `license.resource` en `data/rental.lua`   | `GetAvailableCards()` devuelve una lista de `{ type, label }`. `GetPlayerLicenses(citizenid)` devuelve una lista de `{ type }`. |
| `finance.resource` en `shared/config.lua` | `getPlayerFinancedVehicles(citizenid)`, `getFinanceByPlate(plate)` y `makeFinancePayment(source, plate)`                        |

El aviso de robo que recibe `SendDispatchAlert`:

```lua
{
    title = 'Robo de vehículo',   -- texto traducido
    type = 'vehicle',
    code = '10-72',
    coords = { x = 0.0, y = 0.0, z = 0.0 },
    vehicle = { plate = 'ABC12345' },
    central = true,
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/es/nucleo/cuxial-garages/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.