# Boat Licenses: documentación

> Una escuela náutica con examen teórico, examen de moto de agua y examen de embarcación que termina con un atraque puntuado.

- URL: https://xexstudio.com/es/docs/boat-licenses
- Versión: 1.0.0
- Ficha del producto: https://xexstudio.com/es/scripts/boat-licenses
Boat Licenses: una escuela náutica (Marine Academy en el juego) para ESX, QBCore y Qbox. Los jugadores hacen un examen
teórico, después un examen de moto de agua y un examen de embarcación. Los exámenes recorren zonas de velocidad
reducida y un circuito de boyas, y el examen de embarcación termina atracando en un amarre. El atraque recibe una
puntuación y una calificación, mostradas en un informe de atraque.

El servidor lo comprueba todo. Genera la embarcación y comprueba cada boya contra la posición real de la embarcación.
Una vez por segundo mide la velocidad y los daños, y puntúa el atraque a partir de la posición, el rumbo y el estado
de la embarcación. No se concede ninguna licencia sin superar esas comprobaciones.

## Características

- **Examen teórico:** preguntas aleatorias de un banco en inglés y español, corregidas en el servidor (las respuestas
  nunca llegan al cliente). Tasa cobrada al empezar, espera opcional antes de reintentar tras un suspenso.
- **Examen de moto de agua:** moto de agua por la zona de velocidad reducida del puerto y el circuito de boyas, y
  después parar de vuelta en la salida.
- **Examen de embarcación:** el mismo recorrido en una embarcación, y después atracar en el amarre. Puntuación de
  atraque de 0–100 y una calificación de S a F, según lo centrada que esté la embarcación, lo bien que se alinea con
  el amarre (de proa o de popa) y cualquier impacto durante el atraque.
- **Faltas medidas en el servidor:** exceso de velocidad en una zona de velocidad reducida (una falta por infracción,
  con tolerancia) y colisiones. Una falta por encima del límite termina el examen.
- **HUD del examen:** paso actual, distancia, tiempo restante, velocidad en nudos, el límite de velocidad de la zona y
  el contador de faltas. Las zonas de velocidad reducida se dibujan en el mapa durante el examen.
- **Tableta de la academia:** exámenes con su tasa y estado, licencias, mejor puntuación de atraque e historial de
  exámenes. Se abre en cualquier lugar con `/marinepad`. Nombre de marca y color de acento configurables.
- **Instructor en el mostrador:** un NPC con una opción de ox_target / qb-target. Sin recurso de target (o sin el
  NPC) el mostrador es un marker y un aviso `[E]`.
- **Herramienta de administración:** `/marinetool desk | buoy | zone | berth | spawn` imprime una línea lista para
  pegar en `config.lua` o `data/routes.lua`.
