# Guide

#### Setup Instructions

1. Download the resource
2. Extract the `sanba-mysterybox` folder to your server's resources directory
3. Add `ensure sanba-mysterybox` to your `server.cfg` file
4. Configure the settings in `shared/config.lua`
5. Set up your Discord webhook for logging
6. Restart your server

### Configuration

#### Main Configuration

The main configuration file is located at `shared/config.lua`. Here you can adjust various settings:

```lua
Config = {}

-- Animation settings
Config.Duration = 1000 -- Duration of the spinning animation in milliseconds

-- Framework auto-detection (will be set automatically)
Config.Framework = nil -- 'qb', 'qbx', 'esx', or nil if not detected

-- Mystery box items
Config.Boxes = {
    'mystery_box',
    'mystery_box_2',
}

-- Logging configuration
Config.Logs = {
    Enabled = true,
    WebhookURL = "YOUR_DISCORD_WEBHOOK_URL_HERE",
    LogColors = {
        Open = 3447003,     -- Blue
        Reward = 5763719,   -- Green
        Error = 15548997    -- Red
    },
}
```

#### Configuring Box Items

You can configure the items that players can win from mystery boxes by editing the `Config.BoxItems` section:

```lua
-- Box items configuration
Config.BoxItems = {
    items = {
        ["burger"] = {
            name = "Burger ham",
            chance = 30,  -- Probability of winning (higher number = more likely)
            imageurl = 'https://cfx-nui-ox_inventory/web/images/burger.png',
            amount = 10,  -- Amount of the item the player receives
        },
        ["weapon_pistol"] = {
            name = "Pistol",
            chance = 25,
            imageurl = 'https://cfx-nui-ox_inventory/web/images/weapon_pistol.png',
            amount = 5,
        },
        -- Add more items as needed
    }
}
```

#### Item Properties

* `name`: Display name of the item
* `chance`: Probability weight for this item (higher numbers = higher chance)
* `imageurl`: URL to the item's image (can use inventory image paths)
* `amount`: Quantity of the item to give to the player

### Framework Integration

The system automatically detects and adapts to the framework your server is using:

#### QBCore/QBX

For QBCore and QBX servers, the script will automatically register usable items and handle inventory operations through the core functions.

#### ESX

For ESX servers, the script will use the ESX item system and money handling functions.

### Discord Logging

The script includes a Discord webhook integration to log all box openings and rewards.

#### Setting Up Logging

1. Create a webhook in your Discord server (Server Settings → Integrations → Webhooks)
2. Copy the webhook URL
3. Paste the URL in the `Config.Logs.WebhookURL` field in `config.lua`

#### Log Types

* **Box Open**: Triggered when a player opens a mystery box
* **Reward Given**: Triggered when a player receives a reward
* **Error**: Triggered when there's an issue with processing rewards

### Adding New Mystery Boxes

To add new mystery box types:

1. Add the item to your server's items database according to your framework
2. Add the item name to `Config.Boxes` in `config.lua`
3. Configure the item in your inventory system
4. Restart the resource

Example for adding a new box type:

```lua
Config.Boxes = {
    'mystery_box',
    'mystery_box_2',
    'premium_mystery_box' -- New box type
}
```

### Special Items

#### Money Rewards

The system has special handling for money rewards. If an item has the key "money", it will add cash to the player instead of an inventory item.

```lua
["money"] = {
    name = "Cash",
    chance = 100,
    imageurl = 'https://cfx-nui-ox_inventory/web/images/money.png',
    amount = 10000, -- Amount of cash to add
},
```


---

# 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://sanbascripts.gitbook.io/bytestake/mystery-box-system/guide.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.