ox_inventory: a slot-based inventory for FiveM servers

What it is, and what it is for

ox_inventory is described as a complete and modern inventory system for FiveM, providing a flexible slot-based inventory with support for shops, stashes, crafting, and vehicle storage.

The subject is the FiveM role playing framework, and the reason an inventory needs to be a separate project rather than a snippet is that in that setting the inventory is the hub of the economy. A player's money, their weapon, their documents, their vehicle keys, the contents of a stash, the stock of a shop: all of it is inventory state, and the rules about how it may be moved are the rules of the server's economy. Get them wrong and the economy has exploits; get them right and the server has a working game.

The word slot-based is the key structural decision, and it differs from the list-based model that most game inventories use. In a list model, an item is a record with a quantity, and the container has a count. In a slot model, the container has a fixed number of slots, each of which holds at most one item, and an item has to fit into a slot. The consequences are visible to a player: you can carry one rifle in a slot but not two, and the shape of what you carry depends on the container.

The other thing the readme is explicit about is framework compatibility. Four frameworks are listed as supported, including the project's own core and three third-party ones, and then there is a line that says plainly that compatibility or support for third-party resources is not guaranteed. That sentence matters more than it looks: an inventory is the interface through which every other resource on the server moves items around, so an inventory that changed its item registration format would break every other resource. Saying that third-party compatibility is not guaranteed is a warning to resource authors, not an admission of a bug.

The badges tell you the scale of it. There are download counts for the release and for the latest build, and three badges from a server-metrics service showing the rank of the resource, the number of servers running it, and the number of players. Those numbers describe an inventory that is in production on a large number of servers, which is the context in which the design decisions below make sense.

Server-side validation, and why synchronisation is the hard part

The first feature in the list is server-side security, and it says that interactions with items, shops and stashes are all validated.

That is the single most important line in the readme for anyone building on it, because in a client-authoritative design every rule about the inventory lives in the client, and a client can be modified. Moving the validation to the server means the client can only ask, and the server decides. The cost is a network round trip per action and a server that has to be fast, and for a game with a hundred players in a city that cost is real.

The third feature is the one that makes that cost manageable, and it is stated as a property: fully synchronised, allowing multiple players to access the same inventory. There is a demonstration video linked in the readme of two people reaching into the same container.

Think about what that requires. Two clients both believe they hold a particular item, or both believe a slot is empty, and they act at the same time. The server has to serialise those actions, tell both clients what happened, and make sure the two clients' views of the world converge. And it has to do that without the second player seeing a menu that the first player is already using.

The natural implementation is a session or a lock per container: the first request takes it, the second is told to wait, and the state is pushed to everyone watching. That is what a synchronised container costs, and it is why the readme treats it as a headline feature rather than as an implementation detail. A shared stash that is not synchronised is a duplication bug, and duplication bugs in an inventory are unfixable after the fact.

The second feature is logging, and the readme names the events: purchases, item movement, and item creation or removal. That list is exactly the set of actions that change the economy, and it is exactly the set an operator needs to answer the two questions that matter, which are who took the thing and when. It also happens to be the set of events a cheating player would try to trigger without being there, which means the log is simultaneously an operational tool and a detection tool.

The fourth feature is the one that keeps the inventory from having to know about the rest of the game. It supports player-owned vehicles, licences, and group systems implemented by the frameworks. In other words, the inventory asks the framework who owns this vehicle and whether this player holds that licence, rather than implementing ownership itself. That is what makes the four-framework support list possible at all, and it is why the framework that implements those systems is the one the readme tells you to check first.

Items: slots, metadata and durability

The items section is the longest part of the feature list, and each entry answers a question a server operator has to answer.

Items are stored per slot, with customisable metadata to support item uniqueness. That is the consequence of the slot-based model made explicit. If a container has twenty slots, then it holds twenty item records, and each record has a slot number. And the metadata is what makes two of the same weapon distinguishable: a key card, a serialised firearm, a signed document, a phone with a number on it. The metadata is customisable, which means a server can decide what distinguishes its items, and the inventory stores and carries that metadata wherever the item goes.

The second entry overrides the default weapon system with weapons as items. That is a bigger change than it sounds. In the framework's default, a weapon is not inventory state; it is a component of the player, and it is not an object that can be dropped, stored, or found. Turning weapons into items means a weapon can be in a stash, in a car, in a shop's stock, in another player's hands, and that the same rules about metadata, durability and capacity apply to a rifle as to a document.

The third entry adds weapon attachments and an ammunition system, including special ammunition types. Attachments are items with a relationship to the weapon they are fitted to, and ammunition is a consumable item with a type, which is what makes special ammunition meaningful rather than decorative.

The fourth is durability, allowing items to be depleted or removed over time. That is a mechanic rather than a feature, and it is the mechanic that makes maintenance an activity in the game rather than a chore outside it. It also has a systems consequence: an item with durability has state that changes without anybody touching it, which means the item's owner has to learn it. The readme says items can be removed over time as well as depleted, which is a different behaviour again.

The fifth entry is an internal item system that provides secure and easy handling of item use effects. This is the server-side execution of what happens when a player uses something. A consumable, a key, a document to sign, a bag to open: each of those is an effect, and the effects have to run on the server, because a client-side effect is a client-side exploit. The internal system is where they live.

And the last entry is compatibility with third-party framework item registration, which is the seam that the earlier warning about third-party resources refers to. The inventory consumes items registered elsewhere, and the compatibility is a matter of the registration format agreeing.

Shops, stashes, and the containers between them

The shops section is two lines, and both are about access rather than about commerce.

Access can be restricted based on groups and licences. So a shop can be open to everybody, or to members of a group, or to holders of a particular licence, and the check is made on the server like everything else.

