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.

EditionWhat it is
FreeInventory grid, use and give items, drops, stashes, hotbar, themes and layouts.
ProEverything in Free plus shops, trading, clothing, 3D weapon inspect, item discovery and the admin panel. Core Lua is protected by Cfx.re Asset Escrow.
SourceEverything 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

  1. Download the asset from the Cfx.re Portal under Granted Assets.
  2. Extract it and place the astra_inventory folder in your resources directory. Keep the folder name.
  3. Start it after oxmysql and your framework in server.cfg:
server.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
  1. Stop the inventory window you used before (for example esx_inventory or qb-inventory) so two inventories do not open on the same key.
  2. 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.

KeyAction
F2Open or close the inventory
1 – 5Use hotbar slots
TAB (hold)Show the hotbar
GGive the hovered item to the nearest player
Shift + clickSelect several items
Ctrl + clickMove an item to the other inventory
Y / NAccept or decline a trade request Pro
EOpen 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.lua
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

config.lua
-- 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 = true

Free, 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.lua
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

BlockControls
Config.DiscoveryItem discovery: on or off, where it applies, seconds per rarity
Config.PlacePlacing items in the world: distance and default model
Config.TradeTrading: distance, request timeout, accept and decline keys
Config.Weapon3D weapon inspect, stats, tint items and QBCore attachment items
Config.ClothingClothing 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.

shared/items.lua
Items = {
    water   = { rarity = 'common',    category = 'food', prop = 'prop_ld_flow_bottle' },
    diamond = { rarity = 'legendary', category = 'valuable' },
    lockpick = { rarity = 'uncommon', category = 'tool', canThrow = false },
}
KeyMeaning
raritycommon, uncommon, unique, rare, epic, legendary or mythic
categoryText shown in the tooltip
descriptionTooltip text
propModel used when the item is placed on the ground
imagePicture name in html/images when it differs from the item name
canRename, canThrow, canPlaceOnGroundPer-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.

shared/shops.lua
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, superadmin or owner group
  • QBCore and Qbox: players with the command ace
  • Any framework: players with the astra_inventory.admin ace
server.cfg
add_ace group.admin astra_inventory.admin allow

Admins 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

server.lua
-- 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)
ExportUse
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

client.lua
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

  1. Back up your config.lua and shared/items.lua.
  2. Stop the server and replace the astra_inventory folder with the new edition.
  3. 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.
  4. Start the server. Player data is kept, because all editions use the same tables.

Troubleshooting

The inventory does not open

  • Check that oxmysql and your framework start before astra_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.

Entra no Discord