📬 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.

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