Aviation

Flight school and pilot contracts in one resource. Players earn their licenses with a theory test and practical exams, then fly contracts that pay by distance and by how well they land. Every landing gets a score and a grade, shown in a landing report. Pilots rank up and unlock bigger aircraft and better contracts. ESX, QBCore and Qbox.

Everything that grants money or a license is validated on the server: it spawns the aircraft, builds the route, checks every stage against the aircraft’s real position and timing, and calculates every payment.

Features

• Flight school: theory test (questions never reach the client), helicopter exam (hover, circuit, landing on the pad) and plane exam (circuit and landing at the airport). Each exam needs a minimum landing score.
• Four contract types: scheduled passenger flights (round trip), VIP charters, air rescue against the clock and Cargobob sling loads.
• Landing score: 0–100 and a grade from S to F, from the vertical speed at touchdown, bounces and, on helipads, how close to the center the aircraft sets down. The grade multiplies the pay.
• Progression: XP for every landing, flight hours, ranks with a pay bonus that unlock aircraft classes and contract types. Logbook with the last flights.
• Flightpad tablet: contracts board, school and pilot profile in one UI. Brand name and accent color configurable.
• In-flight HUD: current stage, distance, timer, and altitude, vertical speed and speed near the ground.
• Co-pilot: a player in the co-pilot seat gets a share of every payment.
• Rental with deposit: contracts charge a rent and a refundable deposit that comes back minus damage.
• Optimized: no threads while nobody is flying; 10 checks per second in flight, every frame only on short final. Passengers are local peds: no network or server cost.
• Modular: turn the school or the contracts off. Contracts read licenses through the bridge, so they also work with another school.

Requirements

• ox_lib and oxmysql
• One framework: ESX (with esx_license), QBCore or Qbox
• OneSync (on by default on current servers)

Install

1. Drop xex_aviation into your resources folder.
2. ESX only: run install/esx.sql (adds the three license types). The pilot tables are created automatically.
3. Add to server.cfg after your framework, ox_lib and oxmysql:

   ensure xex_aviation

4. Set the language with setr ox:locale en (or es).

How it works

1. Flight school (blip at the airport): the player takes the theory test, then the helicopter and plane exams. Each exam spawns its own aircraft and is graded on the final landing.
2. Flight Ops desk: shows a board of contracts for that player. Locked ones say what is missing (license or rank). Accepting charges the rent and the deposit and puts the player in the aircraft.
3. In flight: the HUD shows the next stage. Passengers board and leave the aircraft at the parking spots, the casualty walks to the helicopter, the cargo is hooked and set down in the drop zone.
4. Landing report: after each landing, the score, the grade and the payment.
5. Return: handing the aircraft back returns the deposit minus damage and adds the flight to the logbook.

The tablet also opens anywhere with /flightpad (logbook and licenses). Contracts and exams only start at the desks.

Configure

File	What it contains
config.lua	All settings (table below)
data/airfields.lua	Airfields (landing area, stands, parking) and helipads
data/routes.lua	Exam routes, rescue sites and cargo jobs
questions/<locale>.lua	Theory questions (server only)
locales/<locale>.json	Every text: notifications, HUD and UI
bridge/server.lua	Framework, money, licenses, jobs, vehicle keys, fuel
bridge/client.lua	Client-side fuel resources, notifications

Setting	What it does
Config.Framework	auto, or force esx / qb / qbox
Config.Accounts	Account for exam fees, rent and deposit, and pay
Config.Licenses	License names. Change them to match your existing license system
Config.UI	Brand name, accent color, tablet command and optional key
Config.Landing	Vertical speed limits (ideal, hard, crash) for planes and helicopters, bounce penalty, weight of the helipad accuracy
Config.Grades	Score needed for each grade and its pay multiplier
Config.Session	Time allowed outside the aircraft, flight time limit, maximum plausible speed, plate prefix
Config.School	Location, theory test, and price, aircraft, minimum score, damage and time limit of each exam
Config.Jobs	Desks, board size and refresh, contracts per hour, cooldown, payment cap, co-pilot share, required job
Config.Classes	Aircraft classes: models, rent, deposit and rank needed
Config.Contracts	Each contract type: on/off, how often it appears, license, rank, classes and pay
Config.Peds	Models of passengers, VIPs and casualties
Config.Progression	XP per grade, XP for an exam, ranks with their pay bonus, logbook size

Pay

Every payment is calculated on the server:

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

The type bonus is the rescue time bonus (up to +30% when there is time left) or the cargo condition (a damaged load pays less). A crash landing pays 30% of the normal rate. Config.Jobs.maxPayout caps any single payment.

Existing licenses

If your server already has pilot licenses, put their names in Config.Licenses and players keep them:

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

Adding airfields, stands and helipads

Admins can run /aviationtool point | stand | pad in game. It prints a line ready to paste into data/*.lua and copies it to the clipboard. Every airfield with a parking becomes a passenger destination, and every pad listed in a desk’s helipads lets one more helicopter contract run at the same time (the same goes for stands and planes).

Keys and fuel

bridge/server.lua gives keys with qbx_vehiclekeys or qb-vehiclekeys and sets fuel for ox_fuel. bridge/client.lua covers LegacyFuel, cdn-fuel and ps-fuel. Add your own resource there if it isn’t listed. Notifications go through Bridge.Notify in bridge/client.lua: swap lib.notify there for your own resource.

Exports and events (server)

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)

Event (server, local)	Arguments
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 (e.g. impossible speed between two stages)

Use them for battle passes, logs or your anticheat without editing the resource.

FAQ

Can I use only the contracts with my own flight school? Yes. Set Config.School.enabled = false and put your school’s license names in Config.Licenses.

Can I use only the school? Yes. Set Config.Jobs.enabled = false.

Why does a contract say “every stand is taken”? Each stand or helipad holds one aircraft at a time. Add more with /aviationtool stand or /aviationtool pad.

Can players fly their own aircraft? No. Contracts and exams use aircraft spawned by the server, so the route and the payment can be checked.

Do other players see the passengers? No. Passengers are local to the pilot, which keeps the server and network free of extra peds.

How do I switch from Pilot Jobs (xex_pilotjob)? Aviation replaces it. Stop xex_pilotjob, start xex_aviation and set Config.Licenses to the license names you used (LicenseNeeded / ExtraLicenseNeeded in the old config).