🐝Beekeeping Script

1) Overview

Risk Beekeeping is a fully featured beekeeping job script for FiveM servers featuring:

• 🐝 Placeable beehives with real collection timers

• 🗺️ Forest scan zones – players must find the right location

• 🍯 Full honey processing chain (harvest → clean → mix → sell)

• 🧥 Beekeeper suit system with sting damage

• 🏪 Built-in shop, seller NPC and processing stations

• 🗑️ Auto-delete system for inactive hives with player notifications

• 🔒 Fully exploit-safe – all logic runs server-side

• 📦 Supports ESX, QBCore and QBox (auto-detected)

• 🗄️ SQL-based data storage via oxmysql

---

2) File Structure

You have access to these configuration files:

risk-beekeeping/
├── beekeeping.sql               ← Run this once in your database
└── config/
    ├── config_general.lua       ← Max hives, forest zones, scanner item
    ├── config_collector.lua     ← Hive placement, bee timer, auto-delete
    ├── config_market.lua        ← Shop location, items, prices, NPC
    ├── config_seller.lua        ← Seller NPC, sellable items, prices
    ├── config_cleaner.lua       ← Honey cleaner location and rewards
    ├── config_mixer.lua         ← Honey mixer location and rewards
    ├── config_clothing.lua      ← Beekeeper suit, sting damage
    ├── config_zones.lua         ← Forest scan zones
    └── config_notifications.lua ← All notification texts

---

3) Database Setup

Run the file beekeeping.sql once in your database before starting the script.

Step 1: Run the SQL file

1. Open HeidiSQL, phpMyAdmin or any SQL tool

2. Select your FiveM database

3. Open beekeeping.sql from the script folder

4. Execute the file

This creates two tables:

Table	Purpose
beekeeping_hives	Stores all placed hives with position, owner, and timer
beekeeping_pending_notify	Stores deletion notifications for offline players

⚠️ IMPORTANT: If you update the script and the table already exists, run only the ALTER TABLE line shown in the SQL file – do not run the full file again.

---

4) Items Setup

For ESX / QBCore / QBox

Inside the [items]/ folder you will find:

• items.lua – item definitions to add to your framework

• [items]/sql/ – ready-to-use SQL files (de, en, es, fr, ru, zh)

Run the SQL file for your language or manually add the items using items.lua.

Required Items

Item Name	Description
hive	Beehive – used to place in the world
bees	Bees – placed into the hive to start collecting
beehiveframe	Frame – consumed when placing (5x required by default)
forestscanner	Scanner – reveals allowed placement zones on the map
beekeeper_suit	Protective suit – protects against bee stings
dirtyhoney	Raw honeycomb – reward when harvesting
cleanhoney	Clean honey – output of the Cleaner station
emptyhoneyjar	Empty jar – required for the Mixer
honeyjar	Honey jar – finished product ready to sell
scraper	Hive tool – required to use the Cleaner

---

5) server.cfg Setup

Add the following to your server.cfg:

ensure oxmysql
ensure ox_lib
ensure risk-beekeeping

⚠️ IMPORTANT: oxmysql and ox_lib must start before risk-beekeeping.

The framework (ESX, QBCore or QBox) is detected automatically at runtime – nothing needs to be set manually.

---

6) Configuration

config_general.lua — General Settings

Config.Debug = false
Config.IdentifierType = "license"
Config.MaxHivesPerPlayer = 2
Config.ForestScannerItem = "forestscanner"

Setting	Description
Debug	Enable debug prints in the server console. Always false in production.
IdentifierType	Player identifier used for ownership. "license" or "steam".
MaxHivesPerPlayer	Maximum number of active hives per player at the same time.
ForestScannerItem	Item name of the forest scanner. Only change if you renamed the item.

---

config_zones.lua — Forest Scan Zones

Zones define where players are allowed to place beehives. Players must be inside a zone to place a hive.

Config.ForestScannerItem = "forestscanner"

Config.ForestScanZones = {{
    name = "Small Grove",
    center = vector3(1353.7408, 1477.2067, 102.3420),
    radius = 100,
    color = 46,
    alpha = 100,
    maxHives = 10
}, {
    name = "Big Forest",
    center = vector3(-250.0, 3500.0, 50.0),
    radius = 500,
    color = 46,
    alpha = 100,
    maxHives = 2
}}

Parameters:

