# Aviation: documentación

> Escuela de vuelo y contratos de piloto en un solo recurso, pagados según lo bien que aterrices.

- URL: https://xexstudio.com/es/docs/aviation
- Versión: 2.0.2
- Ficha del producto: https://xexstudio.com/es/scripts/aviation
Escuela de vuelo y contratos de piloto en un solo recurso. Los jugadores obtienen sus licencias con un examen teórico
y exámenes prácticos, y después vuelan contratos que pagan por distancia y por lo bien que aterrizan. Cada aterrizaje
recibe una puntuación y una calificación, mostradas en un informe de aterrizaje. Los pilotos suben de rango y
desbloquean aeronaves más grandes y mejores contratos. ESX, QBCore y Qbox.

Todo lo que otorga dinero o una licencia se valida en el servidor: genera la aeronave, construye la ruta, comprueba
cada etapa contra la posición y el tiempo reales de la aeronave y calcula cada pago.

## Características

- **Escuela de vuelo:** examen teórico (las preguntas nunca llegan al cliente), examen de helicóptero (vuelo
  estacionario, circuito, aterrizaje en el helipuerto) y examen de avión (circuito y aterrizaje en el aeropuerto).
  Cada examen exige una puntuación mínima de aterrizaje.
- **Cuatro tipos de contrato:** vuelos regulares de pasajeros (ida y vuelta), chárteres VIP, rescate aéreo
  contrarreloj y cargas colgantes con el Cargobob.
- **Puntuación de aterrizaje:** de 0 a 100 y una calificación de S a F, a partir de la velocidad vertical al tocar
  tierra, los rebotes y, en helipuertos, lo cerca del centro que se posa la aeronave. La calificación multiplica el
  pago.
- **Progresión:** XP por cada aterrizaje, horas de vuelo, rangos con una bonificación de pago que desbloquean clases
  de aeronave y tipos de contrato. Libro de vuelo con los últimos vuelos.
- **Tableta Flightpad:** tablón de contratos, escuela y perfil de piloto en una sola interfaz. Nombre de marca y
  color de acento configurables.
- **HUD en vuelo:** etapa actual, distancia, temporizador y, cerca del suelo, altitud, velocidad vertical y
  velocidad.
- **Copiloto:** un jugador en el asiento de copiloto recibe una parte de cada pago.
- **Alquiler con depósito:** los contratos cobran un alquiler y un depósito reembolsable que se devuelve menos los
  daños.
- **Optimizado:** sin hilos mientras nadie vuela; 10 comprobaciones por segundo en vuelo y cada frame solo en la
  aproximación final. Los pasajeros son peds locales: sin coste de red ni de servidor.
- **Modular:** desactiva la escuela o los contratos. Los contratos leen las licencias a través del bridge, así que
  también funcionan con otra escuela.

## 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)

## Instalación

1. Copia `xex_aviation` en tu carpeta de recursos.
2. **Solo ESX:** ejecuta `install/esx.sql` (añade los tres tipos de licencia). Las tablas de pilotos se crean
   automáticamente.
3. Añade a `server.cfg` después de tu framework, ox_lib y oxmysql:
   ```cfg
   ensure xex_aviation
   ```
4. Configura el idioma con `setr ox:locale en` (o `es`).

## Cómo funciona

1. **Escuela de vuelo** (blip en el aeropuerto): el jugador hace el examen teórico y después los exámenes de
   helicóptero y de avión. Cada examen genera su propia aeronave y se califica por el aterrizaje final.
2. **Mostrador de Flight Ops:** muestra un tablón de contratos para ese jugador. Los bloqueados indican qué falta
   (licencia o rango). Al aceptar se cobran el alquiler y el depósito y el jugador aparece dentro de la aeronave.
3. **En vuelo:** el HUD muestra la siguiente etapa. Los pasajeros suben y bajan de la aeronave en las plazas de
   estacionamiento, el herido camina hasta el helicóptero, la carga se engancha y se deposita en la zona de descarga.
4. **Informe de aterrizaje:** tras cada aterrizaje, la puntuación, la calificación y el pago.
5. **Devolución:** entregar la aeronave devuelve el depósito menos los daños y añade el vuelo al libro de vuelo.

La tableta también se abre en cualquier sitio con `/flightpad` (libro de vuelo y licencias). Los contratos y los
exámenes solo empiezan en los mostradores.

## Configuración

