Skip to content

Commit 83ec5f0

Browse files
DemiAutomaticDemiAutomatic
committed
Add Item Setup docs and update examples
1 parent ff509d5 commit 83ec5f0

3 files changed

Lines changed: 273 additions & 10 deletions

File tree

‎pages/lootbox/_meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"configuration": "Configuration",
33
"framework-setup": "Framework Setup",
4+
"item-setup": "Item Setup",
45
"exports": "Exports",
56
"examples": "Examples"
67
}

‎pages/lootbox/examples.mdx‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ exports.ox_target:addGlobalObject({
2525
-- Server side
2626
RegisterNetEvent('lootbox:openCrate', function()
2727
local src = source
28-
if exports.ox_inventory:GetItem(src, 'mystery_crate_item', false, true) then
29-
exports.ox_inventory:RemoveItem(src, 'mystery_crate_item', 1)
28+
if exports.ox_inventory:RemoveItem(src, 'mystery_crate_item', 1) then
3029
exports.sleepless_lootbox:open(src, 'mystery_crate_item', true)
3130
end
3231
end)
@@ -69,12 +68,6 @@ Dynamically register a lootbox at runtime from a separate resource, for example
6968

7069
```lua
7170
-- Server side
72-
CreateThread(function()
73-
-- Wait for sleepless_lootbox to be ready
74-
while GetResourceState('sleepless_lootbox') ~= 'started' do
75-
Wait(100)
76-
end
77-
7871
exports.sleepless_lootbox:registerLootbox('event_box', {
7972
label = 'Holiday Event Box',
8073
description = 'Limited-time holiday rewards!',
@@ -87,11 +80,10 @@ CreateThread(function()
8780
{ 1, { name = 'WEAPON_PISTOL_MK2', amount = 1, rarity = 'legendary' } },
8881
},
8982
})
90-
end)
9183
```
9284

9385
<Callout type="warning">
94-
Make sure `sleepless_lootbox` is fully started before calling `registerLootbox`. Use a polling loop or `SetTimeout` to avoid race conditions.
86+
Make sure `sleepless_lootbox` is fully started before calling `registerLootbox`.
9587
</Callout>
9688

9789
## Safe Open with Rolling Check

‎pages/lootbox/item-setup.mdx‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
import { Callout } from 'nextra/components';
2+
import { Tabs, Tab } from 'nextra-theme-docs';
3+
4+
# Item Setup
5+
6+
This page provides complete item definitions for lootbox cases, including the optional **preview button** feature that allows players to see case contents before opening.
7+
8+
<Callout type="info">
9+
These item definitions should be added to your inventory system's item configuration file. The preview button feature is only available with **ox_inventory**.
10+
</Callout>
11+
12+
## ox_inventory Setup
13+
14+
When using ox_inventory, you can add a `buttons` array to your item definitions to provide additional actions. This is perfect for adding a "Preview Case" button that lets players see what's inside before they open it.
15+
16+
### Full Item Definition with Preview Button
17+
18+
```lua
19+
-- ox_inventory/data/items.lua
20+
21+
["gun_case"] = {
22+
label = "Gun Case",
23+
description = "Contains various firearms",
24+
weight = 500,
25+
stack = true,
26+
close = false,
27+
consume = 0,
28+
server = {
29+
export = "sleepless_lootbox.gun_case",
30+
},
31+
buttons = {
32+
{
33+
label = 'Preview Case',
34+
action = function(slot)
35+
exports.ox_inventory:closeInventory()
36+
exports.sleepless_lootbox:preview('gun_case')
37+
end
38+
},
39+
},
40+
},
41+
42+
["supply_crate"] = {
43+
label = "Supply Crate",
44+
description = "Contains useful supplies and materials",
45+
weight = 1000,
46+
stack = true,
47+
close = false,
48+
consume = 0,
49+
server = {
50+
export = "sleepless_lootbox.supply_crate",
51+
},
52+
buttons = {
53+
{
54+
label = 'Preview Case',
55+
action = function(slot)
56+
exports.ox_inventory:closeInventory()
57+
exports.sleepless_lootbox:preview('supply_crate')
58+
end
59+
},
60+
},
61+
},
62+
63+
["vip_case"] = {
64+
label = "VIP Case",
65+
description = "Premium rewards for VIP members",
66+
weight = 500,
67+
stack = true,
68+
close = false,
69+
consume = 0,
70+
server = {
71+
export = "sleepless_lootbox.vip_case",
72+
},
73+
buttons = {
74+
{
75+
label = 'Preview Case',
76+
action = function(slot)
77+
exports.ox_inventory:closeInventory()
78+
exports.sleepless_lootbox:preview('vip_case')
79+
end
80+
},
81+
},
82+
},
83+
```
84+
85+
### Preview Button Breakdown
86+
87+
```lua
88+
buttons = {
89+
{
90+
label = 'Preview Case', -- Button text shown in UI
91+
action = function(slot) -- Function called when clicked
92+
exports.ox_inventory:closeInventory() -- Close inventory first
93+
exports.sleepless_lootbox:preview('case_name') -- Open preview UI
94+
end
95+
},
96+
},
97+
```
98+
99+
<Callout type="warning">
100+
The case name passed to `exports.sleepless_lootbox:preview()` must match the lootbox key defined in your `config.lua` or registered via exports.
101+
</Callout>
102+
103+
## qb-inventory Setup
104+
105+
qb-inventory does not support the `buttons` feature natively. However, you can still provide preview functionality through other means (commands, keybinds, or custom UI).
106+
107+
### Basic Item Definitions
108+
109+
```lua
110+
-- qb-core/shared/items.lua
111+
112+
["gun_case"] = {
113+
name = "gun_case",
114+
label = "Gun Case",
115+
weight = 500,
116+
type = "item",
117+
image = "gun_case.png",
118+
unique = false,
119+
useable = true,
120+
shouldClose = true,
121+
combinable = nil,
122+
description = "Contains various firearms",
123+
},
124+
125+
["supply_crate"] = {
126+
name = "supply_crate",
127+
label = "Supply Crate",
128+
weight = 1000,
129+
type = "item",
130+
image = "supply_crate.png",
131+
unique = false,
132+
useable = true,
133+
shouldClose = true,
134+
combinable = nil,
135+
description = "Contains useful supplies and materials",
136+
},
137+
138+
["vip_case"] = {
139+
name = "vip_case",
140+
label = "VIP Case",
141+
weight = 500,
142+
type = "item",
143+
image = "vip_case.png",
144+
unique = false,
145+
useable = true,
146+
shouldClose = true,
147+
combinable = nil,
148+
description = "Premium rewards for VIP members",
149+
},
150+
```
151+
152+
### Adding Preview for qb-inventory
153+
154+
Since qb-inventory doesn't support item buttons, you can add preview functionality using a command or radial menu:
155+
156+
<Tabs items={['Command', 'Radial Menu']}>
157+
<Tab>
158+
```lua
159+
-- Client side
160+
RegisterCommand('previewcase', function(source, args)
161+
local caseName = args[1]
162+
if caseName then
163+
exports.sleepless_lootbox:preview(caseName)
164+
end
165+
end, false)
166+
```
167+
</Tab>
168+
<Tab>
169+
```lua
170+
-- Client side using ox_lib radial menu
171+
lib.registerRadial({
172+
id = 'lootbox_preview',
173+
items = {
174+
{
175+
label = 'Preview Gun Case',
176+
icon = 'eye',
177+
onSelect = function()
178+
exports.sleepless_lootbox:preview('gun_case')
179+
end
180+
},
181+
{
182+
label = 'Preview Supply Crate',
183+
icon = 'eye',
184+
onSelect = function()
185+
exports.sleepless_lootbox:preview('supply_crate')
186+
end
187+
},
188+
{
189+
label = 'Preview VIP Case',
190+
icon = 'eye',
191+
onSelect = function()
192+
exports.sleepless_lootbox:preview('vip_case')
193+
end
194+
},
195+
}
196+
})
197+
```
198+
</Tab>
199+
</Tabs>
200+
201+
## Adding Custom Lootbox Items
202+
203+
When you create a new lootbox in `config.lua`, you need to add a matching item definition. Here's the template:
204+
205+
<Tabs items={['ox_inventory', 'qb-inventory']}>
206+
<Tab>
207+
```lua
208+
["my_custom_case"] = {
209+
label = "My Custom Case",
210+
description = "Description of what's inside",
211+
weight = 500,
212+
stack = true,
213+
close = false,
214+
consume = 0,
215+
server = {
216+
export = "sleepless_lootbox.my_custom_case",
217+
},
218+
buttons = {
219+
{
220+
label = 'Preview Case',
221+
action = function(slot)
222+
exports.ox_inventory:closeInventory()
223+
exports.sleepless_lootbox:preview('my_custom_case')
224+
end
225+
},
226+
},
227+
},
228+
```
229+
</Tab>
230+
<Tab>
231+
```lua
232+
["my_custom_case"] = {
233+
name = "my_custom_case",
234+
label = "My Custom Case",
235+
weight = 500,
236+
type = "item",
237+
image = "my_custom_case.png",
238+
unique = false,
239+
useable = true,
240+
shouldClose = true,
241+
combinable = nil,
242+
description = "Description of what's inside",
243+
},
244+
```
245+
</Tab>
246+
</Tabs>
247+
248+
## Reference File
249+
250+
The resource includes a `_items.lua` reference file in its root directory containing example item definitions for both ox_inventory and qb-inventory. This file is **not loaded at runtime** — it's purely for reference.
251+
252+
## Troubleshooting
253+
254+
### Preview button doesn't appear
255+
256+
- Ensure you're using ox_inventory (buttons are an ox_inventory feature)
257+
- Verify the `buttons` array is properly formatted in your item definition
258+
- Restart ox_inventory after making changes to item definitions
259+
260+
### Preview shows empty or wrong items
261+
262+
- Verify the case name in the `preview()` call matches the lootbox key exactly
263+
- Check that the lootbox is defined in `config.lua` or registered via exports
264+
- Ensure sleepless_lootbox is started and running
265+
266+
### Item doesn't open when used
267+
268+
- For ox_inventory: Ensure `server.export` is set to `"sleepless_lootbox.<item_name>"`
269+
- For qb-inventory: Ensure `useable = true` in the item definition
270+
- See the [Framework Setup](/lootbox/framework-setup) page for detailed troubleshooting

0 commit comments

Comments
 (0)