Parameter	Description
name	Zone name displayed to the player
center	Center coordinates of the zone
radius	Zone radius in meters
color	Blip color when the zone is revealed by the scanner
alpha	Blip transparency (0–255)
maxHives	Maximum number of hives allowed in this zone at the same time

How to find coordinates:

• Use /coords in-game (if your server has this command)

• Or use the F8 console and type getpos in supported scripts

Add a new zone:

Config.ForestScanZones = {{
    name = "Pine Valley",
    center = vector3(500.0, -1200.0, 35.0),
    radius = 150,
    color = 46,
    alpha = 100,
    maxHives = 5
}}

Disable zone limit (unlimited hives per zone):

maxHives = 0

---

config_collector.lua — Beehive & Timing ⭐

This is the most important config file. Start here.

Config.Collector = {
    BeesWaitTime = 500,
    DeleteAfterDays = 3,
    RewardItem = "dirtyhoney",
    RewardQuantity = 10,
    RequiredFramesItem = "beehiveframe",
    RequiredFramesCount = 5,
    BeeItem = "bees",
    ...
}

Setting	Description
BeesWaitTime	How long bees collect honey, in seconds. Example: 3600 = 1 hour
DeleteAfterDays	Days until inactive hives are auto-deleted. Set 0 to disable
RewardItem	Item the player receives when harvesting the hive
RewardQuantity	How many of the reward item the player receives
RequiredFramesItem	Item consumed when placing the hive
RequiredFramesCount	How many frames are needed to place a hive
BeeItem	Item used to place bees into the hive

Timer examples:

BeesWaitTime = 1800    -- 30 minutes
BeesWaitTime = 3600    -- 1 hour
BeesWaitTime = 7200    -- 2 hours
BeesWaitTime = 86400   -- 24 hours

Hive blip settings:

EnableHiveBlip = true,     -- Show a blip on the map for placed hives
HiveBlipSprite = 783,      -- Blip icon
HiveBlipName = "Beehive",  -- Text shown on map
HiveBlipScale = 0.7,
HiveBlipColor = 5,

Optional placement items (e.g. require a hammer and wood to place):

RequiredPlaceItems = {
    enabled = false,        -- Set true to enable
    items = {{
        item = "hammer",
        count = 1,
        remove = false,     -- false = item stays in inventory
        label = "Hammer"
    }, {
        item = "wood",
        count = 5,
        remove = true,      -- true = item gets removed
        label = "Wood"
    }}
}

💡 TIP: Set enabled = false to skip this requirement completely.

---

config_market.lua — Shop

The market is where players buy all beekeeping supplies.

Config.Market = {
    Location = vector3(1532.0930, 1728.2382, 108.9176),
    ...
}

Setting	Description
Location	Coordinates of the shop marker
ShowDistance	Distance from which the marker becomes visible
MarkerRadius	Distance at which the player can interact
OpenKey	Key to open the shop (default: 38 = E)
NPC.enable	Show an NPC at the shop location
NPC.model	NPC model name
NPC.coords	NPC position and heading (vector4)
Blip.enable	Show a map blip for the shop

Shop items — add, remove or change prices:

Items = {{
    name = "Beehive",
    item = "hive",
    price = "$30",
    amount = 1,
    description = "A wooden beehive where bees can live.",
    image = "haus.png"
}}

Parameter	Description
name	Display name shown in the shop UI
item	Internal item name (must match your items)
price	Price shown in the UI (use "$30" format)
amount	How many items the player receives per purchase
description	Short description shown in the shop
image	Image filename from the html/images/ folder

---

config_seller.lua — Seller NPC

The seller is where players sell processed honey products.

Config.Seller = {
    Location = vector3(802.9879, 2175.2734, 52.0708),
    SellAmount = 5,
    ItemsToSell = {{
        label = "Honey Jar",
        item = "honeyjar",
        pricePerUnit = 50
    }},
    ...
}

Setting	Description
Location	Coordinates of the seller marker
SellAmount	How many items are sold per click
ItemsToSell	List of sellable items with labels and prices
PaymentMethods	Payment options shown to the player (Cash / Bank)
NPC.enable	Show an NPC at the seller location

Change sell prices:

ItemsToSell = {{
    label = "Honey Jar",
    item = "honeyjar",
    pricePerUnit = 100      -- Changed to $100
}, {
    label = "Clean Honey",
    item = "cleanhoney",
    pricePerUnit = 50
}, {
    label = "Dirty Honey",
    item = "dirtyhoney",
    pricePerUnit = 15
}}

Change items sold per click:

