Installation Guide

How to get oxide-vending running on your server, one step at a time.

What You Need First

These three resources must already be installed and working on your server. They are free and most servers already have them:

Resource	What it does
`ox_lib`	A shared toolbox many scripts use for menus, text, and translations
`oxmysql`	Lets scripts talk to your database
`o-link`	The bridge that connects this script to your framework (QBCore, QBX, or ESX) and to your inventory, money, and targeting systems

Optional

Resource	What it does
`oxide-weather`	If installed, the NPC sales system follows your server's in-game clock (lunch rush at in-game noon, quiet at in-game night). Without it, the system uses real-world time instead. Either way works — this is not required.

Installation Steps

1. Add the resource to your server

Copy the oxide-vending folder into your server's resources folder.

2. Start it in your server.cfg

Open your server.cfg and make sure these lines exist, in this order. The order matters — oxide-vending needs the other three to be running before it starts:

ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-vending

3. Set up the database

The resource keeps its data (businesses, machines, stock, sales history) in your database. To create the tables it needs, run the file sql/install.sql against your database.

If you use a database tool like HeidiSQL or phpMyAdmin: open your server's database, choose the option to run or import an SQL file, and pick sql/install.sql. It is safe to run more than once.

This creates a set of tables that all start with vending_.

4. Look over the settings

The settings live in the config/ folder. You can open these with any text editor (Notepad++ or VS Code work well):

config/config.lua — main settings: prices, fees, the showroom location, machine durability
config/machines.lua — the machine types players can buy
config/items.lua — which items machines are allowed to sell, and their base prices
config/wholesale.lua — the bulk-order catalog
config/npc_sales.lua — the passive NPC sales system
config/progression.lua — business levels and rewards

The defaults work out of the box, but see the next step before going live. Configuration explains every setting.

5. Check the item names (important)

Machines can only sell items that actually exist on your server. The item names in config/items.lua and config/wholesale.lua are a starter list — some of them will not exist on your server, depending on your framework. An item that doesn't exist simply can't be stocked or sold, and wholesale orders for it will deliver something your players can't use.

How to check, per framework:

QBCore — your item list is in qb-core/shared/items.lua. Most of the starter list matches QBCore, but a few defaults do not exist in a stock QBCore install: water, juice, soda, bread, apple, candy_bar, chimpschips, and gps. Swap these for items you actually have (for example, QBCore uses water_bottle instead of water, and kurkakola is its soda), or add them as new items.
QBX — your item list is in ox_inventory/data/items.lua. A stock install includes water, coffee, grapejuice, sandwich, lighter, rolling_paper, bandage, painkillers, phone, radio, cryptostick, electronickit, and binoculars — but many of the QBCore-style names in the starter list (like water_bottle, kurkakola, tosti, twerks_candy, snikkel_candy, tablet, laptop, fitbit, gps) are not stock. Swap or add them.
ESX — where your items live depends on your inventory. If you use ox_inventory, check ox_inventory/data/items.lua. If you use the default ESX inventory, your items are in the items table in your database.

The simple rule: open your item list, search for each item name used in config/items.lua and config/wholesale.lua, and replace anything you can't find with an item you do have. Make sure the same name appears in three places — the machine whitelist (Config.ItemWhitelists), the base price list (Config.ItemBasePrices), and, if you want it orderable in bulk, the wholesale catalog (Config.WholesaleCatalog).

6. Leave the `html/` folder alone

The dashboard screen players see is included ready-to-use in the html/ folder. There is nothing to build or compile — just don't delete or rename anything in there.

Checking That It Works

After a server restart, run through this list:

Watch the server console while it starts. You should see no red errors mentioning oxide-vending, o-link, ox_lib, or oxmysql.
Open your in-game map. You should see a "Vending Machines" shop icon (if you left Config.Showroom.Blip.enabled = true).
Go to that location. There is an NPC with a clipboard — walking up and aiming at him should show an interaction option.
Register a test business through the NPC. A contract screen opens; signing it charges the registration fee and creates your business.
Buy a machine from the NPC, then place it: a see-through preview of the machine follows your aim, glowing green where it can go and red where it can't. Scroll to rotate it, press E to place it, or Backspace to cancel.
Stock the machine with one of your configured items, then buy from it as a player. You should pay cash and receive the item.
Type /vdb in chat as the business owner. The business dashboard should open.
If you kept the warehouse and wholesale features on, place a small bulk order from the dashboard and check that cardboard boxes appear on the wooden pallet near the showroom after the delivery timer (5 minutes by default).

If any step fails, see Troubleshooting.

Next Steps

Features — what the resource does, explained
Configuration — every setting
Admin — admin commands
Troubleshooting — common problems and fixes

On this page