📦OLRP Dropbox

🎁 Overview

OLRP Drop Box is a dynamic loot drop system that creates exciting treasure hunting experiences on your FiveM server. Players receive notifications when mysterious drop boxes appear across the map, creating competitive scavenger hunts with valuable rewards.

Key Features

• 🎯 5-Tier Rarity System — Common, Uncommon, Rare, Epic, and Legendary drops

• 🗺️ 60+ Spawn Locations — Strategically placed across the entire map

• 🎨 Visual Indicators — Color-coded blips and radius indicators

• 📱 Real-time Notifications — Instant alerts for all players

• 🎁 Comprehensive Rewards — Items, weapons, cash, and special keys

• 🔧 Fully Customizable — Every aspect can be configured

• 📊 Discord Integration — Webhook notifications for server events

• ⚡ Performance Optimized — Lightweight and efficient

🚀 Quick Start

1

Install

Install the script to your server.

2

Configure

Configure reward categories and spawn locations.

3

Start

Start the resource and watch the magic happen.

4

Customize

Adjust settings to match your server's economy.

📋 Requirements

• Framework: QBCore or Qbox

• Dependencies: ox_lib

• Permissions: Admin access for configuration

• Server: FiveM server with Lua 5.4 support

🎮 How It Works

1

Drop Event

A drop box spawns at a random location.

2

Notification

All players receive a map notification.

3

Race

Players rush to find the drop box first.

4

Collection

First player to reach it collects all rewards.

5

Cleanup

Drop box disappears after collection.

6

Cooldown

System waits before spawning the next drop.

🎯 Rarity System

Rarity	Chance	Color	Rewards
Common	50%	White	Basic items, small cash amounts
Uncommon	25%	Green	Better items, moderate cash
Rare	15%	Blue	Good items, special keys
Epic	8%	Purple	High-value items, weapons
Legendary	2%	Red	Premium items, rare weapons

📍 Spawn Locations

Drop boxes can spawn at 60+ carefully selected locations across:

• Los Santos — Downtown, suburbs, and industrial areas

• Sandy Shores — Desert locations and airfields

• Paleto Bay — Northern wilderness areas

• Mountains — High-altitude locations

• Coastline — Beach and pier areas

🎁 Reward Categories

Items

• Cash — Marked bills ($5,000 - $100,000)

• Drugs — Meth, crack, cocaine (10-60 units)

• Ammunition — Pistol, SMG, rifle ammo (10-60 rounds)

• Armor — Body armor and heavy armor (10-60 units)

• Keys — Special access cards and keys

Weapons

• Pistols — Various pistol models

• SMGs — Compact and assault weapons

• Rifles — Assault rifles and carbines

• Knives — Melee weapons and tools

• Special — Lockpicks and utility items

⚙️ Configuration Options

• Timing — Customizable spawn intervals

• Rewards — Fully customizable reward pools

• Locations — Add or remove spawn points

• Notifications — Customize alert messages

• Discord — Webhook integration settings

• Permissions — Access control options

---

Installation Guide

📋 Prerequisites

Before installing OLRP Drop Box, ensure you have:

• FiveM Server with Lua 5.4 support

• Framework: QBCore or Qbox

• ox_lib dependency installed

• Admin Access to your server files

• Database Access (if using persistent features)

🚀 Installation Steps

1

Download & Extract

1. Download the OLRP Drop Box script from your purchase

2. Extract the files to your server's resources folder

3. Ensure the folder structure is correct:

resources/
└── olrp-dropbox/
    ├── bridge/
    ├── client.lua
    ├── server.lua
    ├── config.lua
    ├── sv_config.lua
    ├── reward_config.lua
    └── fxmanifest.lua

2

Framework Setup

For QBCore Servers

• Ensure qb-core is installed and running. No additional setup required — automatic detection.

For QBOX Framework Servers

• Ensure QBOX Framework is installed and running. No additional setup required — automatic detection.

3

Dependencies

Install the required dependency by adding to your server.cfg:

# Add to your server.cfg
ensure ox_lib

4

Server Configuration

Add the resource to your server.cfg:

# Add this line to your server.cfg
ensure olrp-dropbox

5

Initial Configuration

1. Open config.lua and customize basic settings:

return {
    TextUIMessage = 'Press **E** to collect OLRP Dropbox',
    DropNotify = 'OLRP has dropped a box somewhere. Check your map for details!',
    Blip = {
        alpha = 150,
        color = 0,
    }
}

1. Open sv_config.lua and configure:

   • Webhook URL for Discord notifications

   • Spawn timing settings

   • Minimum player requirements

2. Open reward_config.lua and customize:

   • Reward categories and chances

   • Item lists and quantities

   • Rarity colors and settings

6

Start the Resource

1. Restart your server or use the command:

restart olrp-dropbox

1. Check the console for initialization messages:

[OLRP Drop Box] Resource started successfully
[OLRP Drop Box] Framework detected: QBCore
[OLRP Drop Box] Reward system initialized

