# Weapon Licenses: documentación

> Un examen teórico y un examen de tiro cronometrado para licencias de armas, evaluados en el servidor.

- URL: https://xexstudio.com/es/docs/weapon-licenses
- Versión: 3.1.0
- Ficha del producto: https://xexstudio.com/es/scripts/weapon-licenses
Licencias de armas ganadas como es debido: un examen teórico y un examen cronometrado en el campo de tiro, más un modo de práctica opcional.
ESX, QBCore y Qbox. Todo lo que concede una licencia se valida en el servidor.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib)
- Un framework: **ESX** (con `esx_license`), **QBCore** o **Qbox**
- Opcional: ox_inventory (compatible: el arma del campo de tiro se habilita a través de su rueda de armas)

## Instalación

1. Copia `xex_weaponlicense` en tu carpeta de recursos.
2. **Solo ESX:** ejecuta `install/esx.sql` (añade los dos tipos de licencia).
3. Añade a `server.cfg` después de tu framework y ox_lib:
   ```cfg
   ensure xex_weaponlicense
   ```
4. Configura el idioma de la UI y las notificaciones con `setr ox:locale en` (o `es`).

### ox_inventory

No hay que cambiar nada. El arma del campo de tiro funciona a través del export público `weaponWheel` de ox_inventory, que pausa su
comprobación de "arma no está en el inventario" solo para ese jugador mientras dura el examen o la práctica. **No** añadas el arma del campo
de tiro a `inventory:ignoreweapons`: eso permitiría a cualquiera llevar esa arma sin poseerla.

Si usabas una versión anterior que requería editar ox_inventory, puedes revertir ese cambio.

## Configuración

Todo está en `config.lua`:

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` | `auto`, o fuerza `esx` / `qb` / `qbox` |
| `Config.Key` | Control que abre cada punto (38 = E) |
| `Config.Licenses` | Nombres de las licencias. Cámbialos para que coincidan con tu sistema de licencias actual |
| `Config.RequiredLicense` | Licencia opcional requerida antes del examen teórico (p. ej., un reconocimiento médico) |
| `Config.UI` | Nombre de marca, título, color de acento y enlace opcional a las normas mostrado en el examen |
| `Config.Theory` | Ubicación, precio, número de preguntas y respuestas correctas necesarias |
| `Config.Practical` | Ubicación, precio, arma, munición, dianas, límite de tiempo y cuenta atrás |
| `Config.Practice` | Modo de entrenamiento opcional con su propio precio y ajustes |
| `Config.Range` | Un jugador a la vez o compartido, punto de salida, modelo de diana, posiciones de las dianas, movimiento de las dianas y ritmo anti-cheat |

Las dianas cuelgan del raíl del techo del campo de tiro: bajan girando hasta su sitio, se pliegan al recibir el impacto y la
siguiente baja tras una breve pausa. Las pausas se suman al límite de tiempo, así que `timeLimit` es el tiempo de tiro. Ajusta los
tiempos con `Config.Range.targetMotion`, o ponlo a `false` para que las dianas aparezcan y desaparezcan al instante.

Los textos (indicaciones, notificaciones, UI y nombres de blips) están en `locales/*.json`. El examen teórico solo se cobra cuando el
jugador pulsa Empezar, así que cerrar la introducción es gratis.

Las preguntas están en `questions/<locale>.lua`. Se cargan **solo en el servidor**, así que los jugadores nunca pueden leer las respuestas.

## Actualización desde v2 (ESX)

v2 usaba los nombres de licencia `theoretical_weapons` y `practical_weapons`. Consérvalos para que tus jugadores no pierdan sus
licencias:

```lua
Config.Licenses = {
    theory = 'theoretical_weapons',
    practical = 'practical_weapons',
}
```

En ese caso no necesitas ejecutar `install/esx.sql`. Elimina la carpeta del recurso antiguo antes de añadir v3.

## Para desarrolladores

```lua
-- server
local hasLicense = exports.xex_weaponlicense:HasWeaponLicense(source)
```

`bridge/server.lua` es abierto: adáptalo si usas un framework o sistema de licencias personalizado.

## Seguridad

- El servidor elige las preguntas, evalúa las respuestas y concede la licencia.
- El examen de tiro se inicia, se cobra y se cronometra en el servidor; los resultados demasiado rápidos o demasiado lentos se rechazan.
- Las dianas son objetos locales, así que no hay nada que limpiar y ninguna entidad puede ser eliminada por otros jugadores.
