ds-mailtheft

# 📬 Mail Theft Script (QBCore / ESX)

A configurable and framework-flexible script that allows players to steal

from **mailboxes** around the map and earn randomized loot rewards.

Supports **QBCore**, **ESX**, or **auto-detection**,

with optional integration for multiple **target**, **inventory**, **progress**, and **notification** systems.

---

# 📦 Installation

1. **Download** this resource into your server’s `resources` folder.

Example:

resources/[qb] or [esx]/ds-mailtheft

2. Add the following line to your **server.cfg**:

ensure ds-mailtheft

3. Configure your settings inside `config.lua` as you wish.

---

#⚙️ Configuration Overview

The configuration file (config.lua) is fully customizable and built for maximum flexibility.

Below is an explanation of each configurable option.

---

# 🧩 Core Settings

| Setting | Description | Options | Default |

|----------|--------------|----------|----------|

| `Config.Framework` | Game framework to use. | `"qbcore"`, `"esx"`, `"auto"` | `"auto"` |

| `Config.NotifyType` | Notification system integration. | `"qb"`, `"ox"`, `"okok"`, `"ps"`, `"custom"` | `"qb"` |

| `Config.Inventory` | Inventory system integration. | `"qb"`, `"ox"`, `"ps"`, `"custom"` | `"ps"` |

| `Config.Target` | Target system to use. | `"qb-target"`, `"ox_target"`, `"3dtext"`, `"auto"` | `"qb-target"` |

| `Config.Progress` | Progress bar or task display. | `"qb"`, `"ox"`, `"ps"`, `"text"` | `"qb"` |

---

# ⏱️ Cooldowns

| Setting | Description | Default |

|----------|--------------|----------|

| `Config.MailboxCooldown` | Time (in seconds) before a mailbox can be reused. | `180` |

| `Config.ReuseDelay` | Time (in seconds) to prevent mailbox spam checks. | `5` |

---

# 🎮 Mini-Game Integration

| Setting | Description | Options | Default |

|----------|--------------|----------|----------|

| `Config.StealMinigame` | Select the mini-game required for stealing. | `"none"`, `"memorygame"`, `"qb-lock"`, `"ps-ui"` | `"ps-ui"` |

---

# 📬 Mailbox Models

List of world models recognized as mailboxes for the script.

Add or remove models as needed.

```lua

Config.Mailboxes = {

'prop_postbox_ss_01a',

'prop_postbox_01a',

'prop_letterbox_01',

'prop_letterbox_02',

'prop_letterbox_03',

'prop_letterbox_04',

}

💰 Reward System

You can fully customize the items and their drop chances.

Each reward includes:

item → the item name

chance → the percent chance to receive it

amount → {min, max} range of item quantity

Example:

{ item = "cash", chance = 35, amount = {10, 500} },

{ item = "burger", chance = 20, amount = {1, 1} },

{ item = "lockpick", chance = 42, amount = {1, 3} },

💡 You can add or remove rewards freely — the system will automatically handle them.

🧰 Custom Functions (Optional)

If your server uses custom notification or inventory systems,

you can override these functions to integrate your own logic.

-- Custom notification function

Config.CustomNotify = function(msg, type)

TriggerEvent('chat:addMessage', { args = { '[Mail Theft]', msg } })

end

-- Custom inventory give function

Config.CustomAddItem = function(src, item, amount)

print(("Give %s x%d to %s (custom inventory)"):format(item, amount, GetPlayerName(src)))

end

🧠 Framework Auto-Detection

When Config.Framework = "auto", the script will:

Automatically detect if QBCore or ESX is running.

Load the appropriate functions for item giving, notifications, and targeting.

No manual setup needed unless you want to force one framework.

🔌 Dependencies

Depending on your configuration, you may need one or more of the following:

Frameworks:

qb-core

es_extended

Target Systems:

qb-target

ox_target

Inventories:

ps-inventory

ox_inventory

qb-inventory

custom

Progress / UI:

ps-ui

progressbar - this is built in qb framework

ox_lib

🎮 Example Usage:

Players can find mailboxes around the map (based on Config.Mailboxes)

and interact with them to attempt a theft.

They’ll trigger a progress bar, optional mini-game, and receive random loot based on the reward pool.

🗺️ Suggested Installation Path:

resources/[qb] or [esx]/ds-mailtheft