🔧 Post-Installation Setup

Discord Webhook Setup (Optional)

1. Create a Discord Webhook in your server settings → Integrations → Webhooks. Copy the webhook URL.

2. Configure the Webhook in sv_config.lua:

-- In sv_config.lua
WebhookURL = 'YOUR_DISCORD_WEBHOOK_URL_HERE'

Testing the Installation

• Use admin commands (if available):

/dropbox_test  # Test drop box spawn
/dropbox_debug # Enable debug mode

• Monitor console for errors and verify framework detection and reward initialization.

• Test player experience with a natural spawn or the test command.

⚠️ Troubleshooting

Common issues and solutions are detailed in the Troubleshooting section below (search for "Resource Won't Start", "No Notifications Appearing", "Rewards Not Given", etc.). Enable debug mode in sv_config.lua to get detailed logs:

-- In sv_config.lua
Debug = true

---

Configuration Guide

⚙️ Configuration Overview

OLRP Drop Box offers extensive customization via three main configuration files:

• config.lua — Basic UI and notification settings

• sv_config.lua — Server-side settings and spawn configuration

• reward_config.lua — Reward system and rarity configuration

📱 Basic Configuration (config.lua)

UI Messages

return {
    TextUIMessage = 'Press **E** to collect OLRP Dropbox',
    DropNotify = 'OLRP has dropped a box somewhere. Check your map for details and be the first to find it!',
    Blip = {
        alpha = 150,    -- Blip transparency (0-255)
        color = 0,      -- Default blip color
    }
}

Customization Options

Setting	Description	Default	Options
TextUIMessage	Interaction prompt text	Press E to collect...	Any text
DropNotify	Server notification message	OLRP has dropped a box...	Any text
Blip.alpha	Blip transparency	150	0-255
Blip.color	Default blip color	0 (White)	0-85

🖥️ Server Configuration (sv_config.lua)

Core Settings

return {
    -- Timing Configuration
    MinPlayers = 1,
    FirstDropMin = 30,
    FirstDropMax = 60,
    SubsequentDropMin = 90,
    SubsequentDropMax = 150,

    -- System Settings
    Debug = true,
    WebhookURL = 'YOUR_WEBHOOK_URL',

    -- Models and Locations
    Models = {
        'prop_box_wood03a',
    },
    Locations = {
        -- 60+ spawn locations
    }
}

Timing Configuration table and Spawn Location Management are documented in the original content — add or modify Locations as:

Locations = {
    {coords = vec3(x, y, z), rot = vec3(rx, ry, rz)},
    -- Add your custom locations here
}

Discord Webhook Configuration

• Create webhook in Discord, copy URL, paste into WebhookURL in sv_config.lua. Features include drop, collection and error notifications.

🎁 Reward Configuration (reward_config.lua)

Rarity System Overview

return {
    RewardCategories = {
        {
            name = "Common",
            chance = 50,
            color = "~w~",
            rewards = {
                -- Reward items
            }
        },
        -- Additional categories...
    }
}

Rarity tiers, reward types (item, weapon, money), and code examples for defining items are provided in the original content.

Color Configuration example

RarityColors = {
    Common = {
        blipColor = 0,
        radiusColor = 0,
        radiusAlpha = 150,
        textColor = "~w~"
    },
    -- Additional colors...
}

🔧 Advanced Configuration

Examples for custom spawn and reward logic, performance optimization, and configuration examples (High-Frequency Server, Low-Frequency Server, Economy-Focused, Combat-Focused) are included in the original content and can be copied directly into your config files.

---

Features & Functionality

🎯 Core Features

• Dynamic Spawn System (random timing, first drop delay, 60+ spawn points)

• Rarity-Based Rewards (5-tier system, percentage based)

• Real-Time Notifications (map alerts, radius indicators, chat messages, Discord)

🎮 Player Experience

Discovery and collection phases are sequential processes — summarized below as steppers.

Discovery Phase

1

Notification

"OLRP has dropped a box somewhere. Check your map!"

2

Map Check

Players see colored blip indicating rarity.

3

Search

Players navigate to the general area.

4

Exploration

Search within the radius indicator.

Collection Phase

1

Proximity

Player approaches the drop box.

2

Interaction

Press E to collect rewards.

3

Rewards

All items from the rarity tier are given to the player who collects.

4

Notification & Cleanup

Success message with reward list and drop box disappears.

🎨 Visual Features

• Blip System: Color coding, alpha control, radius display, dynamic updates

• Notification System: Color-coded text, rich formatting, multi-language support, customizable messages

• Model System: 3D objects, correct rotation, collision detection, cleanup

🔧 Technical Features

• Performance Optimization: lightweight code, efficient spawning, memory management

• Error Handling: graceful failures, partial rewards, logging, fallback systems

• Framework Compatibility: QBCore, ESX, ND Framework with automatic bridge detection

📊 Analytics & Monitoring

• Discord Webhooks for events and errors

• Logging: collection logs, error logs, performance metrics, debug information

