# 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**

```lua
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.

```lua
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:**

```lua
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):**

```lua
maxHives = 0
```

***

**config\_collector.lua — Beehive & Timing ⭐**

This is the most important config file. Start here.

```lua
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:**

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

**Hive blip settings:**

```lua
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):

```lua
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.

```lua
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:

```lua
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.

```lua
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:**

```lua
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:**

```lua
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.

```lua
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):**

```lua
RequiredHoneyCount = 10,
RewardQuantity = 5,
```

***

**config\_mixer.lua — Honey Mixer**

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

```lua
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.

```lua
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:**

```lua
ClothingEnabled = false
```

**Make bees more aggressive:**

```lua
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):**

```lua
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:**

```lua
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

{% embed url="<https://youtu.be/pr_mrR3DR1w>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://risk-scripts.gitbook.io/risk-scripts/scripts/beekeeping-script.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.