AS-01Documentação
Astra Inventory
Install, configure and extend Astra Inventory on ESX, QBCore or Qbox.
Overview
Astra Inventory is the inventory window for your server. It reads and writes items through your framework (or through ox_inventory if you run it), so your existing items and player data keep working.
| Edition | What it is |
|---|---|
| Free | Inventory grid, use and give items, drops, stashes, hotbar, themes and layouts. |
| Pro | Everything in Free plus shops, trading, clothing, 3D weapon inspect, item discovery and the admin panel. Core Lua is protected by Cfx.re Asset Escrow. |
| Source | Everything in Pro with every Lua and NUI file open. |
Sections marked Pro apply to the Pro and Source editions.
Requirements
- A FiveM server with a recent artifact (Asset Escrow needs an up-to-date server build).
oxmysql- One framework: ESX Legacy (
es_extended), QBCore (qb-core) or Qbox (qbx_core) - Optional:
ox_inventory, used as the item backend when it is running
Installation
- Download the asset from the Cfx.re Portal under Granted Assets.
- Extract it and place the
astra_inventoryfolder in yourresourcesdirectory. Keep the folder name. - Start it after
oxmysqland your framework inserver.cfg:
ensure oxmysql
ensure es_extended # or qb-core / qbx_core
ensure ox_inventory # only if you use it as the backend
ensure astra_inventory- Stop the inventory window you used before (for example
esx_inventoryorqb-inventory) so two inventories do not open on the same key. - Start the server. The database tables (prefix
astra_inv_) are created on first start.
First start
Join the server and press F2 to open the inventory. Players can rebind the key in GTA Settings → Key Bindings → FiveM.
| Key | Action |
|---|---|
| F2 | Open or close the inventory |
| 1 – 5 | Use hotbar slots |
| TAB (hold) | Show the hotbar |
| G | Give the hovered item to the nearest player |
| Shift + click | Select several items |
| Ctrl + click | Move an item to the other inventory |
| Y / N | Accept or decline a trade request Pro |
| E | Open a shop Pro |
Configuration
Everything is set in config.lua, which stays editable in every edition. Restart the resource after a change.
Framework and backend
Config.Framework = 'auto' -- 'auto', 'esx', 'qb' or 'qbx'
Config.Backend = 'auto' -- 'auto', 'esx', 'qb' or 'ox'
Config.Locale = 'en' -- 'en', 'pt', 'es', 'fr', 'de', 'it', 'nl', 'pl', 'tr'
Config.OpenKey = 'F2'auto detects the framework that is running, and uses ox_inventory as the backend when it is started.
Interface
-- Edit the existing entries in config.lua
Config.UI.layout = 'classic'
Config.UI.style = 'graphite'
Config.UI.PlayerSettings = true
Config.UI.PlayerCanChange.style = true
Config.UI.PlayerCanChange.layout = trueFree, Pro and Source include the same 19 themes and 13 layouts. Settings for ordinary players are off by default. Enable them with PlayerSettings and use PlayerCanChange to allow individual options.
Theme IDs graphite, glass, midnight, tactical, neon, frost, ember, rose, lilac, slate, carbon, marine, forest, sandstone, pearl, mist, plum, terracotta, arctic. Use auto to switch to Glass at 07:00 and Midnight at 20:00 on the in-game clock.
Layout IDs classic, tactical, compact, balanced, cockpit, equipment, field, inspector, wide, dense, drawer, station, gallery.
Hotbar, giving and drops
Config.Hotbar = {
slots = 5,
style = 'angled', -- 'angled', 'rounded' or 'minimal'
alwaysVisible = true,
showKey = 'TAB',
disableWeaponWheel = true, -- weapons live in the hotbar
}
Config.Give = { distance = 3.0, hoverKey = 'G' }
Config.Drops = {
lifetime = 30, -- minutes an untouched drop stays on the ground
maxPerPlayer = 15,
openRadius = 2.2,
slots = 30,
}Pro features Pro
| Block | Controls |
|---|---|
Config.Discovery | Item discovery: on or off, where it applies, seconds per rarity |
Config.Place | Placing items in the world: distance and default model |
Config.Trade | Trading: distance, request timeout, accept and decline keys |
Config.Weapon | 3D weapon inspect, stats, tint items and QBCore attachment items |
Config.Clothing | Clothing items, backpack slots and weight, armour plates |
Items
Items come from your framework. shared/items.lua only adds how they look in the inventory, and every key is optional.
Items = {
water = { rarity = 'common', category = 'food', prop = 'prop_ld_flow_bottle' },
diamond = { rarity = 'legendary', category = 'valuable' },
lockpick = { rarity = 'uncommon', category = 'tool', canThrow = false },
}| Key | Meaning |
|---|---|
rarity | common, uncommon, unique, rare, epic, legendary or mythic |
category | Text shown in the tooltip |
description | Tooltip text |
prop | Model used when the item is placed on the ground |
image | Picture name in html/images when it differs from the item name |
canRename, canThrow, canPlaceOnGround | Per-item switches |
Items that are not listed get a category and rarity from ItemRules in the same file, matched on the item name. Rarity colours are set in Rarities.
Item pictures
Put a PNG named after the item in html/images, for example html/images/water.png. Weapons without a picture use the image from the FiveM docs.
Shops Pro
Shops are defined in shared/shops.lua, which stays editable in Pro. You can also create and edit them in game from the admin panel.
Config.Shop = {
enabled = true,
key = 'E',
interaction = 'prompt', -- 'prompt', 'ox_target', 'qb-target' or 'auto'
locations = {
strawberry = {
label = 'Strawberry Market',
locations = { { x = 25.72, y = -1347.28, z = 29.5, distance = 2.5 } },
payments = { cash = true, bank = true },
products = {
{ item = 'water', price = 10 },
{ item = 'bandage', price = 30, stock = 100 },
},
},
},
}Admin panel Pro
Open the panel with /invadmin, or from the Admin tab in the inventory. It manages players and their inventories, items, rarities, shops, stashes, clothing, default settings, permissions, translations and history, without a restart.
Who is an admin
- ESX: players in the
admin,superadminorownergroup - QBCore and Qbox: players with the
commandace - Any framework: players with the
astra_inventory.adminace
add_ace group.admin astra_inventory.admin allowAdmins can then give other players access to single sections from the Permissions tab.
Stashes and exports
Other resources can register stashes and open inventories through exports.
Server
-- register a stash once (for example when your resource starts)
exports.astra_inventory:RegisterStash('police_locker', {
label = 'Police locker',
slots = 40,
job = 'police',
})
-- open it for a player
exports.astra_inventory:OpenStorage(source, 'police_locker')
-- open another player's inventory (search)
exports.astra_inventory:OpenPlayer(source, targetId)| Export | Use |
|---|---|
RegisterStash(id, options) | Creates a stash. Options: label, slots, maxWeight, coords, distance, job, canAccess |
OpenStorage(source, id) | Opens a registered stash or storage for a player |
OpenPlayer(source, target) | Opens the target player's inventory for source |
RegisterStorage(id, definition) | Advanced: a storage backed by your own functions (canAccess, getItems, putItem, takeItem) |
Client
exports.astra_inventory:OpenInventory()
exports.astra_inventory:CloseInventory()
local open = exports.astra_inventory:IsOpen()Using ox_inventory
When ox_inventory is running and Config.Backend is 'auto' or 'ox', it keeps the items and Astra Inventory is the window. The ox window stays closed while Config.Ox.hideNativeUI is true.
For the clothing system Pro, add the item definitions from ox_inventory_clothing.lua to ox_inventory/data/items.lua and restart ox_inventory. In Pro the file is in the ox_inventory integration folder of your download; in Source it is in integrations/.
Changing edition
- Back up your
config.luaandshared/items.lua. - Stop the server and replace the
astra_inventoryfolder with the new edition. - Copy your settings into the new
config.lua. Pro and Source have more options, so do not overwrite the whole file with the Free one. - Start the server. Player data is kept, because all editions use the same tables.
Troubleshooting
The inventory does not open
- Check that
oxmysqland your framework start beforeastra_inventory. - Make sure your old inventory resource is stopped.
- Open the client console with F8 and the server console, and look for lines starting with
[astra_inventory].
The resource fails to start with an escrow or entitlement error
- The server licence key must belong to the Cfx.re account that owns the asset.
- Update the server artifact, then restart the server.
- Do not rename files that are protected or change the folder structure.
An item has no picture
Add html/images/<item name>.png, or set image for that item in shared/items.lua.
Two inventories open at once
Another inventory is still bound to the same key. Stop it, or change Config.OpenKey.