🛡️ Security Features

• Server-side validation, permission checks, rate limiting, data validation

• Admin commands, permission system, debug and maintenance modes

---

Rewards System

🎁 Rewards System Overview

Detailed 5-tier rarity structure, reward categories, selection and distribution mechanics, error handling and customization options are provided in the original content.

🎯 Rarity System

Tier	Chance	Color	Blip Color	Description
Common	50%	~w~	0	Basic items, small cash amounts
Uncommon	25%	~g~	2	Better items, moderate cash
Rare	15%	~b~	3	Good items, special keys
Epic	8%	~p~	27	High-value items, weapons
Legendary	2%	~r~	17	Premium items, rare weapons

Cash, drug, ammo, armor, weapon, and special item reward breakdowns, selection process, distribution rules (player gets all rewards from selected tier with random quantities), and customization snippets are included in the original content.

Examples for adding custom rewards

Item, weapon, and money reward code snippets are provided in the original content — copy those directly into reward_config.lua when adding new rewards.

---

Troubleshooting

⚠️ Common Issues

The original documentation provides detailed troubleshooting for: Resource Won't Start, No Notifications Appearing, Rewards Not Given, Performance Issues, Discord Webhook Issues, Debug Mode instructions, Performance Optimization, Update Issues and Getting Help. Key steps include enabling Debug, checking dependencies, validating config syntax, verifying framework and item names, and testing webhooks.

Debug Mode

Enable in sv_config.lua:

Debug = true

Debug commands (admin):

/dropbox_test
/dropbox_debug
/dropbox_status
/dropbox_cleanup

Performance and memory management tips are included in the original content.

---

FAQ

What frameworks does OLRP Drop Box support?

A: OLRP Drop Box supports QBCore, ESX, and QBOX Framework with automatic detection and bridge system.

How often do drop boxes spawn?

A: By default, the first drop appears 30-60 minutes after server restart, then every 90-150 minutes. This is fully customizable in the configuration.

Can I customize the spawn locations?

A: Yes! You can add, remove, or modify spawn locations in the `sv_config.lua` file. The script comes with 60+ pre-configured locations.

What happens if multiple players reach the drop box at the same time?

A: Only the first player to interact with the drop box will receive the rewards. It's a first-come-first-served system.

How do I change the reward items?

A: Edit the `reward_config.lua` file to modify reward categories, items, quantities, and rarity chances. Each tier can be fully customized.

Can I add my own custom items to the rewards?

A: Yes! Simply add your custom items to the appropriate rarity tier in `reward_config.lua`. Make sure the item names match your server's item database.

How do I set up Discord notifications?

A: Create a Discord webhook in your server settings, then paste the URL into the `WebhookURL` setting in `sv_config.lua`.

Can I disable certain rarity tiers?

A: Yes! Set the chance to 0 for any rarity tier you want to disable, or remove it entirely from the configuration.

Does this script cause server lag?

A: No, OLRP Drop Box is optimized for performance with minimal server impact. It uses efficient spawning and cleanup systems.

What if a player's inventory is full?

A: The script handles inventory management automatically. If some items can't be given due to full inventory, the player will receive what they can and be notified of partial rewards.

Can I run multiple drop box systems simultaneously?

A: While technically possible, it's not recommended as it could cause conflicts and performance issues. One instance per server is recommended.

How do I update the script?

A: Download the new version, backup your configuration files, replace the script files, restore your configs, and restart the resource.

Will this script inflate my server's economy?

A: No, the rewards are designed to be balanced and supplement existing income sources rather than replace them. Cash amounts are moderate and items are useful but not game-breaking.

Can I adjust the cash rewards for my server's economy?

A: Absolutely! All reward amounts are fully customizable in `reward_config.lua`. Scale the amounts to match your server's economy.

What if I want to remove cash rewards entirely?

A: Simply remove or comment out the cash reward entries in each rarity tier of `reward_config.lua`.

How many spawn locations should I use?

A: The script comes with 60+ locations, but you can use fewer for better performance. 20-30 well-distributed locations work well for most servers.

Can I reduce the spawn frequency for better performance?

A: Yes! Increase the `SubsequentDropMin` and `SubsequentDropMax` values in `sv_config.lua` to reduce spawn frequency.

Should I enable debug mode in production?

A: No, debug mode should only be enabled for troubleshooting. It generates additional console output that can impact performance.

Where can I get help if I have issues?

A: Check this documentation first, then join the OLRP Discord community for support. Provide detailed information about your issue (framework, versions, logs).

Do you provide custom modifications?

A: Contact support for information about custom modifications. Many requests can be handled through configuration changes.

Is there a warranty or guarantee?

A: Check your purchase agreement for warranty details. Support and updates are provided as described in your purchase.

---

If you want, I can:

• Extract the code snippets into separate titled code blocks for GitBook code block titles.

• Create a ready-to-drop server.cfg snippet and sample minimal config files (config.lua, sv_config.lua, reward_config.lua) based strictly on the settings shown above.