SellAmount = 1    -- Sell 1 item at a time
SellAmount = 10   -- Sell 10 items at a time

---

config_cleaner.lua — Honey Cleaner

The cleaner converts raw honeycomb into clean honey.

Config.Cleaner = {
    Location = vector3(-796.7173, 185.6047, 72.6054),
    RequiredHoneyItem = "dirtyhoney",
    RequiredHoneyCount = 10,
    RequiredToolItem = "scraper",
    RewardItem = "cleanhoney",
    RewardQuantity = 5,
    ...
}

Setting	Description
Location	Coordinates of the cleaner station
RequiredHoneyItem	Input item (raw honeycomb)
RequiredHoneyCount	How many input items are consumed per cycle
RequiredToolItem	Tool required to use the cleaner (not consumed)
RewardItem	Output item (clean honey)
RewardQuantity	How many output items are produced

Processing ratio example (10 dirty → 5 clean):

RequiredHoneyCount = 10,
RewardQuantity = 5,

---

config_mixer.lua — Honey Mixer

The mixer combines clean honey and an empty jar into a sellable honey jar.

Config.Mixer = {
    Location = vector3(1217.0969, 1905.1538, 76.8086),
    RequiredHoneyItem = "cleanhoney",
    RequiredHoneyCount = 4,
    RequiredEmptyJarItem = "emptyhoneyjar",
    RewardItem = "honeyjar",
    RewardCount = 1,
    ...
}

Setting	Description
Location	Coordinates of the mixer station
RequiredHoneyItem	Input item (clean honey)
RequiredHoneyCount	How many input items are consumed per mix
RequiredEmptyJarItem	Empty jar consumed per mix
RewardItem	Output item (honey jar)
RewardCount	How many output items are produced

---

config_clothing.lua — Beekeeper Suit

Controls the protective suit system and bee sting mechanics.

Config.BeeKeeper = {
    ClothingEnabled = true,
    SingleSuitItem = "beekeeper_suit",
    MatchTextures = true,
    HiveDangerDistance = 5.0,
    DamageInterval = 8000,
    DamageAmount = 5,
    MinimumHealth = 102,
    ...
}

Setting	Description
ClothingEnabled	Enable or disable the entire suit system
SingleSuitItem	Item name of the beekeeper suit
MatchTextures	true = suit texture must also match; false = only check the drawable
HiveDangerDistance	Distance in meters at which bees start stinging
DamageInterval	Time between stings in milliseconds (8000 = every 8 seconds)
DamageAmount	Health removed per sting
MinimumHealth	Health will never go below this value

Disable sting damage completely:

ClothingEnabled = false

Make bees more aggressive:

HiveDangerDistance = 10.0,   -- Start stinging from 10m away
DamageInterval = 3000,        -- Sting every 3 seconds
DamageAmount = 10,            -- 10 damage per sting

---

config_notifications.lua — Notification Texts

All messages shown to players can be edited here.

💡 TIP: Keep placeholders like {minutes}, {count}, {days}, {item}, {max} in place – they are automatically replaced with real values.

Important placeholders:

Placeholder	Used in	Replaced with
{minutes}	beesNotReady, placeBeesSuccess	Remaining minutes
{count}	collectorMissingFrames, zoneHiveCapReached	Item count / hive count
{max}	maxHiveReached, zoneHiveCapReached	Max allowed amount
{item}	missingPlaceItem, cleanerMissingHoney	Item name
{days}	hiveDeletedInactive	Days from DeleteAfterDays

Translate to German (example):

beesNotReady = "Deine Bienen sind noch nicht fertig! Komm in {minutes} Minuten wieder!",
beesFinished = "Deine Bienen sind fertig! Du kannst den Bienenstock jetzt öffnen!",

---

7) Player Gameplay Flow

This is the full process a player follows from start to finish:

1. Go to the MARKET
   → Buy a Beehive (hive)
   → Buy Beehive Frames (5x required by default)
   → Buy Bees
   → Optional: Buy Beekeeper Suit (protection against stings)
   → Optional: Buy Forest Scanner (reveals allowed zones on the map)

2. Use the Forest Scanner
   → Green zones appear on the minimap
   → Travel to one of the zones

3. Place the Beehive
   → Use the hive item from the inventory
   → Confirm the green placement marker (press E)
   → 5x Beehive Frames are consumed automatically

4. Place the Bees
   → Walk up to your placed hive
   → Press E
   → Use the bees item from inventory
   → Collection timer starts

