NR_MailBoxes

A realistic mailbox robbery script for QBX/QBCore with lockpick skill checks, police dispatch integration, and a weighted reward system.

Features

• Multiple mailbox models - Targets 6 different mailbox prop types found around the map
• Lockpick required - Players must have a lockpick to attempt robberies
• Skill-based minigame - ox_lib skill check adds challenge to robberies
• Robbery cooldown - Each mailbox has a 30-minute cooldown after being robbed
• Police dispatch integration - Configurable 50% chance to alert police
• Weighted reward system - Realistic loot table with common, uncommon, and rare items
• Anti-exploit protection - Server-side distance validation, cooldown tracking, and item verification
• Multi-dispatch support - Compatible with tk_dispatch, ps-dispatch, cd_dispatch, and fd-dispatch
• Performance optimized - Minimal resource usage with cached globals and efficient threading

Dependencies

Installation

Step 1: Download

Download NR_MailBoxes from your Tebex purchase and extract it to your resources folder:

server/
  └── resources/
      └── [nightrider]/
          └── NR_MailBoxes/

Step 2: server.cfg

Add the resource to your server configuration:

ensure NR_MailBoxes

Step 3: Configure Dispatch

Set your dispatch system in Open/cl_config.lua.

Step 4: Configure Rewards

Adjust the reward table in Open/sv_config.lua.

Step 5: Restart

Restart your server to load the resource.

How It Works

1. Finding Mailboxes

Players explore the map looking for mailbox props. 6 different mailbox models are targetable. No map markers — players must discover locations organically.

2. Initiating Robbery

Player must have a lockpick in inventory. Approach a mailbox and use ox_target (third eye), then select "Rob with Lockpick".

3. Skill Check

The player faces the mailbox automatically and a lockpick animation plays. An ox_lib skill check minigame appears with easy, easy, and medium difficulty. Keys 1, 2, 3, 4 must be pressed at the right time.

4. Robbery Progress

If the skill check succeeds, an 8-second progress bar starts with a robbery animation. The player cannot move or enter vehicles during this time. Can be cancelled by pressing the designated key.

5. Completion

Items are awarded based on the weighted probability system. A notification shows what was found. The mailbox enters a 30-minute cooldown and there's a 50% chance of a police dispatch alert.

6. Police Alert (if triggered)

A dispatch notification is sent to all on-duty police, a blip appears on police maps, and the alert includes the location and description.

Configuration

Client Config (Open/cl_config.lua)

-- Notification system
interaction = 'ox'  -- 'ox' or 'qb'

-- Dispatch system
dispatch = 'ps-dispatch'  -- 'tk_dispatch', 'ps-dispatch', 'cd_dispatch', 'fd-dispatch', 'none'

-- Interaction distance
maxDistance = 2.5  -- meters

-- Required item
item = 'lockpick'

Server Config (Open/sv_config.lua)

Core settings:

resetTime = 1800     -- 30 minutes cooldown per mailbox
maxRobDistance = 5.0 -- Maximum distance for anti-exploit validation

Timing:

duration = 8000  -- Progress bar duration (8 seconds)

Police settings:

policeChance = 15       -- Base alert chance
policeChanceAdded = 35  -- Additional chance (total 50%)
minPolice = 1           -- Minimum cops required (0 to disable)
policeJobs = {'police', 'marshal', 'state'}

Reward System (Weighted Probability)

The reward table uses weighted percentages. Total should equal 100%.

Reward = {
    -- Common (70% total)
    {item = 'money', amount = math.random(5, 10), chance = 35},
    {item = 'money', amount = math.random(10, 50), chance = 20},
    {item = 'wooden_dice', amount = 1, chance = 15},

    -- Uncommon (20% total)
    {item = 'money', amount = math.random(50, 150), chance = 10},
    {item = 'ammo-9-box', amount = 1, chance = 5},
    {item = 'money', amount = math.random(150, 300), chance = 5},

    -- Rare (10% total)
    {item = 'money', amount = math.random(150, 300), chance = 5},
    {item = 'lockpick', amount = math.random(1, 3), chance = 3},
    {item = 'money', amount = math.random(150, 300), chance = 2},
}

Mailbox Models

The script targets these mailbox props:

Dispatch Systems

Set your dispatch system in Open/cl_config.lua:

dispatch = 'tk_dispatch'  -- tk_dispatch
dispatch = 'ps-dispatch'  -- ps-dispatch
dispatch = 'cd_dispatch'  -- cd_dispatch
dispatch = 'fd-dispatch'  -- fd-dispatch
dispatch = 'none'         -- No dispatch

To customize dispatch alerts, edit the dispatch.sendCall() function in Escrowed/cl_main.lua:

function dispatch.sendCall(data)
    title = "Mailbox Robbery"
    code = "10-34"
    priority = "Priority 2"
    message = "Suspicious activity at mailbox!"
end

Security & Anti-Exploit

Server-Side Validation

Client-Side Protection

• Item requirement - ox_target only shows option if lockpick is present
• State management - isRobbing flag prevents concurrent robberies
• Callback validation - Checks server-side cooldown before starting

Customization

Adding Custom Mailbox Models

Edit the mailBoxes table in Open/cl_config.lua:

mailBoxes = {
    'prop_postbox_01a',
    'your_custom_mailbox_prop',
    'another_mailbox_model',
}

Adjusting Difficulty

Edit utils.minigame() in Escrowed/cl_main.lua:

lib.skillCheck({'easy', 'medium', 'hard'}, {'w', 'a', 's', 'd'})

Adjust progress time:

duration = 12000  -- 12 seconds instead of 8

Adjust cooldown time:

resetTime = 3600  -- 1 hour instead of 30 minutes

Modifying Police Alert Chance

-- Always alert:
if true then
    dispatch.sendCall({...})
end

-- Never alert:
dispatch = 'none'  -- In cl_config.lua

-- Custom percentage (25%):
if math.random(100) <= 25 then
    dispatch.sendCall({...})
end

Inventory Bridge

The script auto-detects your inventory system: ox_inventory (recommended), qb-inventory, or ps-inventory. Add support for a custom inventory in the inventory.addItem() function:

elseif GetResourceState('your-inventory') == 'started' then
    return exports['your-inventory']:AddItem(source, item, count)

Debug Mode

Enable debug in Open/cl_config.lua:

debug = true

Debug features include server console logs for robberies, validation failure messages, exploit attempt logging, and /testmailbox command to find nearby mailboxes.

Performance

Troubleshooting

Mailboxes not showing ox_target option

• Verify ox_target is running
• Check if lockpick item name matches your inventory
• Confirm mailbox models exist in your server

Can't rob mailbox (already robbed error)

• Mailbox has a 30-minute cooldown
• Find a different mailbox
• Wait for cooldown to expire

No rewards received

• Check server console for errors
• Verify item names exist in your ox_inventory
• Ensure inventory isn't full

Police alerts not working

• Confirm dispatch system in cl_config.lua matches your server
• Check if dispatch resource is running
• Verify police job names in sv_config.lua

Skill check too hard/easy

• Modify difficulty in utils.minigame()
• Options: 'easy', 'medium', 'hard'
• Change key bindings if needed

Support

For paid script support, open a ticket in our Discord server for priority assistance.