> For the complete documentation index, see [llms.txt](https://prfortiq.gitbook.io/wolfstudio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prfortiq.gitbook.io/wolfstudio/fivem/ws-advanced-inventory-system.md).
# WS Advanced Inventory System
WS Inventory is a modern inventory system for FiveM. It includes an inventory UI, hotbar, vehicle inventories, stashes, drops, crafting, player statistics/attributes, and an integrated ticket system.
Resource name: `ws-inventory`\
Frameworks: QBCore and ESX\
QBox: planned for a later update\
Database: oxmysql\
Recommended for: roleplay servers that need a custom inventory, crafting, and support system
***
### Key features
* Modern inventory with weight and slots
* Hotbar for quick item usage
* Use, move, drop, and give items
* Stashes, trunk, and glovebox support
* Crafting system with level, XP, chance, and crafting time
* Player statistics and attributes
* Ticket system inside the inventory
* Separate admin ticket UI via `/admintickets`
* ESX support with custom food and drink configuration
* QBCore support
* QBox support planned for a later update
* Item images through the images folder
* SQL storage for tickets, progress, and inventories
***
### Requirements
Required:
* FiveM server
* oxmysql
* QBCore or ESX
Optional:
* esx\_status for ESX hunger and thirst
* esx\_basicneeds if your server still uses BasicNeeds additionally
* qb-target if target features are used
QBox is not listed as a required supported framework yet, because QBox support will be added in a later update.
***
### Installation
1. Upload the `ws-inventory` folder to your resources folder.
2. Import the included SQL file for WS Inventory.
3. If you use ESX and items are missing, also import the ESX item file.
4. Set your framework to QBCore or ESX.
5. Add the resource to your server start order.
6. Restart the server or the resource.
**Important:** `oxmysql` and your framework must start before `ws-inventory`.
***
### Configuration guide
This section explains the most important configuration options and shows small config examples. Only configuration files are shown here. No client or server code changes are required for normal setup.
Configuration files:
* `config/framework.lua` for framework selection and item aliases
* `config/config.lua` for inventory limits, keybinds, usable items, database options, crafting, attributes, and player progress
* `config/vehicles.lua` for trunk and glovebox storage
After changing any config file, restart the resource or restart the server.
***
#### Framework selection
Use this setting to tell WS Inventory which framework your server uses.
Supported now:
* `qbcore`
* `esx`
QBox is planned for a later update and should not be used yet unless an official QBox-ready version is provided.
Example:
```lua
Config.Framework = {
Type = 'esx', -- options: 'qbcore', 'esx'
ResourceNames = {
qbcore = 'qb-core',
esx = 'es_extended',
},
InventoryResource = 'ws-inventory',
Debug = false,
}
```
Use `Type = 'esx'` for ESX servers.
Use `Type = 'qbcore'` for QBCore servers.
Turn `Debug = true` only while testing or troubleshooting.
***
#### Item aliases
Aliases are used when different frameworks use different item names. This is important for ESX, because ESX often uses `water` and `bread`, while QBCore-style configs often use `water_bottle` and `sandwich`.
Example:
```lua
Config.Framework.ItemAliases = {
esx = {
water_bottle = 'water',
sandwich = 'bread',
repairkit = 'fixkit',
armor = 'bulletproof',
metalscrap = 'metal',
steel = 'iron',
},
qbcore = {},
}
```
How to use this:
* Left side: item name used by WS Inventory, crafting, shop, or UI
* Right side: real item name used by your framework database
Example: if the recipe creates `water_bottle`, but your ESX item is called `water`, keep `water_bottle = 'water'`.
***
#### Basic inventory limits
These settings control the default player inventory weight and slot count.
Example:
```lua
Config.MaxWeight = 120000 -- 120 kg in grams
Config.MaxSlots = 40
```
How to adjust it:
* Increase `MaxWeight` if players should carry more items
* Decrease `MaxWeight` for a stricter economy
* Increase `MaxSlots` if players need more inventory slots
* Decrease `MaxSlots` for a cleaner and more limited inventory
Common examples:
```lua
Config.MaxWeight = 80000 -- 80 kg
Config.MaxSlots = 35
```
```lua
Config.MaxWeight = 150000 -- 150 kg
Config.MaxSlots = 50
```
***
#### Stash storage
These settings control the default stash size.
Example:
```lua
Config.StashSize = {
maxweight = 2000000,
slots = 100
}
```
Use this for job storages, gang storages, house storages, business storages, or other shared storage systems.
Recommended values:
```lua
Config.StashSize = {
maxweight = 500000,
slots = 50
}
```
For large shared storages:
```lua
Config.StashSize = {
maxweight = 2500000,
slots = 150
}
```
***
#### Drop storage
Drops are items placed on the ground.
Example:
```lua
Config.DropSize = {
maxweight = 1000000,
slots = 50
}
Config.CleanupDropTime = 15
Config.CleanupDropInterval = 1
```
Meaning:
* `maxweight` controls how much weight one drop can hold
* `slots` controls how many item slots one drop can hold
* `CleanupDropTime` is the time in minutes before old drops are cleaned
* `CleanupDropInterval` is how often the cleanup check runs
For performance-friendly servers, keep cleanup enabled and do not set the cleanup time too high.
***
#### Keybinds
These settings control the inventory open key and hotbar key.
Example:
```lua
Config.Keybinds = {
Open = 'F2',
Hotbar = 'Z',
}
```
Common options:
```lua
Config.Keybinds = {
Open = 'TAB',
Hotbar = 'Z',
}
```
```lua
Config.Keybinds = {
Open = 'F2',
Hotbar = 'X',
}
```
Make sure your chosen keys do not conflict with other resources.
***
#### Target settings
If you use a target resource, enable target support and set the correct target resource name.
Example:
```lua
Config.UseTarget = true
Config.TargetResource = 'qb-target'
```
Without target:
```lua
Config.UseTarget = false
Config.TargetResource = 'qb-target'
```
Use the exact resource name your server starts.
***
#### ESX food and drink items
WS Inventory can handle food and drink directly from its own config. This is useful when ESX usable items do not trigger correctly.
Example:
```lua
Config.UsableItems = {
Enabled = true,
RefreshAfterUse = true,
CloseInventoryAfterUse = true,
UseOwnClientEffect = true,
AlsoTriggerESXBasicNeeds = false,
Items = {
bread = {
label = 'Bread',
type = 'food',
status = 'hunger',
amount = 200000,
remove = 1,
notify = 'You ate bread.',
},
water = {
label = 'Water',
type = 'drink',
status = 'thirst',
amount = 200000,
remove = 1,
notify = 'You drank water.',
},
sandwich = { alias = 'bread' },
water_bottle = { alias = 'water' },
}
}
```
Meaning:
* `Enabled = true` enables WS Inventory usable items
* `status = 'hunger'` increases hunger
* `status = 'thirst'` increases thirst
* `amount = 200000` controls how much status is added
* `remove = 1` removes one item after use
* `alias` lets another item name use the same settings
If you use ESX, make sure these items also exist in your ESX items table.
Example for adding another drink:
```lua
Config.UsableItems.Items.cola = {
label = 'Cola',
type = 'drink',
status = 'thirst',
amount = 150000,
remove = 1,
notify = 'You drank cola.',
}
```
Example for adding another food item:
```lua
Config.UsableItems.Items.burger = {
label = 'Burger',
type = 'food',
status = 'hunger',
amount = 250000,
remove = 1,
notify = 'You ate a burger.',
}
```
***
#### Database options
These settings control optional WS Inventory database features.
Example:
```lua
Config.Database = {
Tickets = {
Enabled = true,
FallbackToMemory = true,
MaxTicketsPerPlayer = 25,
},
Attributes = {
Enabled = true,
MirrorToSql = true,
LogChanges = true,
}
}
```
Meaning:
* `Tickets.Enabled` enables the ticket system database storage
* `FallbackToMemory` keeps tickets working temporarily if SQL has a problem
* `MaxTicketsPerPlayer` limits how many tickets one player can have
* `Attributes.Enabled` enables player attributes
* `MirrorToSql` mirrors metadata into SQL if the database extension is imported
* `LogChanges` stores attribute changes for easier support and tracking
***
#### Crafting basics
Crafting can be enabled or disabled here.
Example:
```lua
Config.Crafting = {
Enabled = true,
Leveling = {
Enabled = true,
BaseXp = 20,
XpIncrease = 15,
AfterLevel10Increase = 35,
DefaultRecipeXp = 5,
DefaultChance = 100,
},
}
```
Meaning:
* `Enabled = true` enables crafting
* `Leveling.Enabled = true` enables crafting levels and XP
* `BaseXp` is the XP needed for the first level
* `XpIncrease` increases the XP requirement for each level
* `DefaultRecipeXp` is used when a recipe has no custom XP value
* `DefaultChance` is used when a recipe has no custom chance value
***
#### Crafting categories
Categories are shown in the crafting UI filter.
Example:
```lua
Config.Crafting.Categories = {
{ value = 'all', label = 'ALL' },
{ value = 'medical', label = 'MEDICAL' },
{ value = 'tools', label = 'TOOLS' },
{ value = 'survival', label = 'SURVIVAL' },
{ value = 'equipment', label = 'EQUIPMENT' },
}
```
To add a new category:
```lua
{ value = 'weapons', label = 'WEAPONS' },
```
After adding a category, recipes can use it with `category = 'weapons'`.
***
#### Crafting recipe example
A recipe defines what item is created and which materials are needed.
Example:
```lua
{
name = 'bandage',
label = 'BANDAGE',
description = 'Restores a small amount of health.',
image = 'bandage.png',
category = 'medical',
amount = 1,
craftTime = 2,
level = 1,
xp = 5,
chance = 100,
requirements = {
{ item = 'plastic', label = 'CLOTH', amount = 2, image = 'plastic.png' },
{ item = 'rubber', label = 'TAPE', amount = 1, image = 'rubber.png' },
}
}
```
Meaning:
* `name` is the real item name that will be added to the inventory
* `label` is the display name in the crafting UI
* `image` must exist in the item images folder
* `category` decides where the recipe appears
* `amount` is how many items the player receives
* `craftTime` is the crafting time in seconds
* `level` is the required crafting level
* `xp` is the XP reward
* `chance` is the success chance in percent
* `requirements` are the items removed when crafting
**Important:** Every item inside `name` and `requirements` must exist in your framework item list.
***
#### Weapon or armor crafting example
Example:
```lua
{
name = 'armor',
label = 'ARMOR',
description = 'A light protective vest.',
image = 'armor.png',
category = 'equipment',
amount = 1,
craftTime = 8,
level = 4,
xp = 18,
chance = 88,
requirements = {
{ item = 'metalscrap', label = 'METAL SCRAP', amount = 8, image = 'metalscrap.png' },
{ item = 'rubber', label = 'RUBBER', amount = 4, image = 'rubber.png' },
{ item = 'plastic', label = 'PLASTIC', amount = 4, image = 'plastic.png' },
}
}
```
For ESX, check your item aliases. If your ESX armor item is called `bulletproof`, you can map `armor = 'bulletproof'` in the alias config.
***
#### Attributes
Attributes control player stats such as strength, stamina, shooting, driving, flying, and stealth.
Example:
```lua
Config.Attributes = {
Enabled = true,
MaxValue = 100,
PointValue = 5,
InitialPoints = 0,
Defaults = {
strength = 45,
stamina = 60,
shooting = 55,
driving = 70,
flying = 30,
stealth = 50,
}
}
```
Meaning:
* `MaxValue` is the maximum value per attribute
* `PointValue` is how much one attribute point increases a stat
* `InitialPoints` is how many free points new players start with
* `Defaults` are the default starting attribute values
***
#### Attribute benefits
Benefits control what attributes actually change in gameplay.
Example:
```lua
Config.Attributes.Benefits = {
CarryWeightPerStrengthPoint = 600,
SprintMultiplierAtMaxStamina = 0.08,
StaminaRestoreAtMaxStamina = 0.22,
WeaponDamageAtMaxShooting = 0.08,
VehiclePowerAtMaxDriving = 12.0,
AirVehiclePowerAtMaxFlying = 12.0,
SneakNoiseReductionAtMaxStealth = 0.25,
}
```
Set a value to `0` if you want to disable that benefit.
Example:
```lua
WeaponDamageAtMaxShooting = 0,
```
***
#### Player progress
Player progress controls the general level and XP shown on the statistics page.
Example:
```lua
Config.PlayerProgress = {
Enabled = true,
HourlyXp = {
Enabled = true,
XpPerHour = 10,
GrantMinute = 0,
Notify = true,
},
BaseXp = 50,
XpIncrease = 25,
AfterLevel10Increase = 50,
}
```
Meaning:
* `HourlyXp.Enabled` gives automatic XP every hour
* `XpPerHour` controls how much XP is given
* `GrantMinute = 0` gives XP at every full hour
* `BaseXp` controls the first level requirement
* `XpIncrease` controls how much harder each next level becomes
***
#### Vehicle storage
Vehicle storage is configured by vehicle class.
Example:
```lua
VehicleStorage = {
default = {
gloveboxSlots = 5,
gloveboxWeight = 10000,
trunkSlots = 35,
trunkWeight = 60000
},
[0] = { -- Compacts
gloveboxSlots = 5,
gloveboxWeight = 10000,
trunkSlots = 30,
trunkWeight = 38000
},
[2] = { -- SUVs
gloveboxSlots = 5,
gloveboxWeight = 10000,
trunkSlots = 50,
trunkWeight = 75000
}
}
```
Meaning:
* `gloveboxSlots` controls glovebox slot count
* `gloveboxWeight` controls glovebox weight
* `trunkSlots` controls trunk slot count
* `trunkWeight` controls trunk weight
Use `0` slots and `0` weight if a vehicle class should not have storage.
Example:
```lua
[13] = { -- Cycles
gloveboxSlots = 0,
gloveboxWeight = 0,
trunkSlots = 0,
trunkWeight = 0
},
```
***
#### Back engine vehicles
Some vehicles have the engine at the back. This list is used so trunk interaction can be placed correctly.
Example:
```lua
BackEngineVehicles = {
[`adder`] = true,
[`t20`] = true,
[`zentorno`] = true,
}
```
Add vehicles here if the trunk interaction appears at the wrong side of the vehicle.
***
#### Recommended config checklist
Before going live, check these points:
* Correct framework selected
* QBox not used until the official QBox update is available
* All item names exist in your framework item table
* ESX item aliases match your ESX item names
* Bread and water exist in ESX if you use ESX food and drink
* Item images match the exact item names
* Crafting output items exist
* Crafting material items exist
* Vehicle storage values fit your economy
* Ticket database options are enabled if you use tickets
* oxmysql starts before WS Inventory
***
### Recommended start order
**ESX:**
1. oxmysql
2. es\_extended
3. esx\_status
4. esx\_basicneeds, if used
5. ws-inventory
**QBCore:**
1. oxmysql
2. qb-core
3. ws-inventory
**QBox:**
QBox support is planned for a later update. Do not use WS Inventory on QBox until QBox support is officially enabled.
***
### Framework setting
WS Inventory currently supports:
* ESX
* QBCore
* Auto detection
QBox support is planned for a later update.
A fixed framework type is recommended. Use auto detection only when your framework resources can be detected clearly and reliably.
***
### ESX food and drink
WS Inventory includes its own configuration for usable items such as bread and water. This allows food and drink items to be handled directly through WS Inventory.
Default items:
* bread as food
* water as drink
* sandwich as a food alias
* water\_bottle as a water alias
For food and drink to work, the items must exist in your ESX item list and `esx_status` must be running.
***
### Crafting system
The crafting system supports:
* Recipe categories
* Required materials
* Crafting time
* Required crafting level
* XP reward
* Success chance
* Queue for crafted items
* ESX and QBCore item aliases
**Important:** All output items and required materials must exist in your framework.
***
### Ticket system
Players can create and reply to tickets inside the inventory.
Admins can additionally manage tickets through `/admintickets`.
Player options:
* Create a ticket
* View own tickets
* Read messages
* Reply to tickets
Admin options:
* View all tickets
* Open tickets
* Reply
* Change status
* Close tickets
* Delete tickets
Ticket statuses:
* Open
* In progress
* Closed
***
### Statistics and attributes
WS Inventory includes a player progress and attribute system.
Included attributes:
* Strength
* Stamina
* Shooting
* Driving
* Flying
* Stealth
The system can be used for weight, stamina, vehicle values, and other server features.
***
### Commands
Player commands:
* `/inventory` opens the inventory
* `/hotbar` shows the hotbar
* `/closeInv` closes the inventory
Admin commands:
* `/giveitem` gives an item to a player
* `/clearinv` clears an inventory
* `/giveattrpoints` gives attribute points
* `/admintickets` opens the admin ticket UI
***
### Item images
Item images must be placed in the images folder.
Important:
* The file name must match the item name.
* Uppercase and lowercase letters matter.
* The image should be available as PNG.
* Missing images will cause items to appear without an icon.
Examples:
* bread.png
* water.png
* bandage.png
* lockpick.png
***
### Update notes
When updating, always replace the full resource folder.
Recommended update process:
1. Stop the server.
2. Back up the old folder.
3. Upload the new version.
4. Check the config.
5. Check or import database changes.
6. Start the server.
Not recommended:
* Mixing single files from different versions
* Replacing only UI files
* Using an old config without checking it
* Running multiple inventory systems at the same time
***
### Common issues
Inventory does not open
Check whether oxmysql, your framework, and ws-inventory are starting in the correct order.
Items have no image
Check whether the image exists inside the images folder and has the exact same name as the item.
Crafting does not work
Check whether the crafted item and all required materials exist in your framework.
ESX food or drink does not work
Check whether bread and water exist in your ESX item list and whether esx\_status starts before ws-inventory.
Tickets do not load
Check whether the SQL files were imported and the resource was fully restarted.
***
### Support checklist
Always include this information when requesting support:
* Used framework
* Server console errors
* Client F8 errors
* Used resource version
* Affected item name or affected feature
* Whether the SQL files were imported
***
### Credits
WS Inventory is based on a QBCore inventory foundation and was extended by WS Development.
Extensions:
* ESX compatibility
* Crafting system
* Ticket system
* Admin ticket UI
* Statistics and attribute system
* Custom food and drink config
* UI redesign
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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://prfortiq.gitbook.io/wolfstudio/fivem/ws-advanced-inventory-system.md?ask=
```
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.