And support for different currencies for items, with black money and poker chips given as examples. That single line is doing more work than it appears to. If every item has one price in one currency, then the economy has one unit of account and every transaction is comparable. If different items are priced in different currencies, then a currency becomes a thing in the world rather than a number, and the interesting economic questions appear: who converts, at what rate, and is the rate a market or a rule.

The stashes section is longer, and it is the part that shows how the inventory is used by the rest of the game.

Personal stashes can link a stash to a specific identifier or create per-player instances. The distinction is between a stash that everyone shares and a stash that each player has their own of, and a server will want both.

Access can be restricted by groups, in the same way as shops. New stashes can be registered from any resource, which is the extension point: a resource that wants to add a container declares it, and the inventory provides the storage and the access rules.

Containers allow access to stashes when using an item, like a paperbag or a backpack. So a player can pick up a bag, and the bag becomes a container they carry, and the bag's contents are inventory items. That is a recursive structure, and it is why the slot model and the metadata model have to be right: a bag in a slot containing items in slots.

Gloveboxes and trunks can be accessed for any vehicle, and random item generation happens inside dumpsters and unowned vehicles. That last one is a world-building detail with a systems consequence: if a dumpster can contain items, then a server has to decide what is in it, and the answer cannot be the same every time, or the dumpsters are worthless. Random generation means a player has to check, which is a small activity that produces a reward.

And the vehicle storage mentioned in the summary is the same mechanism again. A vehicle is a container with an identifier, and every one of these cases is the same idea applied to a different object: something that holds items, has an owner or an access list, and can be carried around.

The repository, and the shape of a game resource

The top level of the repository shows what a FiveM resource looks like, and it is a shape worth understanding because it differs from an ordinary library.

There is a manifest file, which is how a game framework discovers a resource and knows what to run. There is an initialisation file, and then a client file and a server file at the root. The client and the server split is the framework's model of the world: the client is what runs on a player's machine, the server is what runs once for everybody. An inventory that validates on the server is one whose client file is mostly a view, and that is visible in the layout.

Then there is a modules directory, which is where the feature areas live, and it corresponds to the feature list in the readme. A data directory holds the definitions, which for an inventory means the item definitions and the shop and stash declarations, and that is where a server author's configuration work actually happens. There is a locales directory, so the interface is translated, which for a resource used on servers in many countries is a practical requirement rather than a nicety. There is a setup directory, which is the installer that a server operator runs once, and a web directory, which is the interface the player sees in a browser window rather than in the game.

That last one is worth pausing on. A modern FiveM inventory does not draw its menus in the game's own rendering; it opens a web interface, which is why there is a web directory and why there is a separate client file. The consequence for a resource author is that the interface is written in web technologies and the game side is written in Lua, and the two talk over the network. It is a much better interface than the engine's own menu system, and it is also the reason the project has a dependency on web tooling at all.

The development files are the usual set for a Lua project. There is a configuration for the language server, which is how a Lua project gets the type information that the language server needs, and it is in a data format with comments. There is an editor configuration, an ignore file, and a directory with editor settings.

And there is the legal material, which is more substantial than a small project usually carries. There is a notice file for additional information and legal notices, and the contribution document points at a contributor licence agreement, which is the piece a company needs to sign before contributing code to a copyleft project. The readme's link to both is at the very top, before the documentation, which is where a project that cares about the provenance of its contributions puts them.

What the metrics say, and what the project is

The badge row deserves a second look, because three of the badges are not about the code at all.

There are the download counts, for the latest release and for the current build, which are the conventional popularity measures for a downloadable resource. And then there are three from a service that tracks game servers: the rank of the resource, the number of servers running it, and the number of players on those servers.

That third group is a different kind of number, and it is the interesting one. A download count tells you how many times somebody has installed the resource. A player count tells you how many people are using it right now, on live servers, in a live game. For an inventory, that number is a proxy for how much of the FiveM role playing community runs on it, and it is a number that changes every day.

It also reframes the design decisions. A resource installed on a handful of hobby servers can be tolerant of a bug that a resource running on thousands of servers cannot, because the blast radius of an inventory bug is the economy of a server: an item that duplicates, or a shop that sells below cost, or a stash that two people can open at once, breaks the game for every player on that server rather than for one. The emphasis on server-side validation, on synchronisation, and on logging the economy-changing events is exactly the emphasis you would expect from a project that is measuring itself in live players.

The second thing the badge row says is about the release process. The download links point at a single packaged archive from the releases, and the version badge tracks it. There are tagged releases in the two series with a patch-level cadence of several releases a quarter, and the last push is recent, which is a project that is maintained rather than merely popular.

And the project is copyleft, which is the right licence for a resource that other server authors redistribute. The whole point of a shared resource is that server operators download it, modify it, and share their modifications, and the copyleft licence is what keeps the sharing going in one direction rather than stopping it. That is also why the notice file and the contributor agreement exist: they are the paperwork that lets a company contribute to a copyleft project without a lawyer having to invent something from scratch.

So the whole picture is a piece of infrastructure that is treated as infrastructure: server-side rules, live synchronisation, an audit trail, translations, an installer, a web interface, and the legal scaffolding to let other people's companies contribute to it.

Editorial conclusion

ox_inventory fits a FiveM server operator who wants a complete inventory rather than a minimal one, and who wants the framework-specific parts of the game left to the framework. It does not fit a server author who needs to control every item rule from configuration alone, since the behaviour is code. Verify first which of the four supported frameworks your server runs, and that the item registration of the other resources on your server will work with it, because the readme explicitly does not guarantee compatibility with third-party resources, and that you read the notice and contribution files before vendoring the code, because the project has a contributor licence agreement as well as a copyleft licence.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. overextended/ox_inventory on GitHub
3. Project website
4. README
5. Releases