Free script · v1.0.0
KD Vendingmachine
Immersive, themed vending machines for FiveM. Every machine gets its own realistic interface. Walk up, press the buttons, pay with cash or card, watch your can drop, then reach into the tray and grab it.
ZIP from GitHub · MIT license
Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.
- QBox
- QBCore
- ESX
- Standalone
- ox_inventory
- ox_target
- qb-target
- Lua 5.4
- 6machine types
- 30+items ready
- 0required dependencies
- 0.00 msidle with target
A unique UI for every machine
It isn't one menu with a different colour. Every machine has its own hardware, its own buttons and its own sounds.
-
See it in the preview at the top
eCola
Red soda front, lit sample window, selection buttons, bill acceptor and contactless reader.
prop_vend_soda_01
-
View larger image
Sprunk
Same hardware as eCola, with Sprunk lime branding.
prop_vend_soda_02
-
View larger image
Raine
A clean, glacier-blue water machine.
prop_vend_water_01
-
View larger image
Snacks
Glass-front machine with spiral coils, shelf tags and an A1–D6 keypad. You can also type on your keyboard.
prop_vend_snak_01prop_vend_snak_01_tu
-
View larger image
Coffee
Touchscreen: drink, cup size (changes price), sugar and strength, a brewing progress ring, a cup bay with a pour animation and steam.
prop_vend_coffe_01
-
View larger image
Cigarettes
70s pull-knob machine: wood grain, chase-light marquee, insert coins, then pull a chrome knob.
prop_vend_fags_01
What you get
Everything that makes a vending machine feel like a real machine, and everything that keeps your economy safe.
-
Physical animations
The player walks up and turns to face the machine, presses buttons while the UI is open, and reaches down into the tray for the product. The real prop (can, bottle, chocolate bar, chips, coffee cup, cigarette pack) is in hand and visible to other players.
-
Machine feedback
LCD/VFD displays, card reader LEDs, a bill sliding into the acceptor, the coil spinning, the product dropping and bouncing in the tray, and a flap you push to take it.
-
Procedural sound effects
Key beeps, coins, card approval, motor hum, the thunk of the drop, brewing and knob ratchets. Made with Web Audio, so no audio files are shipped.
-
Framework agnostic
QBox, QBCore, ESX, or standalone with ox_inventory. Detected automatically.
-
Works with your interaction
ox_target, qb-target, ox_lib text UI or native GTA help text (~INPUT_CONTEXT~). The best one you have is picked.
-
Server authoritative
Prices, stock, distance, payment methods, carry checks and cooldowns are all validated server-side. If the item can't be added, the money is refunded automatically.
-
Per-machine stock
Every physical machine has its own stock with automatic restocking. Admins can refill everything with /restockvending.
-
Discord logging
Purchases and suspicious requests can be logged to a Discord webhook.
-
Extra placements
Spawn additional machines anywhere from the config.
-
English and Danish
Both locales are included, and adding your own is easy.
-
Browser dev preview
Open web/index.html in Chrome or Edge to click through every machine without starting the game.
Requirements
No required dependencies beyond your framework and inventory.
- Framework (one of)
- qbx_core · qb-core · es_extended · or standalone with ox_inventory
- Inventory
- ox_inventory, qb-inventory (and forks), or ESX default
- Server
- OneSync enabled (used for server-side distance checks)
Installation
From download to a working machine in a couple of minutes.
-
Drop it in resources
Rename the folder to kd-vendingmachine and drop it into your resources folder.
-
Add the items
Add the items to your inventory. See the table below.
-
Ensure the resource
Add it to your server.cfg after your framework, inventory and target:
ensure kd-vendingmachine -
Admin access (optional)
Give admins the restock permission:
add_ace group.admin kdvending.admin allow -
Restart
Restart your server. The console prints this, and any item missing from your inventory is listed in a warning:
[kd-vendingmachine] v1.0.0 loaded · framework: qbox · inventory: ox_inventory
Items
The default config sells ~30 items. Ready-to-paste definitions are in the /install folder.
| Inventory | File | Where it goes |
|---|---|---|
| ox_inventory (QBox / ESX / standalone) | install/ox_inventory.lua | ox_inventory/data/items.lua. Includes consume anims, props and status values. |
| qb-inventory | install/qb-core.lua | qb-core/shared/items.lua |
| ESX default inventory | install/esx.sql | Run against your database |
Already have water, coffee, sandwich or lighter? Skip those. You can also change any machine to sell your existing items. Just edit the name field in the config.
Running it on your server?
Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.
Configuration
There are two config files. One is shared with clients, the other stays on the server.
| File | Contents | Sent to clients? |
|---|---|---|
config/config.lua | Machines, items, prices, UI, animations, interaction | Yes |
config/server.lua | Webhook, max distance, admin ace, logging | No |
General
Config.Locale = 'en' -- 'en' | 'da'
Config.Framework = 'auto' -- 'auto' | 'qbox' | 'qbcore' | 'esx' | 'standalone'
Config.Inventory = 'auto' -- 'auto' | 'ox_inventory' | 'framework'
Config.Interaction = 'auto' -- 'auto' | 'ox_target' | 'qb-target' | 'textui' | 'native'
Config.Notify = 'auto' -- 'auto' | 'ox_lib' | 'framework' | 'native'
Config.InteractDistance = 1.6
Config.AlignPlayer = true -- walk up to the machine before the UI opens
Config.NetworkedProps = true -- others can see the product in your hand
Config.Cooldown = 1500 -- ms between purchases (server enforced)
Payment & stock
Config.Payment = { cash = true, bank = true } -- default, override per machine
Config.Stock = {
enabled = true,
default = 12, -- per slot, override with `stock = n` on an item
restockMinutes = 30,
}
Stock is tracked per physical machine: two eCola machines side by side each have their own stock.
Interface
Config.UI = {
currency = '$',
sound = true,
volume = 0.35,
showBalance = true, -- show cash / bank under the payment modules
autoTake = 8000, -- auto-grab after X ms if the player doesn't click the tray (0 = off)
images = 'drawn', -- 'drawn' | 'inventory' | 'nui://my-images/%s.png'
}
images | Result |
|---|---|
'drawn' | Stylised CSS products (cans, bottles, bars, chips, cups, packs) coloured per item. Works with zero setup and matches the machine art. |
'inventory' | Uses your inventory's item images (ox / qb / ps / lj inventory auto-detected). Falls back to drawn if an image is missing. |
| custom string | Any URL template containing %s (replaced with the item name). |
Adding or editing a machine
Config.Machines.mymachine = {
label = 'Energy Machine', -- target label / notifications
brand = 'Junk', -- printed on the machine
tagline = 'The quick fix',
layout = 'soda', -- 'soda' | 'glass' | 'coffee' | 'retro'
theme = 'sprunk', -- 'ecola' | 'sprunk' | 'raine' | 'snack' | 'coffee' | 'redwood'
models = { 'prop_vend_soda_02' }, -- each model can only belong to one machine
animation = 'tray_low', -- key from Config.Animations
icon = 'fa-solid fa-bolt',
payment = { cash = true, bank = false }, -- optional
items = {
{
name = 'junk_energy', -- inventory item
label = 'Junk Energy',
price = 6,
kind = 'can', -- drawn shape: can | bottle | bar | bag | candy | cup | pack
color = '#1b1b1b', -- main colour
accent = '#b6ff00', -- label / stripe colour
prop = 'can', -- hand prop, key from Config.Props
stock = 20, -- optional
-- image = 'https://...', -- optional, overrides Config.UI.images
-- metadata = { quality = 100 }, -- optional, ox_inventory metadata
},
},
}
Coffee-style machines can have sizes that multiply the price (validated server-side):
sizes = {
{ label = 'S', name = 'Small', multiplier = 1.0 },
{ label = 'M', name = 'Medium', multiplier = 1.25 },
{ label = 'L', name = 'Large', multiplier = 1.5 },
},
Animations
Every machine uses an animation preset. You can tweak them or add your own. Hand props live in Config.Props and are referenced by name from items. Invalid models are skipped with a console warning, so nothing breaks.
Config.Animations.tray_low = {
align = vec3(0.0, -0.78, 0.0), -- where the player stands (machines face -Y)
browse = { dict = 'anim@heists@keypad@', clip = 'idle_a', flag = 49 }, -- loop while UI is open
press = { dict = 'anim@heists@keypad@', clip = 'exit', flag = 48 }, -- confirm purchase
grab = { dict = 'pickup_object', clip = 'pickup_low', flag = 0,
propAt = 0.36, -- anim phase where the product appears in the hand
stopAt = 0.92, -- anim phase where the grab ends
hold = 900 }, -- ms the product stays in hand afterwards
}
Extra placements
Config.Placements = {
{ machine = 'coffee', coords = vec4(-1199.61, -884.82, 12.81, 124.0) },
{ machine = 'snacks', coords = vec4(441.32, -979.64, 29.69, 180.0), model = 'prop_vend_snak_01_tu' },
}
API
Exports and events, so you can build on it from your own scripts.
Client exports
-- Open the UI for a machine entity (e.g. from your own target / interaction script)
exports['kd-vendingmachine']:OpenMachine(entity)
-- Is the UI currently open?
local open = exports['kd-vendingmachine']:IsOpen()
-- Force close (the player still grabs anything they paid for)
exports['kd-vendingmachine']:CloseMachine()
Server exports
-- Refill every machine
exports['kd-vendingmachine']:Restock()
-- Current stock of a specific machine
local stock = exports['kd-vendingmachine']:GetStock('ecola', vec3(x, y, z))
Server events
-- Fired after every successful purchase
AddEventHandler('kd-vendingmachine:purchased', function(source, data)
-- data.machine, data.item, data.price, data.payment, data.coords
end)
Commands
| Command | Permission | Description |
|---|---|---|
/restockvending | kdvending.admin (or server console) | Refill every machine |
Security
The client never decides anything that matters. For every purchase the server:
- checks the player is within ServerConfig.MaxDistance of the machine
- verifies the item belongs to that machine and takes the price from the config, never from the client
- validates the payment method and cup size
- checks stock, inventory space and balance
- removes the money first, then adds the item, and refunds if adding the item fails
- enforces a per-player cooldown
- logs anything suspicious to the console and, optionally, a Discord webhook
FAQ
The most common questions. Missing an answer? Ask on Discord.
Nothing happens when I target a machine
Make sure kd-vendingmachine starts after your target resource. With Config.Debug = true the F8 console prints which interaction mode was picked.
"Not enough money" / "You cannot carry that" even though I can
Check that the item exists in your inventory. Missing items are listed on resource start. Unknown items fail the carry check.
The player doesn't line up with the machine
Adjust align in the animation preset. y is the distance in front of the machine (negative = in front). You can also disable walking up with Config.AlignPlayer = false.
Can I use my own vending machine props / MLO machines?
Yes. Add the model name to a machine's models list, or create a new machine entry. Any prop works.
Does the UI work without internet (fonts)?
Fonts load from Google Fonts. Without internet the UI falls back to system fonts and still works.
Can I modify it and use it on my server?
Yes. It is MIT licensed: use it, modify it, ship it. Credit is appreciated but not required.
Ready for a drink?
Free and open source under the MIT license. Use it, modify it, ship it. Need something custom? Ask on Discord. Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.