- **API:** exports para comprobar, conceder y revocar licencias, y eventos para logs, pases de batalla o anticheats.
- **Optimizado:** no se ejecuta nada mientras nadie está haciendo un examen. Durante un examen el cliente comprueba
  10 veces por segundo y dibuja los markers en cada frame solo cerca de la boya actual. El servidor comprueba una vez
  por segundo, y solo mientras hay un examen en curso.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib) y [oxmysql](https://github.com/overextended/oxmysql)
- Un framework: **ESX** (con `esx_license`), **QBCore** o **Qbox**
- OneSync (activado por defecto en los servidores actuales)
- Opcional: **ox_target** o **qb-target** (sin uno de ellos, el mostrador usa un marker y un aviso `[E]`)

## Instalación

1. Coloca `xex_marine` en tu carpeta de recursos.
2. **Solo ESX:** ejecuta `install/esx.sql` (añade los tres tipos de licencia). La tabla del historial de exámenes se
   crea automáticamente.
3. Añádelo a `server.cfg` después de tu framework, ox_lib y oxmysql:
   ```cfg
   ensure xex_marine
   ```
4. Configura el idioma con `setr ox:locale en` (o `es`).

## Cómo funciona

1. **Marine Academy** (blip en Paleto Cove): habla con el instructor para abrir la tableta. El examen teórico va
   primero.
2. **Exámenes prácticos:** cada examen genera su propia embarcación en el muelle y sienta al jugador en ella. El HUD
   muestra la siguiente boya y el límite de velocidad cuando se está dentro de una zona de velocidad reducida.
3. **Faltas:** superar el límite en una zona de velocidad reducida durante más de un instante, o chocar contra algo,
   añade una falta. Demasiadas faltas, demasiados daños o agotar el tiempo suspenden el examen.
4. **Atraque (examen de embarcación):** detente dentro del amarre y mantente inmóvil durante dos segundos. El servidor
   puntúa el atraque y el informe muestra la calificación.
5. **Licencia:** se concede en el acto cuando se aprueba el examen. Cada intento va al historial de exámenes.
6. **Vuelta al mostrador:** cuando el examen termina (aprobado, suspendido o cancelado) el jugador vuelve al lugar
   donde lo empezó, para que nadie se quede en el agua.

La tasa del examen no se devuelve cuando un examen se suspende o se cancela. Se devuelve si la embarcación no se puede
generar.

## Configuración

| Archivo | Qué contiene |
| --- | --- |
| `config.lua` | Todos los ajustes (tabla siguiente) |
| `data/routes.lua` | Punto de aparición, zonas de velocidad reducida, boyas y final (parada o amarre) de cada examen |
| `questions/<locale>.lua` | Preguntas teóricas (solo servidor) |
| `locales/<locale>.json` | Todos los textos: notificaciones, HUD e interfaz |
| `bridge/server.lua` | Framework, dinero, licencias, llaves de vehículo, combustible |
| `bridge/client.lua` | Recursos de combustible del lado del cliente, notificaciones |

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` | `auto`, o fuerza `esx` / `qb` / `qbox` |
| `Config.Target` | `auto` (ox_target, después qb-target), fuerza uno, o `none` para el marker y el aviso `[E]` |
| `Config.Accounts.school` | Cuenta de la que se cobran las tasas de examen |
| `Config.Licenses` | Nombres de las licencias. Cámbialos para que coincidan con tu sistema de licencias existente |
| `Config.UI` | Nombre de marca, color de acento, comando de la tableta y tecla opcional |
| `Config.School` | Ubicación y orientación, NPC instructor (modelo, animación, distancia de aparición y de aviso), blip, examen teórico (precio, preguntas, respuestas correctas necesarias, espera para reintentar), y para cada examen: activado/desactivado, precio, modelo de embarcación, ruta, faltas permitidas, daños permitidos, límite de tiempo y (embarcación) puntuación mínima de atraque |
| `Config.Faults` | Tolerancia de velocidad en nudos, segundos por encima del límite antes de que cuente, daño que cuenta como colisión |
| `Config.Docking` | Desplazamiento y ángulo que aún puntúan al máximo, ángulo que puntúa 0, peso de la alineación, de proa o de popa, penalización por impacto y umbral de choque, segundos a mantenerse inmóvil |
| `Config.Grades` | Puntuación necesaria para cada calificación |
| `Config.Session` | Tiempo permitido fuera de la embarcación, velocidad máxima plausible, prefijo de matrícula, tamaño del historial |

### Licencias existentes

Si tu servidor ya tiene licencias náuticas, pon sus nombres en `Config.Licenses` y los jugadores las conservan:

```lua
Config.Licenses = { theory = 'theoretical_boat', watercraft = 'jetski', boat = 'practical_boat' }
```

¿Solo quieres un examen práctico? Pon `enabled = false` en el otro en `Config.School.practical`.

### Mover la escuela o añadir rutas

Los administradores pueden ejecutar `/marinetool` en el juego, en el agua o sentados en una embarcación:

| Comando | Imprime |
| --- | --- |
| `/marinetool desk` | Dónde está y hacia dónde mira el instructor (`Config.School.coords`), a partir de tu propia posición |
| `/marinetool spawn` | Dónde aparece la embarcación del examen (posición y orientación) |
| `/marinetool buoy` | Una boya del circuito |
| `/marinetool zone` | Una zona de velocidad reducida centrada aquí |
| `/marinetool berth` | El amarre para el atraque, con el rumbo que debe tener la embarcación |

La línea se imprime en F8 y se copia al portapapeles, lista para pegar en `config.lua` o `data/routes.lua`.

### Llaves y combustible

`bridge/server.lua` entrega las llaves con `qbx_vehiclekeys` o `qb-vehiclekeys` y pone combustible para `ox_fuel`.
`bridge/client.lua` cubre LegacyFuel, cdn-fuel y ps-fuel. Añade ahí tu propio recurso si no está en la lista.
Las notificaciones pasan por `Bridge.Notify` en `bridge/client.lua`: sustituye ahí `lib.notify` por tu propio recurso.

## Para desarrolladores

```lua
-- key = 'theory' | 'watercraft' | 'boat'
exports.xex_marine:HasLicense(source, key)
exports.xex_marine:GrantLicense(source, key)   -- e.g. from a staff command
exports.xex_marine:RevokeLicense(source, key)  -- e.g. after a court ruling or too many fines
exports.xex_marine:IsInExam(source)
```

| Evento (servidor, local) | Argumentos |
| --- | --- |
| `xex_marine:examStarted` | `source, exam` |
| `xex_marine:examFinished` | `source, { exam, passed, reason, score, grade, faults, duration }` |
| `xex_marine:licenseGranted` | `source, licenseKey, licenseName` |
| `xex_marine:suspicious` | `source, reason, details` (p. ej. velocidad imposible entre dos comprobaciones) |

Úsalos para pases de batalla, logs o tu anticheat sin editar el recurso.

## Seguridad

- El servidor genera la embarcación del examen, guarda la ruta y acepta cada boya solo si la embarcación está
  realmente allí y el jugador la está pilotando.
- La velocidad en las zonas de velocidad reducida, las colisiones, el límite de tiempo y el atraque se miden en el
  servidor, no los informa el cliente.
- Una embarcación que se mueve más rápido que `Config.Session.maxSpeed` entre dos comprobaciones termina el examen y
  dispara `xex_marine:suspicious`.
- Las respuestas del examen teórico se quedan en el servidor, y cada examen solo se puede enviar una vez. Cerrar el
  examen a medias consume el intento.
- Las tasas se cobran en el servidor antes de que empiece el examen.

## Preguntas frecuentes

**¿Pueden los jugadores usar su propia embarcación?**
No. Los exámenes usan una embarcación generada por el servidor, para que la ruta, la velocidad y los daños se puedan
comprobar.

**¿Por qué un examen dice que el sitio está ocupado?**
Solo cabe una embarcación de examen a la vez en el punto de aparición. El siguiente jugador puede empezar en cuanto la
embarcación se aleje.

**¿Funciona con mi objeto de licencia o mi documento de identidad?**
Las licencias se guardan a la manera del framework (`esx_license` o metadatos del jugador). Los recursos de documento
de identidad y de concesionario que leen esas licencias las ven. Usa en `Config.Licenses` los nombres de licencia que
esperan.

**¿Puedo traducirlo?**
Copia `locales/en.json` y `questions/en.lua` a tu idioma y configura `setr ox:locale <code>`.
