> For the complete documentation index, see [llms.txt](https://tyrix.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tyrix.gitbook.io/docs/script-resources/tyrix-dice/item-setup.md).

# Item Setup

When using `Config.DiceMode = 'item'` or `'both'`, you need to add dice items to your inventory system.

## Available Items

| Item Name      | Label        | Description       |
| -------------- | ------------ | ----------------- |
| `dice_white_1` | 1 White Die  | Roll 1 white die  |
| `dice_white_2` | 2 White Dice | Roll 2 white dice |
| `dice_white_3` | 3 White Dice | Roll 3 white dice |
| `dice_black_1` | 1 Black Die  | Roll 1 black die  |
| `dice_black_2` | 2 Black Dice | Roll 2 black dice |
| `dice_black_3` | 3 Black Dice | Roll 3 black dice |
| `dice_red_1`   | 1 Red Die    | Roll 1 red die    |
| `dice_red_2`   | 2 Red Dice   | Roll 2 red dice   |
| `dice_red_3`   | 3 Red Dice   | Roll 3 red dice   |

## Included Files

The `install/` folder contains ready-to-use files:

| File                | Purpose                        |
| ------------------- | ------------------------------ |
| `install/items.lua` | ox\_inventory item definitions |
| `install/images/`   | 9 item icons (PNG)             |

## Item Images

{% file src="/files/IAllTVOA75ivYaNiTGYb" %}

## ox\_inventory Setup

### Quick Install

{% stepper %}
{% step %}
Open `install/items.lua`
{% endstep %}

{% step %}
Copy all contents
{% endstep %}

{% step %}
Paste into `ox_inventory/data/items.lua`
{% endstep %}

{% step %}
Copy all images from `install/images/`
{% endstep %}

{% step %}
Paste into `ox_inventory/web/images/`
{% endstep %}

{% step %}
Restart server or refresh inventory
{% endstep %}
{% endstepper %}

### Item Definitions

Add to `ox_inventory/data/items.lua`:

```lua
['dice_white_1'] = {label = '1 White Die', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_white_1'}},
['dice_white_2'] = {label = '2 White Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_white_2'}},
['dice_white_3'] = {label = '3 White Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_white_3'}},
['dice_black_1'] = {label = '1 Black Die', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_black_1'}},
['dice_black_2'] = {label = '2 Black Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_black_2'}},
['dice_black_3'] = {label = '3 Black Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_black_3'}},
['dice_red_1'] = {label = '1 Red Die', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_red_1'}},
['dice_red_2'] = {label = '2 Red Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_red_2'}},
['dice_red_3'] = {label = '3 Red Dice', weight = 50, stack = true, close = true, server = {export = 'tyrix_dice.dice_red_3'}},
```

## QBCore Setup

### Item Definitions

Add to `qb-core/shared/items.lua`:

```lua
['dice_white_1'] = {name = 'dice_white_1', label = '1 White Die', weight = 50, type = 'item', image = 'dice_white_1.png', unique = false, useable = true, shouldClose = true, description = 'Roll 1 white die'},
['dice_white_2'] = {name = 'dice_white_2', label = '2 White Dice', weight = 50, type = 'item', image = 'dice_white_2.png', unique = false, useable = true, shouldClose = true, description = 'Roll 2 white dice'},
['dice_white_3'] = {name = 'dice_white_3', label = '3 White Dice', weight = 50, type = 'item', image = 'dice_white_3.png', unique = false, useable = true, shouldClose = true, description = 'Roll 3 white dice'},
['dice_black_1'] = {name = 'dice_black_1', label = '1 Black Die', weight = 50, type = 'item', image = 'dice_black_1.png', unique = false, useable = true, shouldClose = true, description = 'Roll 1 black die'},
['dice_black_2'] = {name = 'dice_black_2', label = '2 Black Dice', weight = 50, type = 'item', image = 'dice_black_2.png', unique = false, useable = true, shouldClose = true, description = 'Roll 2 black dice'},
['dice_black_3'] = {name = 'dice_black_3', label = '3 Black Dice', weight = 50, type = 'item', image = 'dice_black_3.png', unique = false, useable = true, shouldClose = true, description = 'Roll 3 black dice'},
['dice_red_1'] = {name = 'dice_red_1', label = '1 Red Die', weight = 50, type = 'item', image = 'dice_red_1.png', unique = false, useable = true, shouldClose = true, description = 'Roll 1 red die'},
['dice_red_2'] = {name = 'dice_red_2', label = '2 Red Dice', weight = 50, type = 'item', image = 'dice_red_2.png', unique = false, useable = true, shouldClose = true, description = 'Roll 2 red dice'},
['dice_red_3'] = {name = 'dice_red_3', label = '3 Red Dice', weight = 50, type = 'item', image = 'dice_red_3.png', unique = false, useable = true, shouldClose = true, description = 'Roll 3 red dice'},
```

### Images

Copy images from `install/images/` to your QBCore inventory's image folder:

* `qb-inventory/html/images/` (default qb-inventory)
* Or your custom inventory's image location

## ESX Setup

### Registering Items

For ESX, items are typically added to your database. The script will auto-register useable items on startup.

Add to your items database table:

```sql
INSERT INTO `items` (`name`, `label`, `weight`) VALUES
('dice_white_1', '1 White Die', 50),
('dice_white_2', '2 White Dice', 50),
('dice_white_3', '3 White Dice', 50),
('dice_black_1', '1 Black Die', 50),
('dice_black_2', '2 Black Dice', 50),
('dice_black_3', '3 Black Dice', 50),
('dice_red_1', '1 Red Die', 50),
('dice_red_2', '2 Red Dice', 50),
('dice_red_3', '3 Red Dice', 50);
```

### Images

Copy images to your ESX inventory's image folder.

## Item Behavior

### ConsumeItem Setting

| Setting | On Use       | On Pickup     |
| ------- | ------------ | ------------- |
| `true`  | Item removed | Item returned |
| `false` | Item stays   | Nothing       |

### Anti-Exploit Protection

The server validates all item returns:

* Only the item you used can be returned
* Only one return per roll
* Cleared on disconnect or new roll

## Giving Items (Admin)

### ox\_inventory

```
/giveitem [id] dice_white_2 1
```

### QBCore

```
/giveitem [id] dice_white_2 1
```

### ESX

```
/giveitem [id] dice_white_2 1
```

## Troubleshooting

<details>

<summary>Items not working</summary>

* Verify `Config.DiceMode` is `'item'` or `'both'`
* Check server console for inventory system detection message
* Ensure items are properly added to your inventory system

</details>

<details>

<summary>Images not showing</summary>

* Verify images are in correct folder
* Check image filenames match exactly (case-sensitive)
* Refresh/restart inventory resource

</details>

<details>

<summary>Items not consumed</summary>

* Check `Config.ConsumeItem` setting
* For ox\_inventory, ensure `close = true` in item definition

</details>