5. Harvest the Honey
   → Return after the timer ends
   → Press E to collect
   → Receive dirtyhoney in inventory
   → Hive is automatically removed after harvesting

6. Clean the Honey — CLEANER station
   → Requires 10x dirtyhoney + scraper tool
   → Output: 5x cleanhoney

7. Fill the Jars — MIXER station
   → Requires 4x cleanhoney + 1x emptyhoneyjar
   → Output: 1x honeyjar

8. Sell
   → Go to the SELLER NPC
   → Choose item and payment method (Cash or Bank)

---

8) Auto-Delete System

Hives that are left inactive are automatically deleted after the number of days set in DeleteAfterDays.

How the timer works:

Situation	Timer starts
Hive placed, no bees added	From the moment the hive was placed
Bees placed (even after 2 days)	Timer resets to the moment bees were placed
Hive ready but not harvested	From the moment the bees finished collecting

Disable auto-delete:

DeleteAfterDays = 0

Player notifications:

• Online — Player is notified immediately when their hive is deleted

• Offline — Notification is saved and shown the next time the player logs in

If a player had multiple hives deleted, they receive one combined message:

3x beehive(s) were automatically removed because they were not collected for 3 days!

💡 TIP: Customize the message text in config_notifications.lua → hiveDeletedInactive.

---

9) Troubleshooting

❌ Hive cannot be placed

Possible causes:

• Player is not inside a ForestScanZone

• Zone has reached maxHives limit

• Player already has MaxHivesPerPlayer active hives

• Player is missing required items (frames, etc.)

Solution:

• Check zone coordinates in config_zones.lua

• Increase maxHives or MaxHivesPerPlayer if needed

• Verify all required items are in the player's inventory

---

❌ Hive timer shows wrong time

Possible causes:

• This was a known bug caused by client/server time mismatch

Solution:

• This bug is fixed in the current version

• Restart the server after updating

---

❌ Items not recognized

Possible causes:

• Items not added to the database or items.lua

• Wrong item name in config

Solution:

• Run the SQL file from [items]/sql/ for your language

• Make sure item names in config match exactly (case-sensitive)

---

❌ SQL error on server start

Possible causes:

• beekeeping.sql has not been run

• oxmysql starts after risk-beekeeping

Solution:

• Run beekeeping.sql in your database

• Make sure ensure oxmysql comes before ensure risk-beekeeping in server.cfg

---

❌ NPC not visible

Possible causes:

• NPC is disabled in config

• Wrong coordinates

Solution:

• Check NPC.enable = true in config_market.lua / config_seller.lua

• Verify NPC coordinates are correct

---

❌ Bees not stinging without suit

Possible causes:

• ClothingEnabled is set to false

• Player is too far from the hive

Solution:

• Set ClothingEnabled = true in config_clothing.lua

• Check HiveDangerDistance – increase if needed

---

❌ Hives not being auto-deleted

Possible causes:

• DeleteAfterDays is set to 0

• Hives do not meet the deletion conditions yet

Solution:

• Set DeleteAfterDays to a value greater than 0

• The check runs every hour and on server restart

---

10) Best Practices

✅ Set BeesWaitTime to match your server economy — Too short = too easy, too long = players lose interest ✅ Configure all 4 locations — Market, Seller, Cleaner and Mixer should all be at different spots ✅ Use the Forest Scanner — Make sure at least 1-2 zones are within the map boundaries ✅ Set maxHives per zone — Prevents one player from monopolizing a zone ✅ Enable DeleteAfterDays — Keeps the database clean and prevents ghost hives ✅ Keep item names lowercase — Item names are case-sensitive ✅ Test all stations — Buy items, place hive, harvest, clean, mix, sell before going live ✅ Backup config files — Save copies before making changes

---

11) Quick Start Checklist

• [ ] Run beekeeping.sql in the database

• [ ] Add items via [items]/sql/ or items.lua

• [ ] Add ensure risk-beekeeping to server.cfg

• [ ] Set MaxHivesPerPlayer in config_general.lua

• [ ] Set zone coordinates in config_zones.lua

• [ ] Set BeesWaitTime in config_collector.lua

• [ ] Set DeleteAfterDays in config_collector.lua

• [ ] Set Market location in config_market.lua

• [ ] Set Seller location and prices in config_seller.lua

• [ ] Set Cleaner location in config_cleaner.lua

• [ ] Set Mixer location in config_mixer.lua

• [ ] Adjust sell prices in config_seller.lua

• [ ] Start the server and test all stations in-game