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

# 📦 Cargo Delivery

***

Cargo delivery with reputation, streak bonuses, distance based payouts, and multi framework support.

> ⚠️ This resource requires our bridge resource ([`mk-bridge`](https://macky-dev.tebex.io/package/7449206)) to function properly.

[Docs](https://mackydev.gitbook.io/mackydev/resources/atm-robbery) • [Discord](https://discord.gg/GBPAGDmegX) • [Showcase](#installation)

***

## ⭐ Features

* Distance-based payout
* Randomized pickup and delivery locations
* Reputation progression system
* Four configurable cargo tiers
  * Low
  * Medium
  * High
  * Hazardous
* Delivery streak bonus
* Automatic truck bed cargo placement
* Dynamic cargo positioning for different truck sizes
* Optional job restriction
* JSON reputation storage (No SQL required)
* Fully configurable
* Lightweight and optimized
* Supports [ESX](https://github.com/esx-framework), [QBCore](https://github.com/qbcore-framework), and [QBox](https://github.com/Qbox-project)

***

### 📊 Performance

Idle: 0.00ms

Active: \~0.03ms

***

## 📥 Installation

1. Place `mk-bridge` `mk-cargodelivery` inside your server's `resources` folder.
2. Add to your `server.cfg`:

```cfg
ensure mk-bridge
ensure mk-cargodelivery
```

4. Configure `config.lua` to fit your server.
5. Restart your server.

***

## 🔧 Configuration

### 👷 Job Requirements

Require players to have a specific framework job before accepting delivery contracts.

```lua
Config.UseJobCheck = false -- Require job before accepting contracts.

Config.AllowedJob = 'trucker' -- Required job
```

***

### 💰 Payment

Configure how delivery payouts are calculated.

```lua
Config.PayPerMile = 500 -- Amount paid per mile traveled | Pickup -> Delivery.

Config.MinimumPay = 600 -- Minimum payout before distance calculations.

Config.PayAccount = 'bank' -- cash | bank
```

***

### 🔥 Delivery Streak Bonuses

Reward players for completing deliveries consecutively.

```lua
-- Consecutive delivery bonus multipliers.
Config.StreakBonus = {
    { count = 10, mult = 1.40 },
    { count = 5,  mult = 1.25 },
    { count = 3,  mult = 1.10 },
    { count = 1,  mult = 1.00 },
}

Config.StreakExpireSeconds = 900 -- Time before a delivery streak expires (15 minutes).
```

***

### 📦 Cargo Dispatcher

Configure where players accept delivery contracts.

```lua
Config.Dispatch = {

    -- Dispatcher interaction location.
    coords = vector3(107.82, -1086.54, 29.38),

    blip = {

        sprite = 478, -- sprite

        color = 5, -- color

        scale = 0.9, -- scale

        name = 'Cargo Dispatch', -- name

        shortRange = true, -- only visible on minimap when nearby
    },

    interactDistance = 3.0, -- distance required to interact
}
```

***

### 🚚 Vehicle Requirements

Choose which vehicles are allowed for deliveries.

```lua
Config.RequireTruck = true -- Require players to use vehicle class below 

-- Allowed vehicle classes.
Config.AllowedClasses = {9} -- 9 = offroad
```

***

### 📦 Cargo Settings

Configure how cargo attaches to vehicle beds.

```lua
Config.Cargo = {
    truckLoadDistance = 5.0, -- Distance from the truck to load cargo.
    bedInset = 1.0, -- Distance cargo is placed inward from the rear of the truck bed.
}
```

***

### ⭐ Reputation Progression

Configure when additional cargo tiers become available.

```lua
-- Deliveries required to unlock additional cargo tiers.
Config.TierThresholds = {
    medium = 5,
    high   = 15,
}
```

***

### 📊 Cargo Tier Selection

Adjust how often each unlocked cargo tier appears.

```lua
-- Chance of each unlocked tier being selected.
Config.TierWeight = {
    low    = 50,
    medium = 30,
    high   = 18,
    hazard = 2,
}

Config.HazardChance = 12 -- Chance for a High delivery to become Hazardous.
```

***

### 📦 Cargo Tiers

Each cargo tier supports its own payout multiplier, cargo props, and attachment offsets.

```lua
Config.Tiers = 
    low = {
        payMult = 1.0,
        props = { ... },
        handOffset = vector3(...),
        handRotation = vector3(...),
        truckOffset = vector3(...),
        truckRotation = vector3(...),
    },

    medium = { ... },

    high = { ... },

    hazard = { ... },
}
```

***

### 📍 Pickup Locations

Configure possible cargo pickup locations.

```lua
Config.PickupLocations = {
    {
        coords = vector3(...),
        label = 'Post OP',
    },
}
```

***

### 📍 Delivery Locations

Configure delivery destinations.

```lua
Config.DeliveryLocations = {
    {
        coords = vector3(...),
        label = 'LS Customs',
    },
}
```

***

### ⚙️ Interaction Settings

Configure interaction distances and delivery cooldowns.

```lua
Config.CooldownSeconds = 120 -- Time before a player can request another delivery

Config.PickupRadius = 8.0 -- Distance required to pick up cargo

Config.DeliveryRadius = 8.0 -- Distance required to complete deliveries

Config.Debug = true
```

***

## 🛠️ Support

If you experience any issues, have questions, or would like to report a bug, please open a support ticket through discord.