The Job Panel#
Everything starts at the dispatcher in the truck yard — the Truck Yard blip, with a floating marker over the dispatcher's head. Press E beside them, or use your target, and the camera cuts to a close-up of the dispatcher while the panel opens beside it. Anybody can open the panel; taking a contract is what needs the job.
Part | What it shows |
|---|---|
Driver card | Your level, the experience bar to the next one, what you are paid per 100 metres at your level, and your chance of being reported on a stolen-cargo run. |
Contracts | One card per contract: picture, description, the level it needs, the kind of load it hands out (Preloaded or By hand), the stolen-cargo chance, and the pay and experience per 100 metres at your level. |
Your rig | Every truck, with locked ones dimmed and the level they need, so a driver can see what the next levels unlock. |
Footer | Start route — or Abandon route while you are on one — plus Statistics, Shop and Guide. A button whose feature is switched off in the config is hidden. |
The rates on the cards are a preview worked out from your level. When the run starts the server works out the real figures from the same configuration, and the tracker shows exactly what the run will pay.
A Run, Step by Step#
The route tracker in the corner lists the steps your run actually has, with the pay and the experience, and ticks each one off as the server confirms it. Every objective has a GPS blip and a coloured ring on the ground showing exactly where to stop.
Take the truck
Pick a contract and a rig and press Start route. The screen fades and you are in the cab at the yard, in the trucker outfit and with the keys. If every spawn slot is blocked by a vehicle the run is refused with Parking lot is full, and nothing is booked.
Hitch the trailer
The GPS points at one of the trailer bays at the port, marked with an amber ring. Reverse onto the trailer: coupling is the trigger, there is no key to press. This is where you find out what kind of load you drew.
Load it — hand-loaded runs
The GPS leads to four loading docks in turn, each marked with a purple ring. At each one, park the trailer beside the boxes, get out and press
Eto load them by hand — see Hand-Loading below.Deliver
Drive to the drop-off on the GPS (a blue ring). If stolen cargo turned up, the offer appears as you set off. A preloaded trailer is handed over here with
E— you can unhitch and reverse it into place on its own, it still counts.Unload and return the trailer — hand-loaded runs
Pulling up at the drop-off opens the unloading stage by itself. Take every box off, then drive the empty trailer back to the bay it came from and press
Ethere to drop it off.Hand the truck back
Drive back to the yard (a green ring) and press
E. The server checks you are really there, pays the run, grants the experience and hands over the manifests if they are switched on.
Contracts#
Contracts are the cards on the panel, listed in Config.Routes. Two ship with the job, and each one is a different kind of work rather than the same drive at another rate:
Contract | Level | Load | Pay · XP | Stolen cargo |
|---|---|---|---|---|
Standard Freight | 1 | Preloaded | ×1.00 · ×1.00 | 10% |
Hand-Loaded Freight | 1 | By hand | ×1.35 · ×1.25 | 25% |
Both start at level 1 so the difference shows from the first shift; raise levelRequired to keep the harder work for later. Add as many contracts as you like:
{
routeOrder = 2, -- a unique number per contract
name = "Hand-Loaded Freight",
img = 'trucker2.png', -- a shipped picture, or an https:// address
description = "An empty trailer and a run of loading docks...",
levelRequired = 1,
moneyMultiplier = 1.35, -- multiplies the pay
experienceMultiplier = 1.25, -- multiplies the experience
illegalChance = 25, -- % chance of the stolen-cargo offer
cargoModes = { manual = 100 }, -- which kinds of load it hands out
},cargoModes is a weighted pool: { manual = 100 } always hand-loads, { preloaded = 60, manual = 40 } mixes the two. Leave it out and the contract draws from Config.CargoModes instead. A contract without illegalChance uses Config.ChanceToGetIllegalJob.
For img, the shipped pictures are trucker1.png and trucker2.png; for your own artwork use a full https:// address to a png, jpg or webp. A picture that cannot be found falls back to a truck mark, so a typo costs the picture and nothing else.
Rigs#
The trucks a driver picks from, in Config.Vehicles. A bigger rig pays a better rate and is handed more boxes on a hand-loaded run — which pays more again, because freight is paid per box. The level is checked on the server when the run starts, so a locked rig cannot be taken by asking for a different model.
Rig | Level | Pay | Freight it takes |
|---|---|---|---|
Packer | 1 | ×1.00 | Half a load |
Hauler | 8 | ×1.12 | Three quarters |
Phantom | 18 | ×1.25 | A full load |
{
model = 'phantom', -- spawn name
label = 'Phantom',
img = 'phantom.png', -- packer.png, hauler.png, phantom.png, or an https:// address
seats = 2, -- shown as a tag on the card
levelRequired = 18,
moneyMultiplier = 1.25, -- multiplies the pay while driving it
cargoMultiplier = 1.0, -- share of a full load it takes: 0.5 is half
},Kinds of Load#
Every run is one of two kinds, rolled by the server when the run starts from the contract's own pool:
Kind | What happens | Pay · XP |
|---|---|---|
Preloaded | A sealed container is waiting at the bay. Hitch up and drive — the whole job is the road. | ×1.00 · ×1.00 |
Hand-loaded | An empty flatbed and four loading docks. Every box goes on by hand, and comes off the same way at the drop-off. | ×1.20 · ×1.25 |
Config.CargoModes = {
preloaded = { weight = 50, minLevel = 1, payMultiplier = 1.00, xpMultiplier = 1.00 },
manual = { weight = 50, minLevel = 2, payMultiplier = 1.20, xpMultiplier = 1.25 },
}
Config.TrailerModels = { 'docktrailer' } -- preloaded runs: a closed container is right
Config.CargoTrailerModels = { 'trflat' } -- hand-loaded runs: flatbeds onlyWeights are relative, not percentages, and 0 switches a kind off. minLevel only applies to contracts that have no cargoModes pool of their own — both shipped contracts have one, so it does not gate them. Hand-loading trailers have to be flatbeds at roughly the deck height of trflat: the boxes are placed at fixed points on the deck, so a closed body swallows them and a taller deck leaves them floating.
Hand-Loading#
A hand-loaded run collects from four of the docks in Config.ManualCargo.sites, chosen by the server and visited nearest-first from the trailer bay, so the run reads as one route instead of zig-zagging across the port. Each pile is built as you approach its dock, and how many boxes are waiting is rolled per dock — you only find out when you pull up.
Park the trailer within 25 metres of the boxes and get out — boxes are moved on foot.
Walk up to the pile and press
E. The view cuts to a camera high above the trailer and the pile, with a cursor on screen.Point at a box until it lights up, hold the left mouse button, drag it onto the green marker on the deck and let go.
When the pile is empty the view closes and the GPS moves on to the next dock. After the last one, the drive to the drop-off begins.
Input | Does |
|---|---|
Mouse | Point at a box. Stacks come apart from the top down, so only a box with nothing on it can be taken. |
Hold left button | Pick the box up and carry it under the cursor. |
Release | Drop it. Within 2.5 metres of the marker it counts; anywhere else it goes straight back. |
| Leave the view. A box in your hand is put back where it came from. |
Each dock's pile goes onto its own section of the deck — rear, middle, front, then over the fifth wheel — so the trailer fills up in the order it was loaded. Boxes cannot be broken, shot or knocked over, and one that goes missing is put back, so a dock can always be finished.
Rig | Boxes per dock | Boxes per run |
|---|---|---|
Packer | 2 | 8 |
Hauler | 3 | 12 |
Phantom | 4 | 16 |
Those are the shipped figures. minBoxes and maxBoxes set the range rolled at each dock — capped at 27, the room one pile has — and the rig's cargoMultiplier scales the top of it:
Config.ManualCargo = {
minBoxes = 4, -- boxes waiting at a dock, rolled between these two
maxBoxes = 4, -- capped at 27
-- Where the piles wait: four entries minimum, add more for variety.
-- vec3 lays a pile out square with the world; vec4(x, y, z, heading) turns it.
sites = {
vec3(1198.879150, -3104.637451, 6.027100),
vec3(1184.452759, -3105.916504, 6.027100),
vec3(1210.008789, -3101.617676, 5.875488),
vec3(1225.397827, -3103.028564, 6.027100),
},
}Unloading and returning the trailer#
With Config.UnloadAtDelivery = true (the default) a hand-loaded trailer is handed back empty. Pulling up at the drop-off opens the unloading stage on its own: press E at the trailer and the same view runs in reverse — lift each box off the deck and set it on the marker beside the trailer, where the boxes stack into a pile and are cleared away after half a minute. Then drive the empty trailer back to the bay it came from and press E to drop it off. That drive back is part of the distance the run is paid for.
Set it to false and a hand-loaded trailer is simply left at the drop-off with its load, like a preloaded one.
Stolen Cargo#
Every contract has a chance of contraband in the container — its illegalChance, or Config.ChanceToGetIllegalJob. The roll happens on the server when the trailer is hitched, and the offer appears once the trailer is loaded and the drive begins: a dialog showing what the buyer pays and your chance of being reported.
Accept — the GPS is re-pointed to a buyer from
Config.IllegalLocationsand the run becomes an Illegal truck route. Pay and experience are multiplied byConfig.IlegalRouteMultiplier(×2), priced on the same full route, and never lower than the legal run it replaces.Decline — the run carries on to the original customer as if nothing happened.
The police roll happens when the trailer is handed over. If you are reported, the run pays nothing and gives no experience, and Config.DispatchExport is called so your dispatch script can alert the police. If not, the money is paid in black money — see Installation for what that needs on each framework.
Config.IlegalRouteMultiplier = 2.0 -- pay and XP on a stolen-cargo run (spelt with one l)
Config.ChanceToGetIllegalJob = 20 -- % for a contract with no illegalChance of its own
Config.IllegalLocations = { -- where the buyers wait
vec3(1146.474731, -3113.090088, 5.791260),
vec3(-1267.14, -820.18, 17.1),
-- ...
}Pay and Experience#
Every figure is worked out on the server from the config — never from the client. A run is paid for the whole distance it covers plus every box it carries:
pay = (metres / 100 × rate at your level + boxes × CargoPay.money)
× contract.moneyMultiplier × rig.moneyMultiplier × kind.payMultiplier
× IlegalRouteMultiplier on a stolen-cargo run
xp = (metres / 100 × ExperiencePerHundredMeters + boxes × CargoPay.experience)
× contract.experienceMultiplier × kind.xpMultiplier
× IlegalRouteMultiplier on a stolen-cargo runThe metres are the real route: the bay to the drop-off on a preloaded run; the bay, every dock in order, the drop-off and the drive back to the bay on a hand-loaded one. The rig's multiplier raises the pay, not the experience.
Setting | Default | Meaning |
|---|---|---|
| 10 | Pay per 100 m at level 1. |
| 1.02 | +2% on that rate per level. |
| 10 | Experience per 100 m — 1 km is 100 XP. |
| 15 · 6 | Paid per box a hand-loaded run asks for. |
| 2.0 | Pay and experience on a stolen-cargo run. |
| 60 | Where the level bonus to pay and police risk stops growing. |
Example: Standard Freight in a Packer, with a drop-off 3 km from the bay, pays $300 and 300 XP at level 1. The same drive pays $438 at level 20, because the rate per 100 m has grown to $14.57.
A legal payout goes to the driver's cash. When qs-job-management is running it is handed to Job Management instead — see Integrations. If the framework refuses the money, the driver keeps the experience and is told the payment could not be processed.
Levels#
Experience fills a bar to the next level, and levels never end. Each one needs more than the last, and each one raises the pay rate and lowers the police risk until Config.MaxBonusLevel — levelling carries on past it, the bonus does not. Levels also unlock rigs and, if you set them, contracts.
Config.LevelExperience = {
BaseExperience = 1000, -- experience needed at level 1
GrowthFactor = 1.1, -- each level needs 10% more
MoneyPerHundredMeters = 10, -- pay per 100 m at level 1
GrowthFactorMoney = 1.02, -- +2% pay per level
PoliceAlertChance = 20, -- % chance of a report at level 1
GrowthFactorPoliceAlert = 0.99 -- -1% of that chance per level
}
Config.MaxBonusLevel = 60Level | XP to the next level | Pay per 100 m | Police alert chance |
|---|---|---|---|
1 | 1,000 | $10.00 | 20.0% |
8 — Hauler | 1,948 | $11.49 | 18.6% |
18 — Phantom | 5,054 | $14.00 | 16.9% |
30 | 15,863 | $17.76 | 14.9% |
60 and above | 276,801 at 60 | $32.17 | 11.1% |
Leaderboards#
The Statistics button opens three rankings — All-time, Season and Daily — ranked by experience, with each driver's earnings beside it and your own row highlighted. They refresh every Config.UpdateLeaderboard minutes and list the top Config.MaxLeaderboardPlayers drivers.
Ranking | Resets | Prizes for 1st · 2nd · 3rd |
|---|---|---|
Daily | Every day at 00:00 server time | $500 · $350 · $200 |
Season | 00:00 on the first day of every month | $5,000 · $3,500 · $2,000 |
All-time | Never | — |
At each reset the top three are paid in cash and shown as the last winners, beside a countdown to the next reset. A winner who is offline keeps the prize: it is stored and paid the next time they log in. A reset that was due while the server was down runs as soon as it starts again.
Config.EnableLeaderboard = true -- false hides the Statistics button
Config.UpdateLeaderboard = 1 -- minutes between refreshes
Config.MaxLeaderboardPlayers = 100 -- drivers per tab
Config.LeaderBoardRewards = {
Daily = { [1] = 500, [2] = 350, [3] = 200 },
Season = { [1] = 5000, [2] = 3500, [3] = 2000 },
}
-- The name a row shows: 'character', 'cfx' (the FiveM name) or 'both'.
-- An offline driver always falls back to their character name.
Config.PlayerNameSource = 'character'The Shop#
An optional supply store inside the panel, off by default. The Buy tab lists Config.Shop.Buy with filter chips and level locks; the Sell tab lists whatever the player is carrying from Config.Shop.Sell, with a button to sell everything at once.
Config.Shop = {
Enabled = true,
-- category: "documents", "equipment", "supplies", "fuel" or "cargo"
Buy = {
{ item = 'legal_manifest', label = 'Shipping Manifest', description = 'Paperwork for a legal load', price = 25, requiredLevel = 1, category = 'documents' },
{ item = 'illegal_manifest', label = 'Blank Manifest', description = 'Nobody checks what is inside', price = 150, requiredLevel = 5, category = 'documents' },
{ item = 'repairkit', label = 'Repair Kit', description = 'Patch the rig up on the road', price = 500, requiredLevel = 1, category = 'equipment' },
},
-- Bought back, at this price per unit.
Sell = {
{ item = 'legal_manifest', label = 'Shipping Manifest', price = 10 },
{ item = 'illegal_manifest', label = 'Blank Manifest', price = 60 },
},
}
Config.MaxShopPurchase = 100 -- most of one item in a single purchaseThe panel only sends item names and amounts: prices and level locks are checked again on the server. Purchases are paid in cash, the whole basket is priced before anything is charged, and a line the inventory cannot take is not charged for. Every item has to exist in your inventory — see Installation.
With Config.Items.receiveItem = true, every paid run hands the driver a legal_manifest, and a stolen-cargo run an illegal_manifest as well. The shop buys them back, so the paperwork sells on top of the run.
The Guide#
The Guide button opens the Driver's Handbook: a walkthrough of a run, a list of tips, and a card for each kind of load with its pay and experience bonus. Its text is the GUIDE_ keys in config/translations.lua — up to ten steps (GUIDE_STEP_1 to GUIDE_STEP_10) and ten tips (GUIDE_TIP_1 to GUIDE_TIP_10). Add or remove keys and the guide follows.
Show on map drops a blip on every delivery point so a new driver can see the network at a glance. Config.EnableGuide = false hides the button, Config.GuideShowBlips = false hides the map option, and Config.GuideBlip sets the blip's look.
The World#
Every place a run uses is a coordinate in config/config.lua. The server picks one trailer bay and one drop-off at random per run and pays by the distance between them, so spreading these across the map is what creates long, well-paid runs.
Setting | What it is |
|---|---|
| The dispatcher: position with heading, and ped model. The only NPC, and the only way into the panel. |
| Where the truck appears. Add slots so several drivers can start at once — a run is refused while every slot is blocked. |
| Where the truck is handed back and the run is paid. |
| The trailer bays, with heading. Thirteen at the port by default. |
| The legal drop-offs. Thirteen across the map by default. |
| Where the stolen-cargo buyers wait. Five by default. |
| The loading docks for hand-loaded runs. Four or more. |
And how it all looks and feels:
Setting | What it does |
|---|---|
| The truck yard blip — shown to players who can take a contract. |
| The GPS blip on the current objective. |
| The ring on the ground at each objective — Trailer amber, Delivery blue, Depot green, Cargo purple, CargoDrop green inside the loading view — each with its own size, colour and height. Drawn within |
| The floating cone over the dispatcher: shape, size, colour, height, bob and range. |
| The name and line on the dispatcher's card. Empty hides them. |
| Put the driver straight in the cab, behind a fade to black. |
| How close to an objective the prompt appears — 8 m. Keep it above the marker's own radius. |
| The interact control — |
|
|
The Settings#
config/config.lua is laid out in numbered sections. Sections 1, 3, 5, 6 and 7 are what you normally tune; 2, 4, 8 and 9 are content — change the values, keep the structure.
Section | What it holds |
|---|---|
1. General | Framework detection, the job, target, prompts, the dispatcher's card, notifications, currency, the outfit and the manifests. |
2. World | Blips, ground markers, the dispatcher, spawn slots, the depot, trailer models, the spawn fade and fuel. |
3. Trucks | The rigs and their level locks. |
4. Routes | Trailer bays, drop-offs and buyers. |
5. Cargo | The kinds of load, the loading docks and unloading at the drop-off. |
6. Levels | The experience curve, pay scaling, per-box pay, stolen cargo and the contracts. |
7. Shop | What the supply store sells and buys back. |
8. Guide | The handbook and its map blips. |
9. Leaderboard | Refresh rate, size and prizes. |
10. Marker | The marker over the dispatcher. |
11. Debug | Console tracing while you set things up. |
Discord webhooks | Logs for runs, payouts and experience — see Integrations. |
The box model, the spacing of a pile, the deck layout and the loading camera are fixed on purpose: they are measured against each other, so changing one alone would break the fit. The only part of hand-loading you place is the docks.