Features

What oxide-vending does and how the pieces fit together.

The Big Picture

Players visit a showroom NPC, register a vending business, and buy vending machines. They place those machines anywhere in the world, fill them with items, and set their own prices. Other players buy from the machines — and a built-in NPC economy quietly generates sales even when nobody is around. Owners manage everything (money, stock, staff, stats) from a dashboard screen.

The resource works on QBCore, QBX, and ESX. All framework-specific things — who the player is, their items, their money, their notifications — go through o-link, so there's nothing framework-specific to set up in this resource itself.

Starting a Business

At the showroom, a player can:

• see what a starting business gets (machine limit, starting machine type)
• pay the registration fee ($5,000 by default)
• choose a business name
• sign the contract on a registration screen

The default rules in Config.Business:

• registration costs $5,000
• each character can own one business
• characters on the same account can each own their own business
• there is no server-wide cap on how many businesses can exist (MaxBusinesses = 0 means unlimited)

Employees

Owners can hire other players and give them one of three roles. Each role is a bundle of permissions:

The owner can do everything. The role permissions can be changed in config/config.lua.

Machines

The four machine types

Each type comes with one or more looks to choose from (Sprunk machine, eCola machine, snack dispenser, and so on) — defined in config/machines.lua. Only drinks machines are available to a brand-new business; the rest unlock as the business levels up.

Placing a machine

Placement is aim-and-click:

1. The player starts placement from the showroom or their owned-machine list.
2. A see-through preview of the machine appears where they aim — green where it can be placed, red where it can't.
3. Scroll wheel rotates the preview (5° per notch).
4. E places it. Backspace cancels.

A spot is refused if it's too far from the player, too close to another machine, or inside a no-placement zone you've configured (for example, around a police station).

Wear and repair

Machines wear down a little with every sale (a default machine breaks after roughly 200 player sales if never repaired). The owner gets a warning when durability drops below 20%, and a broken machine stops selling until it's repaired. Repairs cost a flat fee per machine type ($400–$1,500 by default). All of this can be tuned or turned off in Config.Durability.

A machine is always in one of three states: active (selling), inactive (switched off), or broken (needs repair).

Stock, Prices, and Sales

What machines can sell

Each machine type has a whitelist of allowed items in config/items.lua — drinks machines sell drinks, snack machines sell snacks, and so on. The item also has to actually exist on your server (see Installation, step 5).

Setting prices

Every item has a base price in config/items.lua, and owners choose their own selling price within an allowed range around it. A new business can price between 0.9x and 1.5x of base price; that range widens as the business levels up (down to 0.75x and up to 3.0x at max level). New stock starts at 1.5x base price until the owner changes it.

When a player buys something

1. The item leaves the machine's stock
2. The buyer pays in cash
3. The item goes into the buyer's inventory
4. The money is added to the machine's takings and the business
5. The sale is recorded in the transaction history
6. The machine wears down slightly
7. The business earns XP toward its next level

The Business Balance

Each business has its own money, kept by this resource — no separate banking script is needed or used.

• sales revenue flows into the business balance
• the owner (and employees with permission) can deposit into it or withdraw from it
• deposits and withdrawals move money to and from the player's personal bank account

The Dashboard

Owners and employees open the dashboard with /vendingdashboard, the shorter /vdb, or from the showroom. It has five areas:

Wholesale, Pickup, and the Warehouse

Ordering in bulk

Instead of buying items one by one, businesses can order stock in bulk from the dashboard. Bulk prices come from config/wholesale.lua and carry a 20% markup by default, which shrinks as the business levels up. Orders arrive after a short delivery wait (5 minutes by default).

The pickup pallet

Deliveries arrive as physical cardboard boxes on a wooden pallet near the showroom. Walk up to a box, hold to collect it, and the items go to whoever collects. Boxes survive server restarts. Only the person who ordered, or an employee with stocking permission, can collect a business's boxes.

The warehouse

At business level 3, a business can buy a warehouse for $50,000 (paid from the business balance). The warehouse is a private storage interior:

• entry is through a keypad — the business gets a 4-digit code, and the owner can change it
• each business gets its own private copy of the interior (two businesses never see each other inside)
• it holds up to 5,000 items across up to 50 different item types by default
• anyone with the code can enter and deposit or withdraw items, which makes restocking runs much faster than carrying everything by hand

Entering a wrong code too many times locks that player out for a few minutes.

Leveling Up

Businesses have 10 levels. Moving up a level needs both enough XP and enough lifetime revenue — an active business that isn't earning, or an earning business that isn't being worked, won't level.

Almost everything earns XP: sales, stocking, collecting, placing machines, hiring, repairs, wholesale orders, a daily bonus with a 7-day streak, plus one-time milestone bonuses (first $1,000, 100th sale, and so on).

Each level raises some mix of: how many machines and employees the business can have, which machine types it can buy, how far prices can stretch, the wholesale discount, and a bonus on NPC sale revenue.

See Progression for the full tables.

NPC Sales (Passive Income)

Machines make sales on their own, simulating foot traffic. No actual pedestrians are involved in the money side — the server periodically rolls a chance for each active, stocked machine. That chance depends on:

• the time of day (lunch rush is busy, 3 AM is dead)
• where the machine is (Legion Square sells far better than Sandy Shores)
• the machine type (drinks sell fastest, electronics slowest)
• how the prices compare to base price (greedy pricing = fewer sales)
• how full and varied the machine is
• nearby competing machines of the same type (cheapest wins)

As a purely cosmetic touch, nearby pedestrians may walk up and animate at a machine when a sale happens — this can be turned off without affecting the income.

See NPC Sales for the details and the math.

Safety Nets

The resource protects itself against abuse and bloat:

• all important actions are checked and rate-limited on the server, so a malicious client can't spam purchases, placements, or registrations
• old transaction records are automatically cleaned up after 90 days (configurable, or keep forever)
• admins get a full toolkit of commands for inspecting and fixing things — see Admin

Next Steps

• Installation
• Configuration
• Progression
• NPC Sales
• API Reference