> For the complete documentation index, see [llms.txt](https://fetchq-store.gitbook.io/fetchq-store-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fetchq-store.gitbook.io/fetchq-store-docs/cargo-jobs-pack-script-custom-props-and-custom-cars-or-qbcore-qbox-and-esx.md).

# Cargo Jobs Pack Script–Custom props & Custom Cars | QBCore, QBOX & ESX

* ## 📦 FetchQ Cargo Job Pack

  A full logistics career for FiveM servers. Players start by delivering packages on a bicycle and work their way up through pickups, flatbed recovery, semi trucks, container hauling, yacht transport and armored cash transports. Everything is managed from one in-game tablet, with real forklift and dock-handler loading mechanics, legal and illegal contracts, police dispatch alerts, parties of up to four players and a 10-level XP progression. Every location, vehicle, reward and requirement is editable in `config.lua`.

  ### 🌟 Overview

  FetchQ Cargo replaces simple "drive from A to B" jobs with a complete cargo career. Players talk to a dock worker at the hub, open the tablet, pick a contract, rent a vehicle and get to work. Heavy jobs need real handling: pallets are loaded with a forklift, containers are lifted by a dock handler, wrecked cars are secured on a flatbed with a lowering ramp and luxury cars are parked onto carrier trailers. Illegal contracts pay double but can alert the police.

  ### ✨ Features

  #### 🖥️ Tablet Interface

  * **Contract Browser**: Choose a job type, see its level requirement, vehicle options, rental price and reward range.
  * **Vehicle Rental**: Each job type has its own vehicles with speed, capacity and rental price shown before you accept.
  * **Progress & Level**: XP bar, current level and unlocked jobs at a glance.
  * **Language Picker**: Players choose their own language in the tablet settings (saved per client).
  * **Open It Your Way**: `/cargo` command or the `F5` key. Both are configurable.

  #### 🚛 Job Types

  | Job                      | Level | Description                                                   |
  | ------------------------ | ----- | ------------------------------------------------------------- |
  | Bicycle                  | 1     | Multi-stop package deliveries                                 |
  | Car                      | 1     | Package deliveries with a van                                 |
  | Motorcycle               | 2     | Multi-stop deliveries with boxes strapped to the bike         |
  | Pickup                   | 3     | Multi-stop deliveries with boxes on the truck bed             |
  | Recovery (Tow)           | 3     | Haul a wrecked car on a flatbed to the shop                   |
  | Truck                    | 4     | Load pallets with a forklift, deliver and unload              |
  | Box Trailer (BigTrailer) | 5     | Heavy box trailer cargo                                       |
  | Container                | 6     | Dock handler loads a container, reverse into the drop-off bay |
  | Large Trailer            | 7     | Oversized trailer transport                                   |
  | Yacht (Tr3)              | 8     | Deliver a yacht on its trailer to the marina                  |
  | Car Carrier (Tr4)        | 9     | Park luxury cars onto a carrier trailer and deliver           |
  | Stockade                 | 10    | Armored cash transport with a security handoff                |

  #### 🏗️ Loading Mechanics

  * **Forklift**: Pick up pallets and crates, load trailers and stockade rear doors, unload onto marked spots.
  * **Dock Handler**: Grab containers and place them on a flatbed trailer.
  * **Flatbed Ramp**: Lower and raise the Gtow ramp (`LEFT SHIFT` / `LEFT CTRL`).
  * **Luxury Car Loading**: Park cars onto the carrier ramp with a prompt.
  * **Drop-Off Bay**: Containers must be reversed into a marked bay.

  #### 🕶️ Legal & Illegal Contracts

  * **Double Pay**: Illegal contracts pay roughly twice as much.
  * **Random Locations**: Each illegal job picks a random delivery point (Stockade, BigTrailer, Tr3), so police cannot camp one spot.
  * **Time Schedule**: Optionally restrict illegal contracts to certain hours, using the real server clock or the in-game clock.
  * **Police Dispatch**: `ps-dispatch` alert after a random delay, only once the driver has left the hub, with the location blurred.

  #### 💰 Stockade Heist Feel

  Scripted security guards, a cash crate, a carrier NPC and a handoff scene at the delivery point.

  #### 👥 Party System

  * Up to 4 players, invite with `/cargo_invite [id]`.
  * Rewards are split equally, the leader gets a bonus (default 10%).
  * Bicycle and motorcycle jobs give every member their own vehicle.
  * Heavy jobs (Truck, BigTrailer, Container, TrailerLarge, Tr3, Tr4) are solo only.

  #### 🧭 Routes & Driving

  * **Smart Multi-Stop Routes**: Stops are clustered near each other and ordered by nearest neighbour. The cluster radius is set per job type.
  * **Autopilot**: Toggle with `H`, three modes (Normal, Aggressive, Very Aggressive). It costs a 30% reward penalty and is disabled on bicycles and motorcycles.

  #### ⚙️ System

  * **No Database**: Player XP is saved to `xp_data.json` inside the resource.
  * **Framework Auto-Detection**: QBCore, Qbox or ESX.
  * **Multi-language**: English, German, French, Spanish and Portuguese included.
  * **Custom Models**: Includes a custom Gtow flatbed tow truck plus barrel, pallet and wrapped pallet props.
  * **Mission Cleanup**: Every mission entity is tracked and deleted when a job ends, fails or the resource stops.

  ### 📦 Requirements

  * `qb-core`, `qbx_core` or `es_extended`
  * `ps-dispatch` (optional, for police alerts on illegal contracts)
  * `ox_lib` (optional, used for Qbox notifications)

  ### 🚀 Installation & Configuration

  #### 1. Resource Setup

  Put the resource folder in your `resources` directory and start it after your framework.

  <pre class="language-cfg" data-title="server.cfg"><code class="lang-cfg">ensure qb-core
  ensure ps-dispatch
  ensure fetchq-cargo
  </code></pre>

  #### 2. Database Setup

  No database is needed. Player XP is stored by the server in `xp_data.json` inside the resource folder, keyed by citizen id or identifier.

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Make sure the server can write to <code>xp_data.json</code>, and keep the file when updating the resource so player progress is not lost.</p></div>

  #### 3. Items

  No inventory items are required. Rewards are paid out directly through the framework.

  #### 4. Permissions

  No special permissions are needed. Every player can use `/cargo`.

  #### 5. Language

  Texts live in `i18n/<code>.json`.

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.I18n = {
      Language = 'auto',    -- 'auto' or a fixed code: 'en', 'de', 'fr', 'es', 'pt'
      Fallback = 'en',
      PlayerChoice = true,  -- language picker in the tablet settings
  }
  </code></pre>

  With `'auto'` the language comes from `set cargo_language "de"` or the standard `sets locale "de-DE"` in your `server.cfg`.

  **Adding a language:** copy `i18n/en.json` to `i18n/<code>.json`, translate the values (keep keys and placeholders) and add `<code> = 'Name'` to `Config.I18n.Languages`. Missing keys fall back to English.

  #### 6. Starting a Job

  1. Go to the hub (map blip) and press `E` at the dock worker, or press `F5` / type `/cargo`.
  2. Pick a contract and a vehicle, then pay the rental fee.
  3. Follow the markers and GPS. Use `/helpcargo` for a guide of the current job.
  4. Finish the delivery to receive your reward and XP.

  #### 7. Keys & Commands

  | Command              | Description                                          |
  | -------------------- | ---------------------------------------------------- |
  | `/cargo`             | Open the cargo tablet (name set in `Config.Command`) |
  | `/helpcargo`         | Show the guide for the current job                   |
  | `/togglecargohud`    | Show or hide the job HUD                             |
  | `/cargo_invite [id]` | Invite a player to your party                        |

  | Key                        | Action                               |
  | -------------------------- | ------------------------------------ |
  | `F5`                       | Open the tablet (`Config.OpenKey`)   |
  | `E`                        | Interact with props, cargo, trailers |
  | `H`                        | Toggle autopilot                     |
  | `B`                        | Toggle job HUD                       |
  | `LEFT SHIFT` / `LEFT CTRL` | Lower / raise the flatbed ramp       |

  ### 🛠️ Customization (config.lua)

  | Setting                                            | Purpose                                                  |
  | -------------------------------------------------- | -------------------------------------------------------- |
  | `Config.Framework`                                 | `auto`, `qb`, `qbox` or `esx`                            |
  | `Config.Levels`                                    | XP needed for each of the 10 levels                      |
  | `Config.LevelRequirements`                         | Level needed for each job type                           |
  | `Config.StartLocation`                             | Hub position, NPC model and blip                         |
  | `Config.Interaction`                               | Prompt style (`auto`, `qb`, `esx`) and distance          |
  | `Config.LoadingDistances`                          | Every `E` prompt distance for forklifts, handlers, ramps |
  | `Config.TowRamp`                                   | Ramp keys, door index and on-foot distance               |
  | `Config.TruckMission` ... `Config.StockadeMission` | Spawn, parking and delivery coordinates per mission      |
  | `Config.Dispatch`                                  | Police alert resource, code, chance, delay and blur      |
  | `Config.IllegalSchedule`                           | Hours when illegal contracts are closed                  |
  | `Config.IllegalLocations`                          | Random delivery points for illegal contracts             |
  | `Config.RouteClustering`                           | Multi-stop route radius per job type                     |
  | `Config.Autopilot`                                 | Key, penalty and driving modes                           |
  | `Config.Vehicles`                                  | Models, labels, capacity and rental prices               |
  | `Config.Rewards`                                   | Min, max and per-stop rewards (legal and illegal)        |
  | `Config.DeliveryLocations`                         | Delivery points per job type                             |
  | `Config.MissionCounts`                             | Number of stops per job type                             |
  | `Config.Party`                                     | Party size, split, leader bonus, solo-only jobs          |
  | `Config.TrailerPenalty`                            | Fee for finishing a heavy job without the trailer        |
  | `Config.UI`                                        | Accent colour and marker alpha                           |

  #### Level Requirements

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.LevelRequirements = {
      Bicycle = 1, Car = 1, Motorcycle = 2, Pickup = 3, Tow = 3, Truck = 4,
      BigTrailer = 5, Container = 6, TrailerLarge = 7, Tr3 = 8, Tr4 = 9, Stockade = 10
  }
  </code></pre>

  #### Vehicles & Rental Prices

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.Vehicles = {
      Car   = { {model = 'speedo', label = 'Speedo Custom', speed = 'Fast', capacity = 4, rental = 750} },
      Truck = { {model = 'hauler', label = 'Hauler', speed = 'Slow', capacity = 20, rental = 1000} },
  }
  </code></pre>

  #### Rewards

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.Rewards = {
      Legal   = { Truck = {min = 800,  max = 2000, perStop = 350} },
      Illegal = { Truck = {min = 1600, max = 4000, perStop = 700} },
  }
  </code></pre>

  #### Dispatch

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.Dispatch = {
      Enabled = true,
      Resource = 'ps-dispatch',
      IllegalAlertChance = 100,
      Code = '10-45',
      Message = 'Suspicious cargo transport in progress',
      AlertDelay = {min = 60, max = 180},
      MinDistanceFromHub = 300.0,
      LocationBlur = 120.0,
  }
  </code></pre>

  #### Illegal Schedule

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.IllegalSchedule = {
      Enabled = true,
      TimeSource = 'real',                    -- 'real' = server clock, 'game' = in-game clock
      ClosedHours = { {from = 8, to = 18} },  -- closed 08:00-17:59, ranges may wrap midnight
  }
  </code></pre>

  #### Party

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.Party = {
      Enabled = true,
      MaxSize = 4,
      InviteDistance = 10.0,
      InviteTimeout = 30,
      RewardSplit = 'equal',
      LeaderBonusPercent = 10,
  }
  </code></pre>

  #### Custom Vehicles

  Install the vehicle as a separate resource, `ensure` it before this one, then use its spawn name in `Config.Vehicles`.

  <pre class="language-lua" data-title="config.lua"><code class="lang-lua">Config.Vehicles = {
      Truck = { {model = 'peterbilt337', label = 'Peterbilt 337', speed = 'Medium', capacity = 20, rental = 1500} },
  }
  </code></pre>

  ### 🎯 Mission Notes

  * **Truck / Box Trailer**: Load the pallets with the forklift at the hub, drive to the destination, press `E` in the truck to start unloading, then set the cargo down on the marked spots.
  * **Recovery (Tow)**: The wrecked car is already on the flatbed. Drive the tow truck to the shop.
  * **Container**: Reverse the trailer into the drop-off bay to release the container.
  * **Yacht / Luxury Carrier**: The trailer itself is delivered, there is no forklift unloading.
  * Every job fails when the mission vehicle (truck, trailer, forklift or transported car) is destroyed.

  ### ❓ Troubleshooting

  **Vehicles are not spawning.** Check that `Config.VehicleSpawn` and `Config.TrailerSpawn` are valid for your server and not blocked by other vehicles or map objects. `Config.SpawnCheck` tries nearby offsets automatically.

  **The forklift is not working.** Check the `Config.ForkliftSpawns` coordinates. The forklift is a standard GTA V vehicle.

  **No police alerts on illegal jobs.** Make sure `ps-dispatch` is running and `Config.Dispatch.Resource` matches its folder name. Alerts are sent after a random delay and only once the driver has left the hub.

  **Player XP disappeared.** `xp_data.json` was deleted or is not writable. Keep it when updating.

  **Game crash when restarting the script with a Gtow truck out.** The script deletes every mission entity on stop, but clients can still crash if they see a vehicle whose model is unloading. On live servers, move the `stream/Gtow*` files and `Gtow/*.meta` (with their `data_file` lines) into a separate asset resource and `ensure` it first. `Gtow.ytd` is also large (about 90 MB in memory), so halving its textures is recommended.

  **How does the party system work?** The leader starts a mission from `/cargo` and invites players. Max 4 players, rewards are split equally plus a leader bonus.

  ### 🚛 Recommended Vehicle Mods (not included)

  Third-party assets, all credit goes to their authors. Install them as separate resources.

  | Mod                  | Author                     | Link                                                                             |
  | -------------------- | -------------------------- | -------------------------------------------------------------------------------- |
  | Peterbilt 337 Tuning | \[MFD] MAOAM & SFT\_Weizen | [Download](https://www.gta5-mods.com/vehicles/peterbilt-337-tuning-by-mfd-fivem) |

  ### 📄 License

  This script is proprietary. Do not redistribute, resell or modify without permission. Recommended mods listed above belong to their respective authors.