Installation

This guide takes you from a fresh copy of oxide-shops to a working shop system. You do not need to know how to program. Follow each step in order, and read the notes — they head off the most common mistakes.

Prerequisites

Before you start, make sure these resources are already on your server and working.

Required Resources

What is a "clothing/appearance resource"? It is the script your server already uses to let players change their outfit and looks (for example illenium-appearance, fivem-appearance, rcore_clothing, or your framework's built-in clothing). oxide-shops does not replace it — it asks it to save the changes a player buys at a barber, tattoo parlor, clothing store, or mask shop. The general store, weapon shop, pawn shop, and auction house do not need a clothing resource; only the four "styling" shops do.

Barber and tattoo shops need a bit more. They require a backend that exposes a rich appearance (hair and face detail) through the bridge. illenium-appearance, fivem-appearance, and rcore_clothing are verified to work. On a backend that only handles outfits, the barber and tattoo shops refuse gracefully (with a clear message) rather than wiping a player's look — clothing and mask shops still work fine.

Supported Frameworks

oxide-shops works with any framework that o-link supports. You install it once and it adapts to whatever you run.

Installation Steps

1. Extract the resource into your server's resources/ folder. If you keep Oxide resources together, a folder named [oxide] is a good home for it. The folder must be named exactly oxide-shops.

2. Add it to your server.cfg — this is the text file that tells your server which resources to start. Add this line in the correct place (see Load Order below):

   ensure oxide-shops

3. Register the supply items in your framework so player-owned barber/tattoo/mask/clothing shops can restock. See Adding the Supply Items.

4. Start (or restart) your server. On its first start, oxide-shops builds its own database tables automatically. You do not need to import any SQL by hand (see Database Setup). Note that a fresh install has no shops yet — the tables are empty until you add shops in the next step.

5. Create your shops in-game. As an admin, open /shop admin and create each store you want from the built-in template picker (all the familiar GTA stores — supermarkets, gas stations, gun shops, barbers, tattoo parlors, and more — are ready-made templates). Creating a shop is what places its shopkeeper and blip on the map. See Admin → The Admin Panel.

6. Configure anything you want to change in-game with /shop settings. There are no config files you need to edit for normal setup.

Load Order

Every Oxide resource follows the same four-tier load order in server.cfg. Use this structure exactly — the resource will misbehave if o-link starts after it.

# 1. Framework — everything your framework needs (qb-core, es_extended, qbx_core, etc.)
ensure qb-core

# 2. Scripts — your other resources (inventory, clothing, ox_target, etc.)
ensure ox_target
ensure illenium-appearance

# 3. o-link — the bridge. Starts after your framework/scripts, before any Oxide resource.
ensure o-link

# 4. Oxide resources — keep these together, ideally in a folder named [oxide]
ensure oxide-shops

• The only hard rule is that o-link comes after your framework and other scripts, and before oxide-shops.
• If you run several Oxide resources, put them all in a folder named [oxide] and you can start them together with ensure [oxide].

Adding the Supply Items

Player-owned service shops (barber, tattoo, mask, and clothing stores) run on a "supply" item — each haircut, tattoo, mask, or garment change uses up one unit of a small consumable, and the owner buys more from wholesale. Static (server-run) shops do not use supply, but you should still register these items so ownership works if you enable it.

Register these four items in your framework's item list. Icons for them ship inside oxide-shops/itemimages/ — copy those PNGs into your inventory resource's image folder if it uses one.

ox_inventory (data/items.lua):

['hair_product'] = { label = 'Hair Product', weight = 100, stack = true, close = true },
['tattoo_ink']   = { label = 'Tattoo Ink',   weight = 100, stack = true, close = true },
['mask_blank']   = { label = 'Blank Mask',   weight = 100, stack = true, close = true },
['fabric']       = { label = 'Fabric',       weight = 100, stack = true, close = true },

QBCore (qb-core/shared/items.lua):

hair_product = { name = 'hair_product', label = 'Hair Product', weight = 100, type = 'item', image = 'hair_product.png', unique = false, useable = false, shouldClose = true, description = '' },
tattoo_ink   = { name = 'tattoo_ink',   label = 'Tattoo Ink',   weight = 100, type = 'item', image = 'tattoo_ink.png',   unique = false, useable = false, shouldClose = true, description = '' },
mask_blank   = { name = 'mask_blank',   label = 'Blank Mask',   weight = 100, type = 'item', image = 'mask_blank.png',   unique = false, useable = false, shouldClose = true, description = '' },
fabric       = { name = 'fabric',       label = 'Fabric',       weight = 100, type = 'item', image = 'fabric.png',       unique = false, useable = false, shouldClose = true, description = '' },

ESX (run once in your database, then restart):

INSERT INTO items (name, label, weight, rare, can_remove) VALUES
('hair_product', 'Hair Product', 1, 0, 1),
('tattoo_ink',   'Tattoo Ink',   1, 0, 1),
('mask_blank',   'Blank Mask',   1, 0, 1),
('fabric',       'Fabric',       1, 0, 1);

The stores also sell ordinary items — water, bread, lockpicks, weapons, armor, and so on. Those items must already exist in your framework for a store to display and sell them. If a store shows an item by its raw name (like weapon_pistol instead of "Pistol") or refuses to sell it, that item is not registered in your framework. You can also change any store's item list in /shop admin to match the items you actually have.

Database Setup

In most cases you do nothing here. On its first start, oxide-shops creates all of its database tables automatically. Your database (the place your server stores saved data) just needs to be connected through oxmysql, which it already is if your framework works. (The tables start empty — you add the actual shops yourself in /shop admin, as described in the Installation Steps above.)

A ready-made SQL file is included at oxide-shops/sql/install.sql for reference or for admins who prefer to create the tables by hand. You only need it if your database user is not allowed to create tables automatically — in that case, import sql/install.sql into your database using your database tool (for example phpMyAdmin or HeidiSQL) before starting the resource.

Verification

1. Start your server and watch the console for errors mentioning oxide-shops. A clean start means the tables were created.
2. Join the server as a character.
3. As an admin, type /shop admin — the admin panel should open. If it says you do not have permission, see Permissions.
4. In the admin panel, create at least one shop from the template picker (for example a 24/7 supermarket). Confirm it saves without errors.
5. Open your map — the shop you just created should now show a blip.
6. Walk up to that shopkeeper (or into the store zone, for clothing/mask shops) and press your interaction key. You should see a Browse Shop option; selecting it opens the shop menu.

If a step fails, see Troubleshooting.

Next Steps

• Configuration — every setting and what it changes
• Features — how each shop type works
• Admin — the admin panel and commands