> For the complete documentation index, see [llms.txt](https://pepper-scripts.gitbook.io/pepper-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pepper-scripts.gitbook.io/pepper-scripts-docs/jobs/pepper-trucking.md).

# Pepper Trucking

<figure><img src="https://content.gitbook.com/content/2wrlmY2LsiAJf6u7YGfs/blobs/joR7PYcl87SDANJVvTl6/.gitbook/assets/trucking-cover.png" alt="Pepper Trucking"><figcaption></figcaption></figure>

Trucking as a real profession: with **Pepper Trucking** the freight exchange offers jobs matching your truck and skills – from parcels in a box van to transformers on a heavy-haul trailer. Couple trailers, protect the cargo, deliver on time, park precisely. As you climb the ranks you buy your own trucks, upgrade them in the workshop, drive in convoys and build a logistics company with depots and AI drivers that earn money even while you are offline.

{% hint style="info" %}
🧪 **Tested on our dev server:** Of course we test all scripts continuously on our own dev server “Pepper Scripts”.
{% endhint %}

{% hint style="success" %}
**Get Pepper Trucking:** [pepper-scripts.tebex.store](https://pepper-scripts.tebex.store/)
{% endhint %}

### Features

* **Freight exchange** with 24 cargo types – hazmat, refrigerated, heavy haul, urgent jobs and multi-drop tours
* **Real trailers** – couple, drop off and park precisely with a parking assistant and bonus
* **Skill tree** with 8 skills – hazmat, long haul, fragile cargo, heavy haul, eco driving and more
* **Own trucks** with garage, wear and workshop – upgrades, paint jobs, repairs, resale
* Cargo damage, cold chain and deadlines – careful, punctual driving pays off
* Weigh stations with special permits and fuel with gas stations (or your fuel script)
* **Convoys** for up to 4 drivers with shared jobs and a convoy bonus
* **Logistics company** with staff, fleet, depots and **AI drivers** running jobs passively
* Career with 50 levels, reputation, 1–5 star rating, daily and weekly challenges
* In-game **freight location editor** and admin panel with offline editing and audit log
* Server-side payouts, protection against double payouts, teleports and implausible runs
* German & English, config and locales open

### At a glance

|                  |                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| **Version**      | 1.0.0                                                                                                         |
| **Framework**    | ESX Legacy 1.9+                                                                                               |
| **OneSync**      | required                                                                                                      |
| **Dependencies** | [es\_extended](https://github.com/esx-framework/esx_core), [oxmysql](https://github.com/overextended/oxmysql) |
| **Optional**     | LegacyFuel, ox\_fuel or cdn-fuel                                                                              |
| **Not required** | ox\_lib, ox\_target, ox\_inventory                                                                            |
| **Performance**  | approx. 0.02 ms idle / 0.15 ms on duty (guide value)                                                          |
| **Distribution** | Cfx.re Asset Escrow (`config/`, `locales/`, `sql/` open)                                                      |

### Installation

#### Requirements

| Requirement        | Version                                                 |
| ------------------ | ------------------------------------------------------- |
| FiveM server build | 7290+ with **OneSync**                                  |
| Framework          | ESX Legacy 1.9+ (`es_extended`)                         |
| Database           | [oxmysql](https://github.com/overextended/oxmysql)      |
| Optional           | LegacyFuel, ox\_fuel or cdn-fuel (`Config.Fuel.System`) |

ox\_lib, ox\_target and ox\_inventory are **not** required. No ESX job is needed – every player can drive.

#### Steps

{% stepper %}
{% step %}
**Download**

Download `pepper_trucking` from the [Cfx.re Portal → Granted Assets](https://portal.cfx.re/assets/granted-assets).
{% endstep %}

{% step %}
**Copy**

Extract it to `resources/[pepper]/pepper_trucking`.
{% endstep %}

{% step %}
**Database**

Keep `Config.Database.AutoInstall = true` (default) – missing tables are created on first start. Alternatively, import `sql/install.sql` manually. On first start **33 default freight locations** are created (`Config.Database.SeedDefaultLocations`).
{% endstep %}

{% step %}
**server.cfg**

Add the resource after its dependencies:

```cfg
ensure oxmysql
ensure es_extended
ensure pepper_trucking
```

{% endstep %}

{% step %}
**Admin permissions**

Grant admin access (see below).
{% endstep %}

{% step %}
**Check the freight locations**

Visit the default freight locations once and adjust them in the freight location editor if needed.
{% endstep %}

{% step %}
**Start**

Drive to the truck yard (truck icon at the port) and press `E`.
{% endstep %}
{% endstepper %}

#### Admin permissions

ESX group in `Config.Admin.Groups` (default: `admin`, `superadmin`) **or** ACE permission:

```cfg
add_ace group.admin pepper_trucking.admin allow
```

{% hint style="info" %}
Freight locations are stored in the database – `config/locations.lua` is only imported on first start. Updates of the resource never overwrite your locations.
{% endhint %}

#### Fuel script

By default Pepper Trucking uses its own fuel gauge and truck gas stations. If you already use a fuel script, set `Config.Fuel.System` accordingly – see **Configuration**.

### Configuration

All settings are open in `config/`. Restart the resource after changes.

#### Files

| File                    | Content                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `config/config.lua`     | Depots, freight exchange, docking/parking, fuel, weigh stations, payouts, damage, rating, reputation, garage, convoy, company, AI drivers, admin |
| `config/trucks.lua`     | Trucks (class, type, payload, tank, consumption, price, rent, requirements), upgrade tiers, paint colors                                         |
| `config/cargo.lua`      | Cargo types (cargo group, trailer, weight, value, fragility, hazmat, refrigeration, skills)                                                      |
| `config/skills.lua`     | Skill tree (tiers, minimum level, effect)                                                                                                        |
| `config/levels.lua`     | 50 levels, titles, XP per job, level rewards                                                                                                     |
| `config/locations.lua`  | Default freight locations (first start only)                                                                                                     |
| `config/stations.lua`   | Gas stations and weigh stations                                                                                                                  |
| `config/challenges.lua` | Daily and weekly challenges                                                                                                                      |
| `config/server.lua`     | Server-only: optional Discord webhook for logs                                                                                                   |

#### General

| Option                                 | Default  | Description                                               |
| -------------------------------------- | -------- | --------------------------------------------------------- |
| `Config.Locale`                        | `'de'`   | Language: `'de'` or `'en'`                                |
| `Config.Debug`                         | `false`  | Detailed console logs                                     |
| `Config.Currency`                      | `'$'`    | Currency symbol                                           |
| `Config.TimeSource`                    | `'game'` | Time of day for night/urgent jobs: `'game'` or `'server'` |
| `Config.Database.AutoInstall`          | `true`   | Create missing tables on start                            |
| `Config.Database.SeedDefaultLocations` | `true`   | Create default freight locations if none exist            |

#### Depots (`Config.Depots`)

| Depot                          | Price   | AI slots | Fleet slots | Shift start |
| ------------------------------ | ------- | -------- | ----------- | ----------- |
| Port of Los Santos (main yard) | –       | 3        | 6           | yes         |
| Truckstop Route 68             | 450,000 | 3        | 5           | off         |
| Depot Sandy Shores             | 600,000 | 4        | 6           | off         |
| Depot Paleto Bay               | 750,000 | 4        | 6           | off         |

{% hint style="warning" %}
**Secondary depots:** `route68`, `sandy` and `paleto` have approximate coordinates and `AllowShiftStart = false`. They count for the company (AI slots, parking spaces). Shifts can start there once you have checked the coordinates in-game and set `AllowShiftStart = true`.
{% endhint %}

#### Tablet & freight exchange

| Option                                 | Default | Description                                    |
| -------------------------------------- | ------- | ---------------------------------------------- |
| `Config.Tablet.DefaultKey`             | `'F9'`  | Key for the tablet (players can rebind it)     |
| `Config.Freight.BoardSize`             | `8`     | Offers per driver                              |
| `Config.Freight.RefreshMinutes`        | `12`    | The board refreshes automatically              |
| `Config.Freight.ManualRefreshCooldown` | `45`    | Seconds between manual refreshes               |
| `Config.Freight.MinDistance`           | `700.0` | Minimum distance loading → unloading (m)       |
| `Config.Freight.TourChance`            | `0.25`  | Share of multi-drop tours                      |
| `Config.Freight.MaxDrops`              | `3`     | Maximum drops per tour                         |
| `Config.Freight.UrgentChance`          | `0.18`  | Share of urgent jobs (skill required)          |
| `Config.Freight.NightFactor`           | `1.10`  | Night surcharge (22–5 h game time)             |
| `Config.Freight.MaxLate`               | `1800`  | Seconds after the deadline until the job fails |
| `Config.Freight.ConvoyPayBonus`        | `0.25`  | Convoy jobs pay +25 %                          |

#### Loading & parking

| Option                       | Default     | Description                                 |
| ---------------------------- | ----------- | ------------------------------------------- |
| `Config.Docking.LoadTime`    | `18`        | Seconds of loading time (rigid truck)       |
| `Config.Docking.UnloadTime`  | `15`        | Seconds of unloading per drop               |
| `Config.Docking.LostTimeout` | `900`       | Seconds without trailer until the job fails |
| `Config.Parking.Perfect`     | 1.6 m / 8°  | +10 % and 60 XP                             |
| `Config.Parking.Good`        | 3.2 m / 18° | +5 % and 30 XP                              |

#### Fuel (`Config.Fuel`)

| Option            | Default      | Description                                                         |
| ----------------- | ------------ | ------------------------------------------------------------------- |
| `System`          | `'internal'` | `'internal'`, `'legacyfuel'`, `'ox_fuel'`, `'cdn-fuel'` or `'none'` |
| `PricePerLiter`   | `2`          | Fuel price                                                          |
| `PaymentAccount`  | `'bank'`     | Account for refueling                                               |
| `PerTonFactor`    | `0.012`      | +1.2 % consumption per ton of cargo                                 |
| `RentalStartFill` | `0.6`        | Rental trucks start with 60 % fuel                                  |

With `'internal'` the built-in fuel gauge and truck gas stations are used. With an external fuel script it handles consumption and refueling – Pepper Trucking only sets the start value when a truck is taken out.

#### Weigh stations (`Config.Weigh`)

| Option                        | Default         | Description                                           |
| ----------------------------- | --------------- | ----------------------------------------------------- |
| `Enabled`                     | `true`          | Weigh stations on/off                                 |
| `LegalLimit`                  | `40`            | Tons – above that a special permit is needed          |
| `CycleMinutes`                | `20`            | Stations open/close in this cycle                     |
| `SkipFineChance`              | `0.5`           | Chance of being checked when skipping an open station |
| `SkipFine` / `OverweightFine` | `1500` / `5000` | Fines                                                 |
| `PermitCostPerTon`            | `60`            | Special permit per ton of cargo                       |

#### Payouts (`Config.Economy`)

| Option                                    | Default         | Description                               |
| ----------------------------------------- | --------------- | ----------------------------------------- |
| `PayAccount`                              | `'bank'`        | `'bank'` or `'money'`                     |
| `GlobalMultiplier`                        | `1.0`           | Multiplies all payouts                    |
| `BasePerKm`                               | `90`            | Per road kilometer                        |
| `PerTonKm`                                | `4.0`           | Per ton and kilometer                     |
| `MinPay`                                  | `300`           | Minimum payout                            |
| `UrgentBonus` / `OnTimeBonus`             | `0.30` / `0.08` | Bonus for urgent jobs / punctual delivery |
| `MaxLatePenalty`                          | `0.5`           | Late deduction max. −50 %                 |
| `RentalFee`                               | `0.15`          | Rental truck: 15 % of the payout as rent  |
| `CancelFee`                               | `250`           | Penalty for cancelling a job              |
| `ConvoyBonusPerMember` / `ConvoyBonusMax` | `0.08` / `0.24` | Convoy bonus per member / maximum         |

#### Garage, convoy & company

| Option                                       | Default     | Description                                                  |
| -------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `Config.Garage.MaxTrucks`                    | `5`         | Own trucks per player                                        |
| `Config.Garage.SellFactor`                   | `0.65`      | Resale value factor (× condition)                            |
| `Config.Garage.TowFee`                       | `750`       | Towing to the main yard when ending a shift far from a depot |
| `Config.Convoy.MaxMembers`                   | `4`         | Drivers per convoy                                           |
| `Config.Company.PurchasePrice`               | `1500000`   | Price of the logistics company                               |
| `Config.Company.RepairPaidBy` / `FuelPaidBy` | `'company'` | Who pays on company runs                                     |
| `Config.Company.DefaultRanks`                | 5 ranks     | Salary, share and permissions per rank                       |

#### AI drivers (`Config.AI`)

| Option           | Default | Description                                                  |
| ---------------- | ------- | ------------------------------------------------------------ |
| `Enabled`        | `true`  | AI drivers on/off                                            |
| `JobMinutes`     | `30`    | Real-time minutes per tour                                   |
| `HireFee`        | `5000`  | Hiring fee                                                   |
| `BaseRevenue`    | `1100`  | Revenue per tour (before factors)                            |
| `FailChance`     | `0.05`  | Chance a tour fails                                          |
| `MinCondition`   | `25`    | Below this truck condition the driver waits for the workshop |
| `MaxCatchUpJobs` | `16`    | Missed tours caught up per driver after a restart            |

#### Admin

| Option                       | Default                   | Description                             |
| ---------------------------- | ------------------------- | --------------------------------------- |
| `Config.Admin.Groups`        | `superadmin`, `admin`     | ESX groups with admin access            |
| `Config.Admin.Ace`           | `'pepper_trucking.admin'` | ACE permission as an alternative        |
| `Config.Admin.RequireReason` | `true`                    | Reason required for changes             |
| `Config.Admin.EditorCommand` | `'truckloc'`              | Command for the freight location editor |
| `Config.Admin.MaxLocations`  | `150`                     | Maximum freight locations               |

### Gameplay

#### A job step by step

{% stepper %}
{% step %}
**Start a shift**

At the terminal of the truck yard (truck icon at the port, press `E`): take a rental truck, your own truck or – as an employee – a company truck. Rental trucks cost 15 % of each payout as rent.
{% endstep %}

{% step %}
**Freight exchange**

Open the tablet (`F9`) and pick a job. The board shows 8 personal offers matching your level, skills and truck. Overweight loads offer a special permit; convoy leaders can share jobs.
{% endstep %}

{% step %}
**Loading**

Stop a rigid truck in the loading bay – back a tractor unit up to the marked trailer, it couples automatically.
{% endstep %}

{% step %}
**Driving**

Watch the deadline, protect the cargo, stop at open weigh stations and refuel in time.
{% endstep %}

{% step %}
**Delivery**

Drop the trailer in the zone (arrow = direction). At the final drop your parking precision counts – the HUD shows a parking assistant.
{% endstep %}

{% step %}
**Payout**

Stars, pay with all bonuses and deductions, XP and reputation – then spend skill points and aim for the next truck.
{% endstep %}
{% endstepper %}

#### Cargo

24 cargo types in 12 cargo groups – e.g. parcels, furniture, electronics, frozen goods, fuel, chemicals, explosives, timber, containers, new cars, construction machinery, transformers and art.

| Special cargo    | What to watch out for                         |
| ---------------- | --------------------------------------------- |
| **Fragile**      | More sensitive to impacts and harsh maneuvers |
| **Hazmat**       | Requires the skill – can be destroyed         |
| **Refrigerated** | Delays and damage spoil the cold chain        |
| **Heavy haul**   | Overweight – special permit at weigh stations |
| **Urgent jobs**  | Tight deadline, higher bonus (skill required) |
| **Tours**        | Up to 3 drops per job                         |

#### Skill tree

One skill point per level. 8 skills: **Hazmat (ADR)**, **Long haul**, **Fragile cargo**, **Heavy haul**, **Urgent jobs**, **Eco driving**, **Valuable cargo** and **Mechanic**. Skills can be reset for a fee.

#### Own trucks & workshop

* 7 trucks from the **Mule** to the **Phantom Custom** – rigid trucks, tractor units and heavy-haul tractors
* Garage with 5 spaces, mileage, condition and wear – damage stays on the truck
* **Workshop:** upgrades (engine, transmission, brakes, turbo, extra tank), paint, service and repair, custom name, sale at residual value

#### Weigh stations & fuel

* 5 weigh stations with changing opening hours. Overweight loads need a special permit; skipping an open station risks a check.
* Consumption depends on distance, weight and the eco skill. Refuel at 25 truck gas stations – or use your own fuel script.

#### Convoy

Up to 4 drivers drive together: shared jobs (each with their own trailer), convoy bonus, convoy jobs with +25 % and map blips of all members. Invitations are accepted with `Y` and declined with `N`.

#### Logistics company

* Freelancers always drive on their own account.
* A player-owned company has staff, ranks, salaries, commission and a company account.
* **Fleet & depots:** buy, service and upgrade company trucks; buy depots for more AI slots, parking spaces and +5 % AI revenue.
* **AI drivers:** hire applicants and assign company trucks – they run tours passively, even when nobody is online, and gain experience. Missed tours are caught up after a restart. If the company account is empty, the AI drivers go on strike.

#### Freight location editor (admins)

Tablet (`F9`) → **Admin → Freight locations**: create or fix loading and unloading spots. Position and heading are taken directly from the coupled trailer (button or `/truckloc`), plus cargo groups, access, radius, map preview and teleport.

#### Admin panel

Search players (also offline), edit XP, level, reputation, skills, statistics and challenges, unlock rental trucks, gift trucks, manage the company, view live drivers – every change is recorded in the audit log.

### Commands & Exports

#### Commands & keys

| Command / key         | Function                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `F9` (`/trucktablet`) | Driver tablet – at the logistics terminal, anywhere while on duty                                               |
| `E`                   | Use the terminal at a depot                                                                                     |
| `Y` / `N`             | Accept / decline a convoy invitation                                                                            |
| `/truckloc`           | Admins only: copy your current position (in a truck: the trailer position) into the open freight location draft |

{% hint style="info" %}
Players can change the keys in the GTA settings → Key Bindings → FiveM.
{% endhint %}

#### Exports (server, read-only)

| Export                                | Description                       |
| ------------------------------------- | --------------------------------- |
| `GetTruckerData(src)`                 | Career and statistics of a player |
| `IsTruckerOnDuty(src)`                | Is the player on duty?            |
| `GetTruckerStatus(src)`               | Current status of the player      |
| `GetTruckerJob(src)`                  | Current job of the player         |
| `GetOnDutyTruckers()`                 | List of truckers on duty          |
| `GetPlayerTrucks(identifier)`         | Own trucks of a player            |
| `GetTruckingCompany()`                | Logistics company info            |
| `IsTruckingEmployee(srcOrIdentifier)` | Employee check                    |
| `GetFreightLocations()`               | All freight locations             |

Example:

```lua
local onDuty = exports.pepper_trucking:IsTruckerOnDuty(source)
```

{% hint style="info" %}
There is deliberately **no** export that lets other resources create money, XP or reputation.
{% endhint %}

### FAQ

<details>

<summary>Do players need an ESX job?</summary>

No. Everyone can start a shift; the company (staff, ranks, salaries) runs inside the resource.

</details>

<details>

<summary>Does F9 conflict with Pepper Taxi or Pepper Bus?</summary>

No – Taxi uses F6 and Bus F7. Every player can also rebind the key in the GTA key bindings.

</details>

<details>

<summary>A freight location is badly placed or inside a wall.</summary>

Visit the default locations once and re-capture them in the freight location editor with the trailer coupled in parking position (button or `/truckloc`).

</details>

<details>

<summary>I already use a fuel script.</summary>

Set `Config.Fuel.System` to `'legacyfuel'`, `'ox_fuel'` or `'cdn-fuel'`.

</details>

<details>

<summary>Do AI drivers earn money while nobody is online?</summary>

Yes. Missed runs are caught up after a restart. If the company account is empty, the AI drivers go on strike.

</details>

<details>

<summary>Can I start shifts at the secondary depots?</summary>

Yes, after checking their coordinates in-game: set `AllowShiftStart = true` for the depot in `Config.Depots`.

</details>

<details>

<summary>Can another resource pay out money or XP through Pepper Trucking?</summary>

No, the exports are read-only. Payouts happen server-side only.

</details>

#### Troubleshooting

| Problem                             | Solution                                                                                                                   |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Tables missing                      | Import `sql/install.sql` or set `Config.Database.AutoInstall = true`.                                                      |
| Admin area missing                  | ESX group in `Config.Admin.Groups` or ACE `pepper_trucking.admin`.                                                         |
| Trailer isn't recognized as coupled | Back the tractor unit up to the marked trailer at the ramp until it couples, then pull it a few meters away from the ramp. |
| Job failed                          | The deadline was exceeded by far, the trailer was lost or the cargo was destroyed.                                         |

### Changelog

#### 1.0.0 – 2026-09-27

**Initial release**

* Trucking career with 50 levels, reputation, rating and skill tree (8 skills, 1 point per level)
* Freight exchange with personal offers: 24 cargo types, hazmat, refrigerated goods, heavy haul, urgent jobs, multi-drop tours
* Real trailers: coupling at the ramp, drop-off in the unloading zone, parking rating with parking assistant
* Cargo damage, cold chain, deadlines, weigh stations with special permits, fuel with gas stations (or an external fuel script)
* Own trucks with dealer, garage, wear, workshop (upgrades, paint, repair) and resale
* Convoys for up to 4 drivers with shared jobs and convoy bonus
* Logistics company with staff, ranks, company account, fleet, depots and passive AI drivers
* In-game freight location editor (incl. `/truckloc`), admin panel (also offline), tablet and HUD in the Pepper design, German and English