| Archivo | Qué contiene |
| --- | --- |
| `config.lua` | Todos los ajustes (tabla siguiente) |
| `data/airfields.lua` | Aeródromos (zona de aterrizaje, puestos, estacionamiento) y helipuertos |
| `data/routes.lua` | Rutas de examen, lugares de rescate y trabajos de carga |
| `questions/<locale>.lua` | Preguntas teóricas (solo servidor) |
| `locales/<locale>.json` | Todos los textos: notificaciones, HUD e interfaz |
| `bridge/server.lua` | Framework, dinero, licencias, trabajos, 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.Accounts` | Cuenta para las tasas de examen, el alquiler y el depósito, y el pago |
| `Config.Licenses` | Nombres de las licencias. Cámbialos para que coincidan con tu sistema de licencias actual |
| `Config.UI` | Nombre de marca, color de acento, comando de la tableta y tecla opcional |
| `Config.Landing` | Límites de velocidad vertical (ideal, duro, accidente) para aviones y helicópteros, penalización por rebote, peso de la precisión en el helipuerto |
| `Config.Grades` | Puntuación necesaria para cada calificación y su multiplicador de pago |
| `Config.Session` | Tiempo permitido fuera de la aeronave, límite de tiempo de vuelo, velocidad máxima plausible, prefijo de matrícula |
| `Config.School` | Ubicación, examen teórico, y precio, aeronave, puntuación mínima, daños y límite de tiempo de cada examen |
| `Config.Jobs` | Mostradores, tamaño y actualización del tablón, contratos por hora, tiempo de espera, tope de pago, parte del copiloto, trabajo requerido |
| `Config.Classes` | Clases de aeronave: modelos, alquiler, depósito y rango necesario |
| `Config.Contracts` | Cada tipo de contrato: activado/desactivado, con qué frecuencia aparece, licencia, rango, clases y pago |
| `Config.Peds` | Modelos de pasajeros, VIP y heridos |
| `Config.Progression` | XP por calificación, XP por examen, rangos con su bonificación de pago, tamaño del libro de vuelo |

### Pago

Cada pago se calcula en el servidor:

```
(base + perKm × route km) × grade multiplier × type bonus × (1 + rank bonus)
```

La bonificación por tipo es la bonificación de tiempo del rescate (hasta un +30 % cuando queda tiempo) o el estado
de la carga (una carga dañada paga menos). Un aterrizaje con accidente paga el 30 % de la tarifa normal.
`Config.Jobs.maxPayout` limita cualquier pago individual.

### Licencias existentes

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

```lua
Config.Licenses = { theory = 'pilot_theory', helicopter = 'helicopter', plane = 'aircraft' }
```

### Añadir aeródromos, puestos y helipuertos

Los administradores pueden ejecutar `/aviationtool point | stand | pad` en el juego. Imprime una línea lista para
pegar en `data/*.lua` y la copia al portapapeles. Cada aeródromo con un `parking` se convierte en destino de
pasajeros, y cada helipuerto incluido en los `helipads` de un mostrador permite que un contrato de helicóptero más
se ejecute al mismo tiempo (lo mismo vale para `stands` y aviones).

### Llaves y combustible

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

## Exports y eventos (servidor)

```lua
exports.xex_aviation:GetPilot(source)        -- { xp, rank, rankName, hours, flights, bestFpm, ... }
exports.xex_aviation:AddXP(source, amount)
exports.xex_aviation:HasPilotLicense(source, 'theory' | 'helicopter' | 'plane')
exports.xex_aviation:IsFlying(source)
```

| Evento (servidor, local) | Argumentos |
| --- | --- |
| `xex_aviation:flightStarted` | `source, { kind, type, route, model }` |
| `xex_aviation:flightCompleted` | `source, { kind, route, grade, score, fpm, payout, duration }` |
| `xex_aviation:licenseGranted` | `source, licenseKey, licenseName` |
| `xex_aviation:suspicious` | `source, reason, details` (p. ej., velocidad imposible entre dos etapas) |

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

## Preguntas frecuentes

**¿Puedo usar solo los contratos con mi propia escuela de vuelo?**
Sí. Establece `Config.School.enabled = false` y pon los nombres de licencia de tu escuela en `Config.Licenses`.

**¿Puedo usar solo la escuela?**
Sí. Establece `Config.Jobs.enabled = false`.

**¿Por qué un contrato dice «todos los puestos están ocupados»?**
Cada puesto o helipuerto admite una aeronave a la vez. Añade más con `/aviationtool stand` o `/aviationtool pad`.

**¿Pueden los jugadores volar su propia aeronave?**
No. Los contratos y los exámenes usan aeronaves generadas por el servidor, para que la ruta y el pago se puedan
comprobar.

**¿Los demás jugadores ven a los pasajeros?**
No. Los pasajeros son locales al piloto, lo que mantiene el servidor y la red libres de peds adicionales.

**¿Cómo cambio desde Pilot Jobs (xex_pilotjob)?**
Aviation lo sustituye. Detén `xex_pilotjob`, inicia `xex_aviation` y establece en `Config.Licenses` los nombres de
licencia que usabas (`LicenseNeeded` / `ExtraLicenseNeeded` en la configuración antigua).
