Skip to content

Getting Started

Warning

Documentation is still being improved - you may find some information lacking or missing.

This resource is being designed with the intention of providing advanced functionality while remaining easy to use, however it is not recommended for beginners. You must possess a basic understanding of coding and the ability to read; otherwise you should not install this resource.

Dependencies

OxMySQL

We utilise our own resource to communicate with MySQL databases via the node-mysql2 package. The backend is actively maintained and updated unlike the package used by mysql-async, providing improved performance, security, and features. We provide full backwards compatibility with mysql-async and build for the current Cfx architecture.

GitHub Documentation


Lua Library

A resource designed to provide reusable functions that can be loaded into any resource with simple variable declarations rather than through fxmanifest.
Still a work in progress.

Currently used for

  • SetInterval
  • Server Callbacks
  • Table utilities (contains, matches)
  • Requesting models, animations, etc.
  • Disabling control actions

GitHub


Production build

The interface is written in TypeScript using the React framework, so the code included in the repository will not work. You either need to build the package yourself (more information in guides, or download a release.

GitHub

Optional resources

qtarget

A high performance targeting solution based on bt-target, and the basis for qb-target.
It is being updated alongside Ox Inventory to improve support as well as add compatibility when using QBCore or migrating from bt-target.
All stashes and shops will utilise PolyZone's instead of markers to interact with them.

Attention

If you wish to use it first you must ensure that qtarget is enabled in the resource convars. You will need to enable compatibility manually by adjusting your config - more information provided below.

You must start qtarget before the inventory and after es_extended.

GitHub Documentation

NPWD

A standalone and feature-rich phone created by Project Error.
The inventory will handle disabling the phone when the player has no item, and supports toggling the phone through item use.

GitHub Documentation

Configuration

You can add these settings directly to your 'server.cfg', or create a new (or multiple) file to load with 'exec'.
You do not need to specify convars when you are not changing the values, as they will default.

# Activate specific event handlers and functions (supported: ox, esx)
setr inventory:framework "esx"

# Load specific language file from data/locales
setr inventory:locale "en"

# Number of slots for player inventories
setr inventory:slots 50

# Maximum carry capacity for players, in kilograms
setr inventory:weight 30000

# Weapons will reload after reaching 0 ammo
setr inventory:autoreload false

# Blur the screen while accessing the inventory
setr inventory:screenblur true

# Trim whitespace from vehicle plates when checking owned vehicles
setr inventory:trimplate true

# Integrated support for qtarget stashes, shops, etc
setr inventory:qtarget false

# Default hotkeys to access primary and secondary inventories, and hotbar
setr inventory:keys ["F2", "K", "TAB"]

# Enable control action when inventory is open
setr inventory:enablekeys [249]

# Jobs with access to police armoury, evidence lockers, etc
setr inventory:police ["police", "sheriff"]

# Item prices fluctuate in shops
set inventory:randomprices true

# Compare current version to latest release on GitHub
set inventory:versioncheck true

# Loot will randomly generate inside unowned vehicles and dumpsters
set inventory:randomloot true

# Minimum job grade to remove items from evidence lockers
set inventory:evidencegrade 2

# Stashes will be wiped after remaining unchanged for the given time
set inventory:clearstashes "6 MONTH"

# Set the contents of randomly generated inventories
# [item name, minimum, maxiumum, loot chance]
set inventory:vehicleloot [
    ["cola", 1, 1],
    ["water", 1, 1],
    ["garbage", 1, 2, 50],
    ["panties", 1, 1, 5],
    ["money", 1, 50],
    ["money", 200, 400, 5],
    ["bandage", 1, 1]
]

set inventory:dumpsterloot [
    ["mustard", 1, 1],
    ["garbage", 1, 3],
    ["money", 1, 10],
    ["burger", 1, 1]
]

# Set datadog API key for inventory logging (https://app.datadoghq.com/organization-settings/api-keys)
set datadog:key ""

# Set server intake (https://docs.datadoghq.com/api/latest/logs/#send-logs)
set datadog:site "datadoghq.com"

# Set server hostname
set datadog:hostname "FXServer"


add_principal group.admin ox_inventory
add_ace resource.ox_inventory command.add_principal allow
add_ace resource.ox_inventory command.remove_principal allow

Installation

  • Use a compatible version of ESX Legacy (1.6.0+)
  • Execute the query inside install.sql and vehicle.sql
  • Open fxmanifest.lua and uncomment server_script 'setup/convert.lua'
  • Start the server and execute the convertinventory command from the console
  • Remove the conversion file
  • Execute the query inside upgrade.sql and vehicle.sql
  • Open fxmanifest.lua and uncomment server_script 'setup/convert.lua'
  • Start the server and execute the convertinventory linden command from the console
  • Remove the conversion file

This will not update your items file and old items may be incompatible; refer to documentation for item creation

Work in progress.
Refer to the "bridge" module to get an idea of how you setup support for any framework.
Modifications will need to be made for licenses, owned vehicles, and jobs.

Attention

You should restart your server after the first startup to ensure everything has been correctly setup

Upgrading ESX

Ox Inventory provides a complete suite of tools to replace the built-in items and inventory system from ESX, and is not intended to be used with resources designed around it.

  • ESX loadouts do not exist - resources that use them need to remove references or be modified to look for the weapon as an item
  • Stashes from resources such as esx_policejob, esx_ambulancejob, etc. should be removed
  • Shops from esx_shops or the armoury from esx_policejob should be removed
  • Resources like esx_inventoryhud, esx_trunkinventory, esx_addoninventory, etc. should be removed

Optional optimisation

All item related functions from xPlayer, such as xPlayer.getInventoryItem, have been modified for compatibility purposes; however they are considered deprecated.

The reasoning is fairly simple - there's now additional function references and overhead to consider. Fortunately, the new Inventory functions can be used directly and offer a great deal of improvements over the old ones.

You should read through the modules section for further information, but the following should give you a decent idea.

xPlayer.getInventoryItem and xPlayer.removeInventoryItem

if xPlayer.getInventoryItem('acetone').count > 2 and xPlayer.getInventoryItem('antifreeze').count > 4 and xPlayer.getInventoryItem('sudo').count > 9 then 
    xPlayer.removeInventoryItem("acetone", 3)
    xPlayer.removeInventoryItem("antifreeze", 5)
    xPlayer.removeInventoryItem("sudo", 10)
end

Add the following code somewhere in your resource to cache the exports metatable.

local ox_inventory = exports.ox_inventory

You will be able to reference any functions exposed through the export.

local items = ox_inventory:Search(source, 'count', {'acetone', 'antifreeze', 'sudo'})
if items and items.acetone > 2 and items.antifreeze > 4 and items.sudo > 9 then
    ox_inventory:RemoveItem(source, 'acetone', 3)
    ox_inventory:RemoveItem(source, 'antifreeze', 5)
    ox_inventory:RemoveItem(source, 'sudo', 10)
end

Back to top